astra.guiding

astra.guiding#

Astronomical telescope autoguiding system with PID control.

This module provides automated guiding functionality for astronomical telescopes using image-based tracking with PID control loops. It implements the complete guiding workflow from image acquisition to telescope correction commands.

Key Features: - Real-time star tracking using the Donuts image registration library - PID control loops for precise telescope corrections - Database logging of guiding performance and corrections - Support for German Equatorial Mount (GEM) pier side changes - Outlier rejection and statistical analysis of guiding errors - Automatic reference image management per field/filter combination - Background subtraction and image cleaning for robust star detection

The system continuously monitors incoming images, compares them to reference images, calculates pointing errors, and applies corrective pulse guide commands to keep the telescope accurately tracking celestial objects.

Components:

CustomImageClass: Image preprocessing for robust star detection Guider: Main autoguiding class with PID control PID: Discrete PID controller implementation

Classes

Guider(telescope, logger, database_manager, ...)

Automated telescope guiding system with PID control and statistical analysis.

GuiderManager(guider_dict, logger, ...)

guider_dict: dict[str, Guider] - mapping telescope names to Guider instances logger: logging.Logger or ObservatoryLogger database_manager: DatabaseManager

PID([kp, ki, kd, derivator, integrator, ...])

Discrete PID controller for autoguiding corrections.
class astra.guiding.GuiderManager(guider_dict, logger, database_manager)[source]#

Bases: object

guider_dict: dict[str, Guider] - mapping telescope names to Guider instances logger: logging.Logger or ObservatoryLogger database_manager: DatabaseManager

classmethod from_observatory(observatory) → GuiderManager[source]#
start_guider(image_handler: ImageHandler, paired_devices: PairedDevices, thread_manager: ThreadManager, reset_guiding_reference: bool = True) → bool[source]#

Start the autoguiding system for telescope tracking.

Initializes and starts the guiding system to maintain accurate telescope tracking during long exposures. Creates a separate thread for guiding operations to run concurrently with image acquisition.

Parameters:

  • image_handler (ImageHandler) – Image handler for managing image files.

  • paired_devices (PairedDevices) – Object containing telescope and guide camera devices for the guiding system.

  • thread_manager (ThreadManager) – Thread manager for tracking guiding thread.

  • reset_guiding_reference (bool, optional) – If True, clears existing reference image from database before starting guiding, forcing creation of a new reference. Defaults to True.

Returns:

bool – True if guider was started successfully, False otherwise.

Process: 1. Logs guiding start for the specified telescope 2. Optionally clears existing reference image if reset flag is set 3. Creates guider thread with appropriate parameters 4. Starts the guiding thread in background 5. Adds thread to observatory’s thread tracking list

Note

  • Guiding runs in a separate thread to avoid blocking main operations

  • Thread is tracked in self.threads for proper cleanup

  • Filter name formatting removes single quotes for compatibility

stop_guider(telescope_name, thread_manager)[source]#

Stop guiding for a given telescope.

This function finds the correct guider thread using the telescope’s device name, sets its running flag to False, and then waits for the thread to terminate.

Parameters:

telescope_name (str) – The name of the telescope whose guider should be stopped.

Returns:

bool – True if the guider was stopped successfully, False otherwise.

class astra.guiding.Guider(telescope: Any, logger: ObservatoryLogger, database_manager: DatabaseManager, params: Dict[str, Any])[source]#

Bases: object

Automated telescope guiding system with PID control and statistical analysis.

Implements a complete autoguiding solution that continuously monitors telescope pointing accuracy and applies corrective pulse guide commands. Features include PID control loops, outlier rejection, database logging, and support for German Equatorial Mounts with pier side changes.

The guider maintains statistical buffers for error analysis, handles field stabilization periods, and manages reference images per field/filter combination.

telescope#

Alpaca telescope device for pulse guiding commands

observatory#

Astra observatory instance for logging and database access

PIX2TIME#

Pixel-to-millisecond conversion factors for guide pulses

DIRECTIONS#

Mapping of guide directions to Alpaca constants

RA_AXIS#

Which axis (x/y) corresponds to Right Ascension

PID_COEFFS#

PID controller coefficients for x and y axes

running#

Flag to control guiding loop execution

Example

>>> guider = Guider(telescope, astra_instance, {
...     "PIX2TIME": {"+x": 100, "-x": 100, "+y": 100, "-y": 100},
...     "DIRECTIONS": {"+x": "East", "-x": "West", "+y": "North", "-y": "South"},
...     "RA_AXIS": "x",
...     "PID_COEFFS": {"x": {"p": 0.8, "i": 0.1, "d": 0.1}, ...}
... })
>>> guider.guider_loop("camera1", "/data/*.fits")

Initialize the autoguider with telescope, logging, and PID parameters.

Parameters:

  • telescope – Alpaca telescope device for sending pulse guide commands.

  • logger – Astra observatory logger for logging messages.

  • database_manager – Astra database manager for logging guiding data.

  • params (dict) – Configuration dictionary containing: - PIX2TIME: Pixel to millisecond conversion factors - DIRECTIONS: Guide direction mappings - RA_AXIS: Which axis corresponds to RA (“x” or “y”) - PID_COEFFS: PID controller coefficients for both axes

create_tables() → None[source]#

Create database tables for autoguider reference images and logging.

Creates three tables: - autoguider_ref: Reference image metadata and validity periods - autoguider_log: Detailed guiding corrections and statistics - autoguider_info_log: General status and info messages

logShiftsToDb(qry_args: Tuple[str, ...]) → None[source]#

Log autoguiding corrections and statistics to the database.

Parameters:

qry_args (tuple) – Tuple containing guiding data in order: night, reference, comparison, stabilised, shift_x, shift_y, pre_pid_x, pre_pid_y, post_pid_x, post_pid_y, std_buff_x, std_buff_y, culled_max_shift_x, culled_max_shift_y

logMessageToDb(camera_name: str, message: str) → None[source]#

Log status messages to the database.

Parameters:

  • camera_name (str) – Name of the camera being autoguided.

  • message (str) – Status or info message to log.

guide(x: float, y: float, images_to_stabilise: int, camera_name: str, binning: int = 1, gem: bool = False) → Tuple[bool, float, float, float, float][source]#

Apply telescope guiding corrections using PID control with outlier rejection.

Processes measured pointing errors through PID controllers, applies outlier rejection during stable operation, and sends pulse guide commands to the telescope. Handles declination scaling for RA corrections and German Equatorial Mount pier side changes.

Parameters:

  • x (float) – Guide correction needed in X direction (pixels).

  • y (float) – Guide correction needed in Y direction (pixels).

  • images_to_stabilise (int) – Images remaining in stabilization period. Negative values indicate stable operation.

  • camera_name (str) – Name of the camera for logging.

  • binning (int, optional) – Image binning factor. Defaults to 1.

  • gem (bool, optional) – Whether telescope is German Equatorial Mount. Defaults to False.

Returns:

tuple –

(success, pidx, pidy, sigma_x, sigma_y) where:

  • success (bool): Whether correction was applied

  • pidx, pidy (float): Actual corrections sent to mount

  • sigma_x, sigma_y (float): Buffer standard deviations

getReferenceImage(field: str | None, filt: str | None, exptime: str | None, camera: str, pierside: int) → str | None[source]#

Retrieve the current reference image path for given observation parameters.

Parameters:

  • field (str) – Target field name.

  • filt (str) – Filter name.

  • exptime (str) – Exposure time.

  • camera (str) – Camera name.

  • pierside (int) – Telescope pier side (1=West, 0=East, -1=Unknown).

Returns:

str | None – Path to reference image, or None if not found.

clearReferenceImage(field: str | None, filt: str | None, exptime: str | None, camera: str, pierside: int) → None[source]#

Clear reference image from the database for given observation parameters.

Sets valid_until to current time for matching reference images, effectively invalidating them so a new reference will be created on next guiding run.

Parameters:

  • field (str) – Target field name.

  • filt (str) – Filter name.

  • exptime (str) – Exposure time.

  • camera (str) – Camera name.

  • pierside (int) – Telescope pier side (1=West, 0=East, -1=Unknown).

setReferenceImage(field: str | None, filt: str | None, exptime: str | None, ref_image: str, camera: str, pierside: int) → None[source]#

Set a new reference image in the database and copy to reference directory.

Parameters:

  • field (str) – Target field name.

  • filt (str) – Filter name.

  • exptime (str) – Exposure time.

  • ref_image (str) – Path to image file to use as reference.

  • camera (str) – Camera name.

  • pierside (int) – Telescope pier side (1=West, 0=East, -1=Unknown).

waitForImage(camera_name: str, image_handler: ImageHandler) → Tuple[str | None, str | None, str | None, str | None][source]#

Wait for new images to appear in the monitoring directory.

Parameters:

  • camera_name (str) – Camera name for logging.

  • image_handler (ImageHandler) – Image handler instance to monitor.

Returns:

tuple –

(newest_image, newest_field, newest_filter, newest_exptime)

Returns (None, None, None, None) if self.running becomes False.

guider_loop(camera_name: str, image_handler: ImageHandler, binning: int = 1) → None[source]#

Main autoguiding loop using image_handler for new images. Continuously monitors image_handler.last_image_path and last_image_timestamp, processes new images, updates reference images, measures shifts, and applies guiding corrections.

class astra.guiding.PID(kp: float = 0.5, ki: float = 0.25, kd: float = 0.0, derivator: float = 0, integrator: float = 0, integrator_max: float = 500, integrator_min: float = -500)[source]#

Bases: object

Discrete PID controller for autoguiding corrections.

Implements a digital PID control loop with configurable proportional, integral, and derivative gains. Includes integrator clamping to prevent windup.

Based on: http://code.activestate.com/recipes/577231-discrete-pid-controller/

Parameters:

  • kp (float, optional) – Proportional gain. Defaults to 0.5.

  • ki (float, optional) – Integral gain. Defaults to 0.25.

  • kd (float, optional) – Derivative gain. Defaults to 0.0.

  • derivator (float, optional) – Initial derivative term. Defaults to 0.

  • integrator (float, optional) – Initial integrator value. Defaults to 0.

  • integrator_max (float, optional) – Maximum integrator value. Defaults to 500.

  • integrator_min (float, optional) – Minimum integrator value. Defaults to -500.

update(current_value: float) → float[source]#

Calculate PID output for given input and feedback.

Parameters:

current_value (float) – Current process value (feedback).

Returns:

float – PID controller output.

initialize_set_point(set_point: float) → None[source]#

Initialize the PID setpoint and reset integrator/derivator.

Parameters:

set_point (float) – Desired target value.

classmethod from_config_dict(config: Dict[str, float]) → PID[source]#

Create a PID instance from a configuration dictionary.

Parameters:

config (dict) – Configuration with keys ‘p’, ‘i’, ‘d’

Contents