astra.autofocus

Automated telescope autofocus system for astronomical observations.

This module provides a comprehensive autofocus system for astronomical telescopes, integrating with ALPACA devices and the astrafocus library. It supports various focus measurement operators, automatic target selection using Gaia catalog data, and sophisticated focusing algorithms for optimal image quality.

Key components: - Camera, focuser, and telescope interfaces for ALPACA devices - Automated target selection using Gaia star catalog - Multiple focus measurement algorithms (HFR, FFT, variance-based) - Defocusing and refocusing capabilities - Comprehensive logging and result visualization

Classes:

AstraCamera: Camera interface for autofocus operations AstraFocuser: Focuser interface with position control AstraTelescope: Telescope interface for positioning AstraAutofocusDeviceManager: Device coordination for autofocus Defocuser: Controlled defocusing and refocusing operations Autofocuser: Main autofocus orchestrator with target selection

Classes

AstraAutofocusDeviceManager(observatory, ...)	Device manager for Astra autofocus operations.
AstraCamera(observatory, ...[, maxadu])	Camera interface for autofocus operations with ALPACA devices.
AstraFocuser(observatory, alpaca_device_focuser)	Focuser interface for Astra observatory automation system.
AstraTelescope(observatory, ...)	Telescope interface for Astra observatory automation system.
Autofocuser(observatory, action, paired_devices)	Main autofocus orchestration class for Astra observatory.
Defocuser(observatory, paired_devices[, action])	Defocusing control for creating intentionally out-of-focus images.

class astra.autofocus.Autofocuser(observatory: Any, action: Action, paired_devices: PairedDevices, autofocuser: NonParametricResponseAutofocuser | AnalyticResponseAutofocuser | None = None, success: bool = True)

Bases: object

Main autofocus orchestration class for Astra observatory.

Coordinates complete autofocus operations including target selection, focus measurement, and optimization using multiple algorithms.

Parameters:

• observatory (Any) – Main Astra instance for system coordination.

• action (Action) – Action configuration for the autofocus.

• paired_devices (PairedDevices) – Device manager for observatory components.

• action_value (dict) – Configuration values for autofocus action.

• save_path (Optional[Path]) – Directory path for saving autofocus data.

• autofocuser (Optional[Union[NonParametricResponseAutofocuser, AnalyticResponseAutofocuser]]) – Specific autofocus algorithm instance.

• success (bool) – Success flag for autofocus operation.

property best_focus_position: int

Get the best focus position found by the autofocuser.

Returns:

int – Optimal focus position determined by autofocus algorithm.

Raises:

ValueError – If autofocuser has not been set up yet.

run() → bool

Execute the autofocus sequence.

Runs the complete autofocus operation using the configured algorithm.

Returns:

bool – True if autofocus completed successfully, False otherwise.

setup() → None

Set up the autofocus system with devices and algorithms.

Configures camera, focuser, telescope interfaces and initializes the autofocus algorithm with specified parameters.

_setup() → None

Internal setup method for autofocus configuration.

Configures save paths, device managers, focus measure operators, and autofocus algorithms based on action values.

determine_autofocus_calibration_field()

Determine optimal celestial coordinates for autofocus operation.

Selects suitable star field for autofocus using Gaia catalog data and zenith neighborhood analysis. Uses various selection criteria including magnitude ranges, field of view, and star density preferences.

Selection methods:

• ‘single’: Isolated star closest to zenith

• ‘maximal’: Star with maximum neighbors in field

• ‘any’: Any suitable star closest to zenith

Updates self.config.calibration_field.coordinates with selected coordinates or sets self.success to False if no suitable field found.

_determine_autofocus_calibration_field() → None

Determine the calibration field for the autofocus using config attributes.

slew_to_calibration_field() → None

Slew telescope to the determined autofocus calibration field.

Moves the telescope to the coordinates selected for autofocus operations. Updates action_value with target coordinates and initiates observatory setup.

reduce_exposure_time(autofocus_device_manager: AstraAutofocusDeviceManager, exposure_time: float, reduction_factor: float = 2, max_reduction_steps: int = 5, minimal_exposure_time: float = 0.1) → float

Automatically reduce exposure time to prevent saturation.

Takes test exposures and progressively reduces exposure time if saturation is detected, ensuring optimal image quality for focus measurements.

Parameters:

• autofocus_device_manager (AstraAutofocusDeviceManager) – Device manager for camera access.

• exposure_time (float) – Initial exposure time in seconds.

• reduction_factor (float) – Factor by which to reduce exposure time.

• max_reduction_steps (int) – Maximum number of reduction iterations.

• minimal_exposure_time (float) – Minimum allowed exposure time.

Returns:

float – Optimal exposure time that avoids saturation.

make_summary_plot() → None

Create visualization plot of autofocus results.

Generates a summary plot showing focus measure vs focuser position with the determined best focus position marked. Saves plot to the autofocus results directory.

create_result_file() → None

Create text file with autofocus results summary.

Writes a summary file containing the best focus position, algorithm used, and autofocuser configuration for future reference.

_initialise_logging() → None

Set up logging integration with astrafocus library.

Configures the astrafocus logger to use Astra’s logging system for consistent log formatting and storage.

_check_conditions() → bool

Verify observatory conditions are suitable for autofocus.

Checks weather, equipment status, and other conditions before proceeding with autofocus operations.

Returns:

bool – True if conditions are acceptable, False otherwise.

save_best_focus_position() → None

Save determined best focus position to observatory configuration.

Updates the focuser configuration with the optimal focus position found during autofocus operation for future use.

determine_focus_measure_operator()

Select focus measurement algorithm from configuration.

Determines the appropriate focus measure operator based on user preferences, supporting various algorithms like HFR, 2D Gaussian, FFT, and variance-based methods.

Returns:

Tuple[Any, str] – Focus measure operator class and descriptive name.

determine_extremum_estimator()

Select extremum estimation algorithm for focus curve analysis.

Chooses appropriate curve fitting method for determining optimal focus from focus measure vs position data. Supports LOWESS, median filter, spline, and RBF methods.

Returns:

astrafee.RobustExtremumEstimator – Configured extremum estimator instance.

calculate_field_of_view(paired_devices)

Calculate the field of view of the camera-telescope system.

determine_default_field_of_view(paired_devices, default_dict)