Metadata-Version: 2.4
Name: gaiahealpixcache
Version: 0.1.0
Summary: Download and cache a lightweight version of the Gaia catalog for offline work
Project-URL: Homepage, https://github.com/betoule/gaiahealpixcache
Project-URL: Repository, https://github.com/betoule/gaiahealpixcache
Project-URL: Issues, https://github.com/betoule/gaiahealpixcache/issues
Author-email: Marc Betoule <marc.betoule@lpnhe.in2p3.fr>
License: MIT
License-File: LICENSE
Keywords: astronomy,cache,catalog,gaia,healpix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.11
Requires-Dist: astropy>=6.0
Requires-Dist: healpy
Requires-Dist: numpy>=1.26
Requires-Dist: requests
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pylint; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Description-Content-Type: text/markdown

# gaiahealpixcache

Download and cache a lightweight version of the Gaia DR3 catalog for offline work.

This tool follows the official HEALPix level 8 partitioning of the Gaia archive, enabling on-demand partial download with a pure NumPy backend. Much faster than querying the online archive for large amounts of data.

## Installation

```bash
uv pip install gaiahealpixcache
```

Or from source:

```bash
git clone https://github.com/betoule/gaiahealpixcache.git
uv venv
source .venv/bin/activate
uv pip install -e .
```

## Usage

### Query sources around sky coordinates

```python
import gaiahealpixcache

sources = gaiahealpixcache.query(ra_deg=76.377, dec_deg=52.831, radius_arcmin=30)
print(len(sources))
print(sources["source_id"][:5])
print(sources["phot_g_mean_flux"][:5])
```

### Convert to topocentric coordinates

```python
import gaiahealpixcache
from astropy.time import Time

now = Time.now()
mjd = now.mjd

sources = gaiahealpixcache.query(ra_deg=76.377, dec_deg=52.831)

topo = gaiahealpixcache.gaia_to_topocentric(
    sources,
    mjd=mjd,
    lon_deg=5.71,
    lat_deg=43.93,
    height_m=640.0,
)
print(topo["ra_apparent_deg"][:5])
print(topo["alt_deg"][:5])
```

### Manage cache

```python
cache_dir = gaiahealpixcache.get_cache_dir()
print(f"Cache location: {cache_dir}")

gaiahealpixcache.clear_cache()
```

## API

| Function | Description |
|---|---|
| `query(ra_deg, dec_deg, radius_arcmin)` | Query Gaia sources within a circular region |
| `gaia_to_topocentric(catalog, mjd, ...)` | Convert ICRS catalog to topocentric coordinates |
| `center_at_date(ra, dec, mjd)` | Get apparent RA/Dec at a given date |
| `get_pixlist(ras, decs, level)` | Get HEALPix pixels for coordinates |
| `get_pix_range(ra, dec)` | Get Gaia file pixel ranges for coordinates |
| `retrieve_gaia_data(pixel_range)` | Download/cache a single Gaia tile |
| `haversine(ra1, dec1, ra2, dec2)` | Great-circle distance in degrees |
| `get_cache_dir()` | Get cache directory path |
| `clear_cache()` | Remove all cached data |

## License

MIT
