# 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