Metadata-Version: 2.4
Name: tart-catalogue-client
Version: 0.3.2
Summary: Python client for the TART catalogue ephemerides endpoint
Author-email: Tim Molteno <tim@elec.ac.nz>
License: GPL-3.0-only
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Requires-Dist: astropy>=7.0
Requires-Dist: numpy>=2.0
Requires-Dist: requests>=2.32
Requires-Dist: sgp4>=2.0
Description-Content-Type: text/markdown

# TART Catalogue Python Client

Fetches TLE data from the catalogue server and computes satellite positions
in ECEF or celestial (RA/Dec) coordinates.

## Setup

```sh
uv sync
```

## Usage

```sh
# ECEF positions (default)
uv run python -m tart_client.cli ecef

# Celestial (RA/Dec) positions
uv run python -m tart_client.cli celestial

# Custom server and date
uv run python -m tart_client.cli ecef \
  --url http://localhost:8876 \
  --date 2026-06-16T12:00:00Z
```

Or override the server URL:

```sh
export TART_CATALOGUE_URL=http://localhost:8876
uv run python -m tart_client.cli celestial
```

## Library use

```python
from tart_client import CatalogueClient

client = CatalogueClient()  # defaults to https://tart.elec.ac.nz/catalog
# Or: CatalogueClient(base_url="http://localhost:8876")

# ECEF positions
for sat in client.ecef_positions():
    print(sat["name"], sat["ecef_km"])

# Celestial positions
for sat in client.celestial_positions():
    print(sat["name"], sat["ra_hours"], sat["dec_degrees"])
```

## Output

### ECEF

```json
[
  {
    "name": "GPS BIIR-2  (PRN 13)",
    "ecef_km": [12345.678, -23456.789, 3456.78],
    "velocity_km_s": [1.234, -2.345, 5.678]
  }
]
```

### Celestial

```json
[
  {
    "name": "GPS BIIR-2  (PRN 13)",
    "ra_hours": 12.345678,
    "dec_degrees": -45.678901,
    "distance_km": 26500.0
  }
]
```

## How it works

1. **Fetch** — GET `/ephemerides` returns raw TLE (name, line1, line2)
2. **Propagate** — SGP4 propagator computes TEME position at the requested time
3. **Convert** — astropy transforms TEME → ITRS (ECEF) or TEME → ICRS (RA/Dec)
