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: 1. Real-time pointing correction during observations 2. 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

Classes:

PointingCorrection: Stores target vs actual pointing coordinates ImageStarMapping: Handles star detection and catalog matching

Functions:

calculate_pointing_correction_from_fits: Complete pointing correction from FITS file calculate_pointing_correction_from_image: Complete pointing correction from image array find_stars: Basic star detection using DAOStarFinder local_gaia_db_query: Query local Gaia database for reference stars local_db_query: Low-level database query for astronomical catalogs

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.

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 or Path, optional) – Path to a dark frame for subtraction. 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.
fraction_of_stars_to_match (float, optional) – Fraction of detected stars required to be matched for a valid plate solve. Defaults to 0.70.
or_min_number_of_stars_to_match (int, optional) – Minimum number of stars required to be matched for a valid plate solve. Defaults to 8.

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, if the offset is larger than the field of view, or if too few stars are matched.

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, fraction_of_stars_to_match: float = 0.70, or_min_number_of_stars_to_match: int = 8)[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.
fraction_of_stars_to_match (float, optional) – Fraction of detected stars required to be matched for a valid plate solve. Defaults to 0.70.
or_min_number_of_stars_to_match (int, optional) – Minimum number of stars required to be matched for a valid plate solve. Defaults to 8.

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, if the offset is larger than the field of view, or if too few stars are matched.

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.

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.

target_ra#

The right ascension of the target center in degrees.

Type:: float

target_dec#

The declination of the target center in degrees.

Type:: float

plating_ra#

The right ascension of the plating center in degrees.

Type:: float

plating_dec#

The declination of the plating center in degrees.

Type:: float

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

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#

target_dec: float#

plating_ra: float#

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#