Metadata-Version: 2.4
Name: gaia-catalog
Version: 0.1.2
Summary: Bundled Gaia DR3 star catalog in binary format, with Hipparcos for brightest stars
Author: Steven Michael
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gaia-catalog

Bundled [Gaia DR3](https://www.cosmos.esa.int/web/gaia/dr3) star catalog in a compact binary format for Python, with [Hipparcos 2](https://www.cosmos.esa.int/web/hipparcos) data for the brightest stars.

## Installation

```bash
pip install gaia-catalog
```

## Creating the binary catalog

The binary data file is not included in the repository. To create it from a `gaia_merged.csv` (produced by tetra3rs's download script):

```bash
python -c "from gaia_catalog import convert_csv_to_binary; convert_csv_to_binary('path/to/gaia_merged.csv')"
```

This writes `gaia_merged.bin` into the package's `data/` directory.

## Usage

```python
from gaia_catalog import catalog_path

path = catalog_path()
```

## Binary format

```
Header:  b'GDR3' (4 bytes) + version (u32 LE) + num_stars (u64 LE)
Per star: source_id (i64 LE) + ra (f64 LE) + dec (f64 LE)
          + mag (f32 LE) + pmra (f32 LE) + pmdec (f32 LE)
```

36 bytes per star, little-endian throughout.

## Data license

Gaia DR3 data is published by ESA/Gaia/DPAC under [CC BY-SA 3.0 IGO](https://creativecommons.org/licenses/by-sa/3.0/igo/). Hipparcos 2 data is provided by ESA and is freely available for scientific use. If you use this catalog, please cite Gaia DR3 appropriately. The code in this package is MIT-licensed.
