Star Catalog¶
tetra3rs solves against a merged Gaia DR3 + Hipparcos catalog. Gaia DR3 provides the bulk of stars; Hipparcos 2 fills in the few dozen brightest stars (G < 4) where Gaia saturates. Positions are stored at Gaia's reference epoch (J2016.0) and propagated to the observation epoch at solve time using per-star proper motion.
The on-disk format is a compact little-endian binary (header GDR3, 36 bytes per star) used by both the Rust crate and the Python gaia-catalog PyPI package. The same script can also write a CSV form.
Pre-built download¶
The easiest path. A pre-built catalog with G < 10 (~17 MB, ~482k stars) is hosted on Google Cloud Storage:
mkdir -p data
curl -o data/gaia_merged.bin "https://storage.googleapis.com/tetra3rs-testvecs/gaia_merged.bin"
Python users get the same file bundled in gaia-catalog, which is installed automatically with tetra3rs — no curl needed.
Generate your own¶
If you need a different magnitude limit (e.g. fainter stars for narrow-FOV cameras) or want to regenerate at a more recent reference epoch, two download scripts live in scripts/:
| Script | Backend | Practical mag limit | Setup |
|---|---|---|---|
download_gaia_catalog.py |
ESA Gaia Archive TAP server | G ≲ 11.5 (3M-row hard cap) | pip install astroquery astropy |
download_gaia_flatiron.py |
Flatiron Institute flathub | full Gaia DR3 | flathub from GitHub (see below) |
Both scripts produce byte-compatible output and share the Hipparcos-2 bright-star merge — the flathub script imports the merge and writer functions from the ESA script.
ESA TAP (shallow catalogs)¶
The canonical Gaia source. Default settings produce the same ~17 MB / ~482k-star catalog as the pre-built download:
pip install astroquery astropy
bash scripts/download_hip2.sh
python scripts/download_gaia_catalog.py --mag-limit 10.0 --output data/gaia_merged.bin
3-million-row cap
The ESA TAP server advertises a hard output limit of 3,000,000 rows per async job for anonymous users (see https://gea.esac.esa.int/tap-server/tap/capabilities). Cumulative Gaia DR3 counts: G<10 ≈ 482k, G<11 ≈ 1.25M, G<12 ≈ 3.09M, G<13 ≈ 7.37M. So anonymous queries top out around G ≈ 11.5; fainter mags return a silently-truncated result. The script already uses launch_job_async, but the cap is server-side and MAXREC cannot raise it.
Workarounds: register for a free Gaia archive account (the per-job limit is higher for authenticated users), or use the flathub script below, which has no faint-end cap.
Flatiron flathub (faint catalogs)¶
flathub hosts the full Gaia DR3 catalog and streams .npy payloads directly. It serves the same query as the ESA TAP backend without the faint-end cap.
flathub is not on PyPI. Install from the upstream repo:
# one-shot from git
pip install "flathub @ git+https://github.com/flatironinstitute/flathub.git@prod#subdirectory=py"
# or clone + local install
git clone https://github.com/flatironinstitute/flathub.git
pip install ./flathub/py
You'll also need the Hipparcos 2 catalog for the bright-star merge:
Then run the downloader:
pip install astropy scipy
python scripts/download_gaia_flatiron.py --mag-limit 14.0 --output data/gaia_merged.bin
NumPy 2.0 shim
The flathub client currently calls numpy.DataSource, which NumPy 2.0 removed. The script shims that symbol back at import time, so no patch to flathub itself is needed.
Large downloads
A G < 14 catalog is ~17M stars, ~1 GB on disk; the response is served as a single streaming .npy. A corporate / filtering proxy may drop or truncate the connection — run the script on a direct connection if possible.
What's in the merged catalog¶
Records, in either output format, carry: source_id, ra, dec, phot_g_mean_mag, pmra, pmdec (binary), plus phot_bp_mean_mag, phot_rp_mean_mag, parallax (CSV only).
The Hipparcos merge propagates Hipparcos positions from the Hipparcos reference epoch (J1991.25) to the Gaia DR3 reference epoch (J2016.0) using each star's proper motion, then adds Hipparcos stars brighter than the bright-threshold (G ~ 4 by default) that have no Gaia counterpart within the match radius (5″ by default). Synthesized Hipparcos entries are stored with negative source_id values so they're distinguishable from real Gaia IDs. The relevant CLI flags are --bright-threshold and --match-radius (both scripts).
See the docstrings in scripts/download_gaia_catalog.py and scripts/download_gaia_flatiron.py for the full option set and cross-match details.