Ryan Malloy
1d36729bed
Core modules: - tle.py: NORAD decoding (Alpha-5 + Super-5, matching get_el.c), 3LE/2LE parsing, TLERecord dataclass with epoch-based dedup - config.py: TOML config + env var overlay (XDG-compliant paths) - cache.py: File-based cache with staleness checking - catalog.py: Multi-source merge with MergeStats tracking - regime.py: LEO/MEO/GEO/HEO classification by mean motion Source downloaders (httpx): - celestrak.py: Active catalog + supplemental GP groups - satnogs.py: JSON API with 3LE conversion - spacetrack.py: POST auth flow, bulk GP download Output formatters: - sql.py: pg_orrery-compatible INSERT generation (E'' strings) - tle_file.py: Standard 3LE text output - json_out.py: JSON with orbital metadata and regime CLI (Click + Rich): - download: Cache TLEs from all sources - build: Merge + output SQL/3LE/JSON (pipes to psql) - load: Direct DB load via psycopg (optional [pg] extra) - info: Cache stats and configuration display 58 tests covering NORAD decoding (all 4 encoding cases), parsing, merge/dedup, SQL escaping, regime classification.
81 lines
2.0 KiB
Markdown
81 lines
2.0 KiB
Markdown
# pg-orrery-catalog
|
||
|
||
TLE catalog builder for [pg_orrery](https://pg-orrery.warehack.ing) — download, merge, and load satellite catalogs from Space-Track, CelesTrak, and SatNOGS into PostgreSQL.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
uv pip install pg-orrery-catalog
|
||
# or
|
||
uvx pg-orrery-catalog --help
|
||
```
|
||
|
||
For direct database loading:
|
||
|
||
```bash
|
||
uv pip install "pg-orrery-catalog[pg]"
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Download TLE data from all sources
|
||
pg-orrery-catalog download
|
||
|
||
# Build SQL and pipe to psql
|
||
pg-orrery-catalog build | psql -d mydb
|
||
|
||
# Or load directly (requires [pg] extra)
|
||
pg-orrery-catalog load --database-url postgresql:///mydb --create-index
|
||
|
||
# Export as 3LE file
|
||
pg-orrery-catalog build --format 3le -o merged.tle
|
||
|
||
# Check cache status
|
||
pg-orrery-catalog info --cache
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Create `~/.config/pg-orrery-catalog/config.toml`:
|
||
|
||
```toml
|
||
[spacetrack]
|
||
user = "you@example.com"
|
||
password = "secret"
|
||
|
||
[celestrak]
|
||
proxy = "localhost:1080"
|
||
supgp_groups = ["starlink", "oneweb", "planet", "orbcomm"]
|
||
|
||
[output]
|
||
table = "satellites"
|
||
|
||
[database]
|
||
url = "postgresql://localhost/mydb"
|
||
```
|
||
|
||
Environment variables (`SPACETRACK_USER`, `SPACETRACK_PASSWORD`, `SOCKS_PROXY`, `DATABASE_URL`) override config file values.
|
||
|
||
## Sources
|
||
|
||
| Source | Auth | Coverage |
|
||
|--------|------|----------|
|
||
| [Space-Track](https://www.space-track.org) | Login required | Full catalog (~30k+ on-orbit) |
|
||
| [CelesTrak](https://celestrak.org) | None | Active sats + operator SupGP |
|
||
| [SatNOGS](https://db.satnogs.org) | None | Community-tracked objects |
|
||
|
||
When the same NORAD ID appears in multiple sources, the entry with the newest epoch wins — CelesTrak SupGP data (operator-provided, fresher epochs) overrides stale Space-Track entries.
|
||
|
||
## NORAD ID Decoding
|
||
|
||
Handles all four encoding schemes from Bill Gray's sat_code:
|
||
- **Traditional**: 5-digit (00001–99999)
|
||
- **Alpha-5**: letter + 4 digits (A0000–Z9999 → 100000–339999)
|
||
- **Super-5 case 3**: base-64 with uppercase last char (340000–906309663)
|
||
- **Super-5 case 4**: base-64 with non-digit 4th char (906309664+)
|
||
|
||
## License
|
||
|
||
MIT
|