Metadata-Version: 2.4
Name: astrafocus
Version: 0.1.2
Summary: A package that provides flexible autofocus procedures for telescopes.
Author-email: David Degen <ddegen@ethz.ch>
License: MIT
Project-URL: Bug Tracker, https://github.com/dgegen/astrafocus/issues
Project-URL: Homepage, https://github.com/dgegen/astrafocus
Project-URL: Source, https://github.com/dgegen/astrafocus
Keywords: telescope,autofocus
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astropy
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: photutils
Requires-Dist: scipy
Requires-Dist: sqlite3worker
Requires-Dist: statsmodels
Provides-Extra: alpaca
Requires-Dist: alpyca; extra == "alpaca"
Provides-Extra: extended
Requires-Dist: scikit-learn; extra == "extended"
Provides-Extra: visualization
Requires-Dist: ipython; extra == "visualization"
Requires-Dist: matplotlib; extra == "visualization"
Requires-Dist: notebook; extra == "visualization"
Dynamic: license-file

# AstrAFocus

A Python package for automated telescope focusing.

<p align="center">
   <img src="docs/logo.png" alt="logo image" width="45%" style="margin: 20px;">
</p>

*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](https://dgegen.github.io/astrafocus/)**

## Installation

```bash
pip install astrafocus
```

Or from source using [uv](https://docs.astral.sh/uv/):

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

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

```bash
uv sync --group dev --group docs --group test
```

Optional extras:

```bash
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

```python
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](https://dgegen.github.io/astrafocus/notebooks/getting_started.html) 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](https://github.com/ppp-one/gaia-tmass-sqlite).

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