These collections of programs take a dataset of TLEs (two line element sets) of a number of satellites (ex. Starlink satellites), groups them into their respective orbital shells, and sorts them through their RAAN to place satellites that are next to each other in the sky, next to each other in their respective entry.
This can be used to develop ISL (inter-satellite link) diagrams between the satellites, as many Starlink satellites use ISLs (through both intraplane - on the same plane - and interplane - neighboring planes - links) to communicate with each other. By sorting the satellites into their respective altitude and inclination shells, followed by RAAN planes, it gives us a better picture of how they're positioned in the sky. By sorting the plane through mean anomaly angles, it allows us to create a visual of the exact order that they're in.
Go check out my research team and our published paper on satellite networking! Our papers were accepted at TRPC 53 and IMC 2025.
- Clone the repository
git clone https://github.com/etumanova/satelliteTLEs.git- Install the dependencies:
- install sgp4: sgp4 easily analyses the TLE data set and provides you with the needed orbital elements (for example: altitude, inclination, raan, etc.)
pip install sgp4-
install sklearn (to run the DBSCAN) ——— depends on your computer, follow this link to download it properly
-
ensure that you have numpy ——— download the type of numpy that you prefer: either for speed or cross-platform manager
The best place to receive TLE data is through Celestrak, which is updated regularly and contains the most accurate information for all publicly available data. For example, if you want to receive the TLE dataset for all Starlink satellites, you can click on the link that says 'Starlink', which will take you to a 3-line data set, including the satellite name and the TLE of the satellite. This type of data set is the kind that the programs are based on.
It's helpful to update the TLE dataset you're using every once in a while, but since this program only sorts the satellites into their shells, planes, and spots, the result shouldn't change depending on when you download the dataset.
The collection of code runs two main programs: grouping.py and dbscan.py
- grouping.py categorizes the shells and planes through rounding to a specific value for all of the orbital elements. You can run it by navigating to the src folder and running:
python grouping.py <tle_file> [--show-top N]Where <tle_file> is a file with 3-line TLE sets (name, line1, line2), and --show-top N will print the top N shells with the most satellites.
- dbscan.py categorizes the shells through running a dbscan on all of the satellites: which looks at the different clusters, and, depending on a variable (eps) that you provide for it, will group them into clusters with their nearby satellites.
Navigate to the src folder and run:
python group_dbscan.py <tle_file> [--show-top N] [--use-dbscan]With the same descriptions of <tle_file> and --show-top N.
If you ever forget, most instructions are listed as comments at the top of the main files (src/grouping.py and src/dbscan.py). Check them out!
- How do satellite orbital shells and planes work?
For each collection of satellites, there are thousands of them in the sky. Keeping them all moving randomly at the same altitude would inevitably cause a problem, so they are split up into "shells" (which live at different altitudes and move in different directions). This direction is measured by the angle in which they cross the equator, which is called the inclination angle. Within these shells, there are about 300-1500 satellites (depending on how "popular" the shell is). All of these satellites can't be on the same line, so they are split up among "planes", with about 20 satellites per plane.
These planes all appear with the same inclination angle and altitude, but cross the equator at different points. This point is called the RAAN (Right Ascension of Ascending Node).
Shells and planes collect satellites into organized groups, allowing these satellites to access and provide internet for a big part of the world.
- How does this program organize all of that?
Inclination + Altitude: These two define the orbital shell.
- Altitude sets the orbital height (roughly the radius of the orbit).
- Inclination sets the tilt relative to Earth’s equator.
RAAN (Right Ascension of Ascending Node): Sets where the orbital plane crosses the equator.
- If two satellites have the same altitude and inclination but different RAANs, they’re in different orbital planes within the same shell.
Mean Anomaly (or True Anomaly at epoch): Defines the satellite’s position along its orbit.
- This is what spaces them out along each orbital plane.
So the hierarchy is basically:
- Shell: (inclination + altitude)
- Plane within shell: (RAAN)
- Slot within plane: (mean anomaly)
- What are TLEs and how do I read them?
TLEs might seem like a bunch of numbers, but they all mean something important once you understand them. The best site is usually either the Wikipedia, or a concise blog on Celestrak. I found the Celestrak information to be very quick and easy to understand, which allowed me to use all the satellite orbital element data in the code.
If you have any more questions, email me at 'etumanova [at] gatech [dot] edu', and I will add on to this readme file!
- Fork the repository.
- Create a new branch:
git checkout -b feature-name. - Make your changes.
- Push your branch:
git push origin feature-name. - Create a pull request.
This project is licensed under the MIT license. See license.md for more information.