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.

  • header (fits.Header) – FITS header containing FILTER, IMAGETYP, OBJECT, EXPTIME.

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

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

  • image_directory (str) – Subdirectory name within the images directory.

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

Returns:

Path – Path to the saved FITS file.

Note

Filename formats:

  • Light frames: “{device}_{filter}_{object}_{exptime}_{timestamp}.fits”

  • Bias/Dark: “{device}_{imagetype}_{exptime}_{timestamp}.fits”

  • Other: “{device}_{filter}_{imagetype}_{exptime}_{timestamp}.fits”

Headers automatically updated with DATE-OBS, DATE, and WCS (if provided).

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]#

Create a directory for storing astronomical images.

Creates a directory for image storage using either a user-specified path or an auto-generated date-based path. The auto-generated path uses the local date calculated from the schedule start time and site longitude.

Parameters:

  • schedule_start_time (datetime, optional) – Start time of the observing schedule. Defaults to current UTC time.

  • site_long (float, optional) – Site longitude in degrees for local time conversion. Defaults to 0.

  • user_specified_dir (str | None, optional) – Custom directory path. If provided, this overrides auto-generation. Defaults to None.

Returns:

Path – Path object pointing to the created directory.

Note

Auto-generated directory format is YYYYMMDD based on local date calculated as schedule_start_time + (site_long / 15) hours.

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

Calculate the observing night date based on the sun’s position.

If the sun is up, the date is the current local date. If the sun is down:

  • If it’s morning (before noon), the date is yesterday.

  • If it’s evening (after noon), the date is today.

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).

static get_default_observing_date(longitude: float = 0)[source]#
Contents