astrafocus 0.1.3

A package that provides flexible autofocus procedures for telescopes.

AstrAFocus

A Python package for automated telescope focusing.

AstrAFocus solves two problems: finding suitable sky regions for focus calibration, and performing the autofocus sweep itself. It is hardware-agnostic — connect real devices by implementing two small interface classes, or use the built-in simulators for development and testing.

Documentation

Installation

pip install astrafocus

Or from source using uv:

git clone https://github.com/dgegen/astrafocus.git
cd astrafocus
uv sync

For development (includes linting, docs, and test dependencies):

uv sync --group dev --group docs --group test

Optional extras:

pip install "astrafocus[alpaca]"       # ASCOM Alpaca device support (alpyca)
pip install "astrafocus[visualization]" # matplotlib, IPython, notebook
pip install "astrafocus[extended]"     # scikit-learn for additional estimators

Quick start

from astrafocus.interface.simulation import CabaretDeviceSimulator
from astrafocus.autofocuser import AnalyticResponseAutofocuser
from astrafocus.star_size_focus_measure_operators import HFRStarFocusMeasure

simulator = CabaretDeviceSimulator(current_position=11_000, allowed_range=(9_000, 13_000))

autofocuser = AnalyticResponseAutofocuser(
    autofocus_device_manager=simulator,
    exposure_time=3.0,
    focus_measure_operator=HFRStarFocusMeasure,
    n_steps=(20, 10),
)
autofocuser.run()
print(f"Best focus position: {autofocuser.best_focus_position}")

See the Getting Started notebook for a full walkthrough, or explorations/speculoos_main.py for a more complete real-world example.

Key components

Autofocus

• AnalyticResponseAutofocuser — sweeps the focuser through a range of positions, measures focus quality, and fits an analytic curve (e.g. parabola) to locate the optimum.
• NonParametricResponseAutofocuser — same sweep strategy, but uses a non-parametric smoother (LOWESS, spline, or RBF) instead of an analytic fit. Works with any focus measure operator.
• FocusMeasureOperatorRegistry — 13 built-in operators: star-size estimators (hfr, gauss) and image-sharpness metrics (fft, tenengrad, laplacian, brenner, …).

Sky targeting

• ZenithNeighbourhoodQuery — queries a Gaia-2MASS catalogue (local SQLite or remote) to find a region near zenith with a suitable density of stars for focus calibration.

Hardware interface

Connect real hardware by implementing two classes:

• CameraInterface — one method: perform_exposure(texp).
• FocuserInterface — one method: move_focuser_to_position(position).

Wrap them in AutofocusDeviceManager and pass it to any autofocuser. For hardware-free development and testing, use the built-in CabaretDeviceSimulator (synthetic images) or ObservationBasedDeviceSimulator (replay from FITS files).

The Gaia-2MASS Local Catalogue

The sky-targeting component requires a local Gaia-2MASS catalogue, available at ppp-one/gaia-tmass-sqlite.

Citation

If you use AstraFocus in your research, please cite it. A DOI is minted via Zenodo for each release. Use the Cite this repository button on GitHub for an up-to-date citation in your preferred format.

May your stars align and your focus be as sharp as a caffeinated owl spotting its prey!