astra.pointer

astra.pointer#

Astronomical pointing correction and plate solving utilities.

This module provides comprehensive tools for correcting telescope pointing errors by analyzing astronomical images and comparing detected stars with catalog data. The primary workflow involves star detection, world coordinate system (WCS) computation, and pointing offset calculation.

Key Features:

Multi-scale star detection algorithms for robust identification in noisy images
Gaia star catalog integration for precise astrometric reference
World Coordinate System (WCS) computation using the twirl library
Automatic pointing correction calculation and validation
Support for FITS file processing with metadata extraction
Background subtraction and image cleaning utilities

The module supports two main use cases:

Real-time pointing correction during observations
Post-processing analysis of astronomical images

Typical Workflow:

Load or generate an astronomical image
Detect stars using multi-scale algorithms
Query Gaia catalog for reference stars in the field
Compute WCS transformation between image and sky coordinates
Calculate pointing correction based on target vs actual position
Apply corrections to telescope pointing

Example

# Process a FITS file for pointing correction
pointing_correction, image_star_mapping, num_stars = (
    calculate_pointing_correction_from_fits(
        "observation.fits",
        target_ra=150.25,
        target_dec=2.18
    )
)

# Get the pointing offset
ra_offset = pointing_correction.offset_ra
dec_offset = pointing_correction.offset_dec

print(f"Pointing error: RA={ra_offset:.3f}°, Dec={dec_offset:.3f}°")

Functions

`calculate_pointing_correction_from_fits`(filepath)	Calculate pointing correction from a FITS file.
`calculate_pointing_correction_from_image`(...)	Calculate pointing correction from an image array.
`find_stars`(data[, threshold, fwhm])	Find stars using DAOStarFinder algorithm.
`local_db_query`(db, min_dec, max_dec, min_ra, ...)	Query astronomical database for objects within coordinate bounds.
`local_gaia_db_query`(center, fov[, limit, ...])	Query local Gaia database to retrieve RA-DEC coordinates of stars within a given field-of-view.

Classes

`ImageStarMapping`(wcs, stars_in_image, ...)	A class to handle the mapping of stars detected in an image to their corresponding Gaia star coordinates using World Coordinate System (WCS) transformations.
`PointingCorrection`(target_ra, target_dec, ...)	Class to store the pointing correction between the desired target center and the plating center.

Exceptions

PlateSolveError

Raised when twirl finds no solution, or no solution passes the checks.

Calculate pointing correction from a FITS file.

Performs the complete plate solving workflow from a FITS file, including metadata extraction, image cleaning, star detection, and pointing correction.

Parameters:

filepath (str or Path) – Path to the FITS file.
dark_frame (str, Path or np.ndarray, optional) – Dark frame for subtraction, as a path or as image data. Defaults to None.
target_ra (float, optional) – Target right ascension in degrees. If not provided, it’s read from FITS header. Defaults to None.
target_dec (float, optional) – Target declination in degrees. If not provided, it’s read from FITS header. Defaults to None.
filter_band (str, optional) – Filter band used for observation. Defaults to None.
use_local_db (bool, optional) – Whether to use the local Gaia database. Defaults to False.
logger (logging.Logger, optional) – Logger for progress messages, for example the observatory logger so the messages reach the UI. Defaults to the module logger.

Returns:

Tuple[PointingCorrection, ImageStarMapping, int] –

A tuple containing:

PointingCorrection: Object with computed pointing correction
ImageStarMapping: Mapping of image stars to Gaia stars
int: Number of stars used from the image for plate solving

Raises:

Exception – If insufficient stars are detected for plate solving, or if the offset is larger than the field of view.
PlateSolveError – If no solution passes the checks in _verify_plate_solve.

astra.pointer.calculate_pointing_correction_from_image(image: ndarray, target_ra: float, target_dec: float, dateobs: datetime, plate_scale: float, filter_band: str | None = None, use_local_db: bool = False, logger: Logger | None = None)[source]#

Calculate pointing correction from an image array.

Performs the complete plate solving workflow: image cleaning, star detection, Gaia catalog matching, WCS computation, and pointing correction calculation.

Parameters:

image (np.ndarray) – The 2D astronomical image data.
target_ra (float) – Target right ascension in degrees.
target_dec (float) – Target declination in degrees.
dateobs (datetime) – Observation date for proper motion corrections.
plate_scale (float) – Image plate scale in degrees per pixel.
filter_band (str, optional) – Filter band used for observation.
use_local_db (bool, optional) – Whether to use the local Gaia database. Defaults to False.
logger (logging.Logger, optional) – Logger for progress messages, for example the observatory logger so the messages reach the UI. Defaults to the module logger.

Returns:

Tuple[PointingCorrection, ImageStarMapping, int] –

A tuple containing:

PointingCorrection: Object with computed pointing correction
ImageStarMapping: Mapping of image stars to Gaia stars
int: Number of stars used from the image for plate solving

Raises:

Exception – If insufficient stars are detected for plate solving, or if the offset is larger than the field of view.
PlateSolveError – If no solution passes the checks in _verify_plate_solve.

astra.pointer.find_stars(data: ndarray, threshold: float = 5.0, fwhm: float = 3.0) → ndarray[source]#

Find stars using DAOStarFinder algorithm.

Uses the photutils DAOStarFinder algorithm to detect point sources in astronomical images. The function performs background subtraction and returns star coordinates sorted by brightness.

Parameters:

data (np.ndarray) – The 2D image data array.
threshold (float, optional) – Detection threshold in units of background standard deviation. Higher values detect fewer, brighter stars. Defaults to 5.0.
fwhm (float, optional) – Expected Full Width at Half Maximum of stars in pixels. Should match the typical seeing conditions. Defaults to 3.0.

Returns:

np.ndarray –

Array of detected star coordinates sorted by brightness.: Shape is (N, 2) where N is the number of stars, and each row is (x, y). Returns an empty array if no stars are found.

exception astra.pointer.PlateSolveError[source]#

Bases: Exception

Raised when twirl finds no solution, or no solution passes the checks.

class astra.pointer.PointingCorrection(target_ra: float, target_dec: float, plating_ra: float, plating_dec: float)[source]#

Bases: object

Class to store the pointing correction between the desired target center and the plating center.

Stores target and actual telescope pointing coordinates and provides methods to calculate offsets, angular separations, and proxy coordinates for correction. The proxy coordinates represent where the telescope should point to achieve the desired target position.

Properties:: offset_ra: RA offset (plating - target) in degrees :no-index: offset_dec: Dec offset (plating - target) in degrees :no-index: angular_separation: Angular distance between target and actual position :no-index: proxy_ra: RA coordinate to point telescope to reach target :no-index: proxy_dec: Dec coordinate to point telescope to reach target :no-index:

Example

>>> from astra.pointer import PointingCorrection
>>> pointing_correction = PointingCorrection(
...     target_ra=10.685, target_dec=41.269,
...     plating_ra=10.68471, plating_dec=41.26917
... )
>>> print(f"RA offset: {pointing_correction.offset_ra:.4f} degrees")

target_ra: float#: The declination of the target center in degrees.

target_dec: float#: The right ascension of the plating center in degrees.

plating_ra: float#: The declination of the plating center in degrees.

plating_dec: float#

property offset_ra#

Calculate the RA offset between plating and target coordinates.

Returns:

float –

RA offset (plating_ra - target_ra) in degrees. Positive values: indicate the telescope pointed east of the target.

property offset_dec#

Calculate the Dec offset between plating and target coordinates.

Returns:

float –

Dec offset (plating_dec - target_dec) in degrees. Positive values: indicate the telescope pointed north of the target.

property angular_separation: float#

Calculate the angular separation between target and plating coordinates.

Returns:

float –

Angular distance between target and actual position in degrees.: Always positive, represents the magnitude of the pointing error.

property proxy_ra#

Calculate the RA coordinate to point the telescope to reach the target RA.

This assumes that the offset is independent of the telescope’s position in the sky. The proxy coordinate compensates for the systematic pointing error.

Returns:

float –

RA coordinate in degrees where the telescope should point to: effectively arrive at the target RA.

astra.pointer

Contents

astra.pointer#