astra.calibrate_guiding

Guiding calibration system for telescope autoguiding setup.

This module provides automated calibration of telescope guiding systems by measuring pixel-to-time scales and determining camera orientation relative to telescope mount axes. It performs systematic nudges in cardinal directions and analyzes the resulting star field shifts to create calibration parameters.

Classes:

CustomImageClass: Enhanced image processing with background subtraction GuidingCalibrator: Main calibration orchestrator for guiding systems

Classes

GuidingCalibrator(astra_observatory, action, ...)

Automated telescope guiding calibration system.

class astra.calibrate_guiding.GuidingCalibrator(astra_observatory: Observatory, action: Action, paired_devices: Dict[str, str], image_handler: ImageHandler, save_path: Path | None = None, pulse_time: float = 5000, exptime: float = 5, settle_time: float = 10, number_of_cycles: int = 10)

Bases: object

Automated telescope guiding calibration system.

Orchestrates the complete guiding calibration process by systematically pulsing the telescope mount in cardinal directions and measuring the resulting star field shifts to determine pixel-to-time scales and camera orientation relative to mount axes.

astra_observatory

Observatory instance for device control.

action

Action instance containing calibration information.

paired_devices

Dictionary of paired device names.

hdr

FITS header data for images.

save_path

Directory for saving calibration data and images.

pulse_time

Duration of guide pulses in milliseconds.

exptime

Exposure time for calibration images.

settle_time

Wait time after pulses before exposing.

number_of_cycles

Number of calibration cycles to perform.

run() → None

Execute complete guiding calibration sequence.

Performs telescope slewing, calibration cycles, configuration completion, and saves results to observatory configuration.

slew_telescope_one_hour_east_of_sidereal_meridian() → None

Position telescope one hour east of meridian for calibration.

Slews telescope to RA = LST - 1 hour, Dec = 0 degrees to provide optimal conditions for guiding calibration with good star tracking and minimal atmospheric effects.

Raises:

ValueError – If telescope slewing fails.

perform_calibration_cycles() → None

Execute systematic guiding calibration cycles.

Performs multiple cycles of telescope nudges in North, South, East, and West directions, measuring star field shifts to determine pixel scales and camera orientation. Each cycle improves measurement accuracy.

complete_calibration_config() → None

Generate final calibration configuration from measurements.

Processes collected direction and scale measurements to create PIX2TIME conversion factors, determine RA axis orientation, and validate measurement consistency across cycles.

Raises:

ValueError – If direction measurements are inconsistent across cycles.

save_calibration_config() → None

Save calibration configuration to YAML file with nice formatting.

Uses ruamel.yaml to create readable output with proper indentation, preserved structure, and better formatting for nested dictionaries.

update_observatory_config() → None

Update observatory configuration with calibration results.

Integrates the calculated calibration parameters into the observatory configuration file for the specific camera being calibrated.

static _determine_shift_direction(shift: Any, logger: Any = None) → Tuple[str, float]

Analyze donuts shift measurement to determine direction and magnitude.

Processes shift measurements to identify the primary axis of movement and calculate the pixel displacement magnitude for calibration.

Parameters:

• shift (Any) – Donuts shift measurement object with x and y value attributes.

• logger (Any) – Optional logger for debug output.

Returns:

Tuple[str, float] –

Direction literal (‘+x’, ‘-x’, ‘+y’, ‘-y’) and

pixel displacement magnitude.

_pulse_guide_telescope(guide_direction: GuideDirections, duration: float) → None

Execute telescope guide pulse in specified direction.

Sends guide pulse command to telescope mount and waits for completion. Logs telescope position after pulse for verification.

Parameters:

• guide_direction (GuideDirections) – Cardinal direction for guide pulse from GuideDirections enum.

• duration (float) – Pulse duration in milliseconds.

Raises:

ValueError – If guide direction is invalid.

static _apply_donuts(image_path: Path) → Donuts

Create Donuts instance for image shift measurement.

Configures Donuts with custom image processing for accurate star shift detection during guiding calibration.

Parameters:

image_path (Path) – Path object pointing to FITS image file.

Returns:

Donuts – Configured Donuts instance for shift measurements.

_perform_exposure() → Path

Capture calibration image with specified parameters.

Waits for telescope settling, then captures image using configured exposure time and saves to calibration directory.

Returns:

Path – Path to captured FITS image file.

Raises:

ValueError – If image exposure fails.