across.tools.visibility.catalogs

Star catalog utilities for visibility constraints.

Attributes

_RA_COLUMNS
_DEC_COLUMNS
_MAG_COLUMNS
_cache

Functions

_get_cache_dir()	Get the cache directory for star catalog data.
_get_cache_instance()	Get or initialize the diskcache instance.
cache_clear()	Clear the diskcache cache.
get_bright_stars([magnitude_limit, catalog, max_stars])	Retrieve bright stars from a catalog filtered by magnitude.
_get_fallback_bright_stars()	Provide a fallback list of very bright stars if catalog query fails.

Module Contents

_RA_COLUMNS = ['_RA.icrs', 'RA_ICRS', 'RAJ2000', 'RA(ICRS)', '_RAJ2000', 'ra', 'RAICRS']

_DEC_COLUMNS = ['_DE.icrs', 'DE_ICRS', 'DEJ2000', 'DE(ICRS)', '_DEJ2000', 'dec', 'DEICRS']

_MAG_COLUMNS = ['Vmag', 'Bmag', 'mag', 'V']

_cache: diskcache.Cache | None = None

_get_cache_dir()

Get the cache directory for star catalog data.

_get_cache_instance()

Get or initialize the diskcache instance.

cache_clear()

Clear the diskcache cache.

get_bright_stars(magnitude_limit=6.0, catalog='I/239/hip_main', max_stars=None)

Retrieve bright stars from a catalog filtered by magnitude.

This function queries the Hipparcos catalog via Vizier and returns stars brighter than the specified magnitude limit along with their magnitudes. Results are cached persistently on disk to minimize network calls to astroquery.

Parameters:

• magnitude_limit (float, optional) – Magnitude limit for stars to retrieve. Stars brighter (lower magnitude) than this value will be returned. Default is 6.0 (naked eye visible).

• catalog (str, optional) – Vizier catalog identifier. Default is “I/239/hip_main” (Hipparcos Main Catalog). Other options include: - “I/259/tyc2” (Tycho-2 Catalogue) - “V/50/catalog” (Yale Bright Star Catalog)

• max_stars (int, optional) – Maximum number of stars to retrieve. If None, retrieves all stars brighter than magnitude_limit. Default is None.

Returns:

List of tuples containing (sky coordinate, magnitude) for bright stars.

Return type:

list[tuple[SkyCoord, float]]

Examples

>>> # Get all stars brighter than magnitude 6
>>> stars = get_bright_stars(magnitude_limit=6.0)
>>> for coord, mag in stars[:5]:
...     print(f"Star at {coord.ra.deg:.2f}, {coord.dec.deg:.2f} with mag {mag:.2f}")
>>> # Get brightest 100 stars
>>> bright_100 = get_bright_stars(magnitude_limit=10.0, max_stars=100)

Notes

Results are cached using diskcache for persistent caching across sessions.

Disk cache location: ~/.cache/across-tools/star_catalogs/ (or ~/across-tools/star_catalogs/ on systems without ~/.cache)

The Hipparcos catalog contains ~118,000 stars. Filtering by magnitude significantly reduces the number of stars to consider: - mag < 3: ~200 stars - mag < 6: ~5,000 stars - mag < 8: ~25,000 stars

_get_fallback_bright_stars()

Provide a fallback list of very bright stars if catalog query fails.

This includes the 20 brightest stars in the sky, suitable for basic bright star avoidance when network access is unavailable.

Returns:

List of tuples containing (sky coordinate, magnitude) for the brightest stars (magnitude < ~1.5).

Return type:

list[tuple[SkyCoord, float]]