astra.header_manager

Astronomical image processing and FITS file management utilities.

This module provides functions for handling astronomical images captured from observatory cameras. It manages image directory creation, data type conversion, and FITS file saving with proper headers and metadata.

Key features: - Automatic directory creation with date-based naming - Image data type conversion and array reshaping for FITS compatibility - FITS file saving with comprehensive metadata and WCS support - Intelligent filename generation based on observation parameters

The module handles various image types including light frames, bias frames, dark frames, and calibration images, ensuring proper metadata preservation and file organization for astronomical data processing pipelines.

Classes

HeaderManager()	Manages the creation and updating of FITS headers for astronomical images.
ObservatoryHeader(*args, **kwargs)	A FITS header subclass with observatory-specific properties and methods.

class astra.header_manager.HeaderManager

Bases: object

Manages the creation and updating of FITS headers for astronomical images.

static get_base_header(paired_devices: PairedDevices, action_value: BaseActionConfig, fits_config: DataFrame, logger: ObservatoryLogger) → ObservatoryHeader

Create a base FITS header with observatory and observation information.

Constructs a comprehensive FITS header containing fixed observatory parameters, current device status, astronomical coordinates, and observation metadata. The header is built from the FITS configuration file and current system state.

Parameters:

• paired_devices (PairedDevices) – Object containing the devices being used for the current observation sequence.

• action_value (dict) – Dictionary containing observation parameters from the schedule, including target coordinates, filters, and settings.

Returns:

fits.Header –

A complete FITS header object containing:

• Fixed observatory information (location, instrument details)

• Current astronomical conditions (coordinates, time)

• Device-specific parameters (telescope pointing, filter position)

• Observation metadata (object name, exposure settings)

Header Categories:

• astra: Observatory and software version information

• astropy_default: Standard astronomical coordinate systems

• Device-specific: Current status from telescopes, cameras, etc.

Note

• Some header values are populated from real-time device polling

• Coordinate transformations are performed for various reference frames

• Observatory location and timing information is automatically included

static final_headers(database_manager: DatabaseManager, logger: ObservatoryLogger, observatory_config: ObservatoryConfig, devices: dict, fits_config: DataFrame) → None

Complete FITS headers with interpolated device data.

Post-processes captured images by adding dynamic header information that wasn’t available at exposure time. Uses polled device data to interpolate accurate values for each image timestamp, ensuring complete and accurate FITS headers for scientific analysis.

The process: 1. Retrieves incomplete images from the database 2. Groups images by camera for efficient processing 3. Queries polled device data around image timestamps 4. Interpolates device values to exact exposure times 5. Updates FITS files with complete headers 6. Marks images as header-complete in database

Key Features: - Time-interpolated device values for precise timestamps - Handles multiple cameras and device types simultaneously - Preserves original headers while adding missing information - Robust error handling with detailed logging

Data Sources: - Device polling data from database - FITS configuration file for header mapping - Original image FITS headers for timing information

Error Handling: - Individual image failures don’t stop batch processing - All errors are logged and added to error_source - Database consistency maintained even with partial failures

Note

• Typically run after observation sequences complete

• Critical for ensuring complete scientific metadata

• May take significant time for large image sets

class astra.header_manager.ObservatoryHeader(*args, **kwargs)

Bases: Header

A FITS header subclass with observatory-specific properties and methods.

REQUIRED_KEYS

List of required header keys for validation.

Type:

list

Properties:

ra (float): Right Ascension in hours. dec (float): Declination in degrees. airmass (float): Airmass value.

validate()

Validate that all required keys are present in the header.

convert_ra_from_hours_to_degrees()

Convert RA from hours to degrees.

get_target_sky_coordinates()

Get target coordinates as a SkyCoord object.

get_observatory_location()

Get observatory location as an EarthLocation object.

get_test_header()

Class method to generate a test header with sample values.

Examples

>>> from astra.image_handler import ObservatoryHeader
>>> header = ObservatoryHeader.get_test_header()
>>> header.validate()

Construct a Header from an iterable and/or text file.

Parameters

cardslist of Card, optional

The cards to initialize the header with. Also allowed are other Header (or dict-like) objects.

Changed in version 1.2: Allowed cards to be a dict-like object.

copy : bool, optional

If True copies the cards if they were another Header instance. Default is False.

Added in version 1.3.

REQUIRED_KEYS = ['LONG-OBS', 'LAT-OBS', 'RA', 'DEC', 'EXPTIME', 'DATE-OBS']

validate()

property ra: float

Right Ascension

property dec: float

property airmass

convert_ra_from_hours_to_degrees()

get_target_sky_coordinates() → SkyCoord

get_observatory_location()

classmethod get_test_header() → ObservatoryHeader

update_fits_header_times(exposure_start_datetime: datetime) → datetime

set_imagetype(action_type: str, use_light: bool) → bool

Set the IMAGETYP header based on action type. Returns True if the image is a light frame, False otherwise.

set_action_type(action: Action) → None

Set the action type related headers based on the Action object.

add_times(fits_config: DataFrame, location: EarthLocation, target: SkyCoord) → None

Add comprehensive time information to FITS header.

Calculates and adds various time formats to FITS header including Julian Day variants, Modified Julian Day, and astronomical time corrections. Also computes airmass from altitude.

Parameters:

• self (dict) – FITS header dictionary to modify in-place.

• fits_config (pd.DataFrame) – Configuration with header specifications.

• location (EarthLocation) – Observer’s geographic location.

• target (SkyCoord) – Target celestial coordinates.

add_airmass(fits_config: DataFrame) → None