astra.image_handler

astra.image_handler#

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

ImageHandler(header[, image_directory, ...])

Class that stores image_directory and header.
class astra.image_handler.ImageHandler(header: ObservatoryHeader, image_directory: Path | None = None, filename_templates: FilenameTemplates | None = None, logger: Logger | None = None, observing_date: datetime | None = None)[source]#

Bases: object

Class that stores image_directory and header.

header#

FITS header template for images.

Type:

fits.Header

last_image_path#

Path of the last saved image.

Type:

Path | None

last_image_timestamp#

Timestamp of the last saved image.

Type:

datetime | None

filename_templates#

Templates for generating filenames. Uses Python str.format() syntax by default. For more advanced logic, use JinjaFilenameTemplates class.

Type:

FilenameTemplates

logger#

Logger for logging messages.

Type:

logging.Logger

Examples

>>> from astra.image_handler import ImageHandler
>>> from astra.header_manager import ObservatoryHeader
>>> from pathlib import Path
>>> header = ObservatoryHeader.get_test_header()
>>> header['FILTER'] = 'V'
>>> image_handler = ImageHandler(header=header, image_directory=Path("images"))
>>> image_handler.image_directory
PosixPath('images')
>>> image_handler.header['FILTER']
'V'
property image_directory: Path#

Directory path to save images. If None, must be set before saving images.

has_image_directory() → bool[source]#
classmethod from_action(action: Action, paired_devices: PairedDevices, observatory_config: ObservatoryConfig, fits_config: DataFrame, logger: ObservatoryLogger)[source]#

Create ImageHandler from an action and observatory.

save_image(image: List[int] | ndarray, image_info: ImageMetadata, maxadu: int, device_name: str, exposure_start_datetime: datetime, sequence_counter: int = 0, header: ObservatoryHeader | None = None, image_directory: str | Path | None = None, wcs: WCS | None = None) → Path[source]#

Save an astronomical image as a FITS file with proper headers and filename.

Transforms raw image data, updates FITS headers with observation metadata, optionally adds WCS information, and saves as a FITS file with an automatically generated filename based on image properties.

Parameters:

  • image (list[int] | np.ndarray) – Raw image data to save.

  • image_info (ImageMetadata) – Image metadata for data type determination.

  • maxadu (int) – Maximum ADU value for the image.

  • device_name (str) – Camera/device name for filename generation.

  • exposure_start_datetime (datetime) – UTC datetime when exposure started.

  • sequence_counter (int) – Sequence number for filename generation. Defaults to 0.

  • header (ObservatoryHeader | None) – FITS header to use. Defaults to self.header.

  • image_directory (str | Path | None) – Directory to save the image. Relative paths are resolved under the configured images root. Defaults to self.image_directory.

  • wcs (WCS | None) – World Coordinate System information. Defaults to None.

Returns:

Path – Path to the saved FITS file.

get_file_path(device_name: str, header: Header, date: datetime, sequence_counter: int, image_directory: Path) → Path[source]#

Generate a file path for saving an image based on metadata and templates.

static set_image_dir(user_specified_dir: str | None = None) → Path | None[source]#

Resolve the directory for storing images.

Returns either the user-specified directory (creating it if needed) or the default images directory from the observatory config.

Parameters:

user_specified_dir (str | None, optional) – Custom directory path. If provided, the directory is created and returned. Defaults to None.

Returns:

Path – Path to the image directory.

get_observatory_location()[source]#
static get_observing_night_date(observation_time: datetime, location: EarthLocation) → datetime[source]#

Calculate the observing night date using a local-noon boundary.

All times before local noon are assigned to the previous calendar date (last night), and all times from local noon onward are assigned to the current calendar date (tonight). This keeps post-midnight and post-sunrise calibrations in the same nightly folder until noon.

Parameters:

  • observation_time (datetime.datetime) – The time of observation (UTC).

  • location (EarthLocation) – The location of the observatory.

Returns:

datetime.datetime – The observing night date (at midnight).

Contents