Catalogs
catalogs
TLECatalog
A catalog mapping satellite IDs to TLE entries.
Provides dictionary-like storage keyed by satellite identifier strings (NORAD catalog numbers or user-assigned labels). Loading is supported from standard two-line or three-line element set files.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str | None
|
Optional human-readable catalog label.
Set to the file path when loaded with |
count |
int
|
Number of TLE entries in the catalog [dimensionless; 0..]. |
count
property
Number of TLE entries in the catalog [dimensionless; 0..].
name
property
writable
Optional human-readable catalog label.
Set to the file path when loaded with from_tle_file.
__contains__(satellite_id)
Returns whether a TLE is stored under satellite_id.
__delitem__(satellite_id)
Removes the TLE stored under satellite_id.
Raises:
| Type | Description |
|---|---|
KeyError
|
If no entry is stored under |
__getitem__(satellite_id)
Returns the TLE stored under satellite_id.
Raises:
| Type | Description |
|---|---|
KeyError
|
If no entry is stored under |
__init__(name=...)
Creates an empty TLECatalog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
Optional[str]
|
Optional human-readable catalog label. |
...
|
__len__()
Returns the number of element sets in the catalog.
__setitem__(satellite_id, tle)
Adds or replaces the TLE stored under satellite_id.
add(satellite_id, tle)
Inserts or replaces a TLE entry under the given satellite ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
satellite_id
|
str
|
Unique key string (e.g., a NORAD number or custom label). |
required |
tle
|
TLE
|
TLE entry to store. |
required |
add_tle(tle)
Inserts or replaces a TLE entry, deriving the key from its NORAD number.
For catalog numbers ≤ 99 999 the decimal string is used as the key.
For Alpha-5 numbers (> 99 999) the key is a letter plus four digits
(e.g., 100 001 → "A0001").
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tle
|
TLE
|
TLE entry to store. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The satellite ID string used as the catalog key. |
clear()
Removes all entries from the catalog.
fit_best_tle(srp_coefficient=..., drag_coefficient=...)
Fits a single best-fit TLE from all catalog entries via Batch Least Squares.
The earliest-epoch TLE in the catalog is used as the a-priori state. Synthetic range/range-rate observations are generated from each TLE's Cartesian state and fed to the BLS solver.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
srp_coefficient
|
Optional[float]
|
Optional solar radiation pressure coefficient to
fix [km²/kg]. |
...
|
drag_coefficient
|
Optional[float]
|
Optional ballistic coefficient to fix [km²/kg].
|
...
|
Returns:
| Type | Description |
|---|---|
TLE
|
The fitted TLE. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the catalog is empty, if any TLE cannot be evaluated, or if the BLS solver fails to converge. |
from_tle_file(file_path)
staticmethod
Loads a TLECatalog from a two-line or three-line element set file.
Lines containing only whitespace are skipped. Each entry is detected
by its leading character: '1' starts a two-line set; any other
character starts a three-line set (an optional "0 " name prefix is
stripped).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path to the TLE file. |
required |
Returns:
| Type | Description |
|---|---|
TLECatalog
|
A populated TLECatalog whose |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the file cannot be read, if a TLE block is incomplete, or if any TLE string fails to parse. |
get(satellite_id)
Retrieves a TLE entry by satellite ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
satellite_id
|
str
|
Key string to look up. |
required |
Returns:
| Type | Description |
|---|---|
Optional[TLE]
|
The TLE if found, or |
get_by_norad_id(norad_id)
Retrieves a TLE entry by its NORAD catalog number.
Scans all entries; O(n) in catalog size.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
norad_id
|
int
|
NORAD catalog number [dimensionless; 1..]. |
required |
Returns:
| Type | Description |
|---|---|
Optional[TLE]
|
The TLE if an entry with the given NORAD number is found, |
Optional[TLE]
|
or |
get_plot_data()
Generates orbit plot data from the first catalog entry.
Uses the earliest-keyed TLE's current Cartesian state as the initial orbit point.
Returns:
| Type | Description |
|---|---|
OrbitPlotData
|
OrbitPlotData containing a single orbit point. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the catalog is empty or if the TLE's Cartesian state cannot be evaluated. |
keys()
Returns all satellite ID keys in sorted order.
Returns:
| Type | Description |
|---|---|
list[str]
|
Sorted list of satellite ID strings. |
remove(satellite_id)
Removes and returns the TLE entry for the given satellite ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
satellite_id
|
str
|
Key string to remove. |
required |
Returns:
| Type | Description |
|---|---|
Optional[TLE]
|
The removed TLE if the key existed, or |