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

Functions

calibration_from_shifts(shifts, pulse_time)

Guider calibration from the star shift that each guide direction causes.

Classes

GuidingCalibrator(astra_observatory, action, ...)

Automated telescope guiding calibration system.

astra.calibrate_guiding.calibration_from_shifts(shifts: dict[str, Any], pulse_time: float, binning: int = 1) → dict[str, Any]

Guider calibration from the star shift that each guide direction causes.

The camera axes do not need to be aligned with RA and Dec. Each mount axis is assigned to the camera axis it is closest to, and the remaining rotation is returned as ANGLE, which the guider removes before it computes the corrections.

Parameters:

• shifts (dict) – For “North”, “South”, “East” and “West”, the mean shift (x, y) in pixels that Donuts measured after a pulse of pulse_time milliseconds in that direction.

• pulse_time (float) – Pulse duration in milliseconds.

• binning (int, optional) – Camera binning during the calibration.

Returns:

dict –

PIX2TIME, RA_AXIS, DIRECTIONS and ANGLE (degrees) for the guider

configuration.

Raises:

ValueError – If the shifts do not fit two perpendicular axes.

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.

Averages the shift of each guide direction over all cycles and derives PIX2TIME, RA_AXIS, DIRECTIONS and the camera ANGLE from them.

Raises:

ValueError – If a direction has no measurements, or the shifts do not fit two perpendicular axes.

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.