Autofocus

HFR/HFD-based autofocus with one rule: First Light once, Refocus forever. First Light is part of setting a focuser up — you run it once, and it measures the focuser's refocus formula. From then on it is Refocus: from the Console, in every plan, on every night, with no numbers to tune (v22.2.15).

Why one First Light is enough

Through focus, a star's half-flux radius follows a hyperbola:

HFR(x)² = a² + b² · (x − focus)²

On the reference rig the slope was 0.022 px/step on a night of HFR 1.18 and 0.020 px/step on a night of HFR 1.83: the seeing changed, the slope did not. A refocus sized for one night's seeing reads "flat" on a worse one — that is how a fixed refocus sweep used to fail. Sizing the sweep from the slope and the stars of the night does not.

The focuser's backlash (lost motion when it reverses) is the other constant. First Light measures both, once.

First Light — once, when you set up a focuser

Console → Focuser card → First Light… → Start First Light. Until it has run, the card's badge says First Light needed.

Before you start:

What it does:

  1. The stars here — three frames at the starting position, which also measure how much the star size jitters (the noise).
  2. The scale of the V — symmetric probes either side, doubling in size, until the star size curves clearly. A probe that loses its stars on one side walks towards the smaller stars. This finds focus roughly, from wherever you started on the V.
  3. The V-curve — 15 frames around that estimate, out to about 2.4 × the smallest star, every frame approached inward after a generous over-travel (the backlash is not known yet). The hyperbola fitted through them gives focus, the slope b and the seeing a. Points from stars too big to measure, or too few to trust, are left out. If the vertex sits off-centre, the V is swept again around it.
  4. The backlash — the same V swept again from the other side. The lost motion moves the vertex; the shift is the backlash. A backlash bigger than the sweep is followed until the vertex is found.
  5. The formula — b (in pixels per step at the AF binning, and in microns per step at the sensor when the pixel size is known), the backlash and the over-travel that clears it (1.5 × the backlash plus a quarter of the focus zone), the range factor and the points per side.
  6. The check — two refocuses with the formula, one starting outside focus and one inside. Both must land within 0.3 focus zones (a / b) of First Light's focus. The formula is saved as validated or not; the badge says which.

Run First Light again only when the telescope or the focuser changes. Starship ties the formula to the focuser (its ASCOM driver, or its Alpaca device): a different focuser shows First Light needed again. A different camera or AF binning is converted, not re-measured (the slope is kept in microns at the sensor). Seeing, temperature, filters and a moved focus position never need it. A plan never runs First Light.

Refocus — every time after

Console → Refocus, a plan's autofocus action, a refocus trigger: all the same refocus.

  1. The stars where the focuser stands — one frame, approached inward.
  2. The sweep — ± refocus_range_factor (1.5) × that star size / b, in 11 frames. Because a star can never be smaller than b × its distance from focus, focus is always inside that sweep; and when the rig is already in focus the ends of the sweep reach 1.8 × the smallest star, whatever the seeing — a clear V. A bigger drift or a worse night just makes the sweep wider.
  3. Every frame approached inward, after an over-travel bigger than First Light's measured backlash.
  4. The fit — the hyperbola through the frames (with the known slope as a cross-check and a fallback for a shallow or one-sided sweep). If the vertex is off the centre of the sweep, it sweeps again around it.
  5. The landing — inward onto the vertex, then one frame there to report the stars at focus.

What it does when things are not normal:

Typical cost: 13 frames when focus is near (12 for the sweep and the check, 1 to size it), about 24 when it has drifted off the first sweep's centre.

Travel limits and refused moves

Since v23, First Light and Refocus plan their sweeps inside the focuser's travel: the driver's own maximum and your [focuser] in_limit_steps / out_limit_steps (Settings → Focuser). Before v23 only the driver's maximum was used, so near one of your limits the over-travel was refused and the samples were taken without their backlash clearance.

If a refocus fails with "the focuser refused the move", check in_limit_steps and out_limit_steps against where focus is.

A follower focuser

New in v23. On a piggyback rig the follower train's focuser has its own First Light: Console → Focuser card → Follower First Light… (shown only when a follower train is set up). It measures the follower focuser with the follower camera and keeps its formula in its own files next to config.toml (focus_recipe_follower.json, focuser_report_follower.json). The card shows follower: First Light ✓ or follower: First Light needed.

Once the follower has a formula, its refocus is the formula refocus too. Until then it refocuses the older way. The follower uses the lead's [autofocus] settings.

Before First Light (older recipes)

A rig whose focus_recipe.json was written by an older wizard (no formula in it) still refocuses the older way until First Light runs, and the Console and the run journal say "First Light needed". That older refocus re-traces the recipe's sweep around the current position (refocus_step_frac, refocus_points_per_arm), widens a flat sweep up to refocus_widen_max times (a side "rises" when its outer HFR is refocus_rise_frac above the floor) and keeps the position when a widest flat sweep sits at the in-focus HFR. It is what failed on rigs whose seeing changed or whose backlash was larger than the recipe's clearance — run First Light once.

The files

Next to config.toml:

Forget First Light deletes the calibration and sets the recipe aside as focus_recipe.json.bak: First Light has to run again.

Running it

Console → Focuser card:

The badge shows the last focus and First Light ✓ (hover for the slope and backlash), First Light ✓ (not validated), or First Light needed with the reason.

Endpoints: POST /api/console/autofocus/first-light (the older name /adaptive-first-light does the same), /refocus, /goto-focus, /clear, /approve-focuser-report; GET /api/console/autofocus/calibration returns the recipe and first_light (status ok / missing / legacy / stale, and the formula's numbers). Every sample is logged to the ops log as pos … HFD=… (N stars).

In sequences

The Sequencer runs Refocus two ways, both synchronous and cancelable (the sequence's Stop reaches it):

A plan never runs First Light. Without it, the plan's refocus is the older one and the journal says once per run that First Light has not been run for this focuser.

Two extras apply after a focus completes:

A refocus failure mid-sequence is journaled but does not abort the run (fail-soft), and the camera is restored to full-frame / bin 1 afterwards so science captures are unaffected. The V-curve streams live into the sequence run view as it samples.

Key tunables (Settings → Autofocus)

Measurement

Star-size thresholds: the unit

The threshold keys with hfd in their name — near_focus_hfd (4.0), vcurve_limit_hfd (12.0), max_hfd_allowed (6.0) — are compared with what autofocus measures, which is the star's half-flux radius (HFR) in pixels of the autofocus frame. Whatever the key says, the number is an HFR, not a diameter (HFD = 2 × HFR), and the pixels are pixels at the autofocus binning (af_hw_binning).

Example: with max_hfd_allowed = 6 and hfd_threshold_binning = 1, autofocus at bin 2 fails a final star above HFR 3 px in its bin-2 frame, which is the same star size on the sensor.

The Console shows the same HFR in pixels, so a number read on screen can be typed straight into Settings.

Refocus

The older refocus (before First Light) also reads refocus_step_frac, refocus_widen_max, refocus_rise_frac, fit_method, fit_r2_min and max_hfd_allowed.

Refocus triggers (sequence; master refocus_enabled off by default)

Behind the scenes

Pure NumPy — no photutils, no sep. Star detection is connected-components flood fill on a sigma-thresholded image with eccentricity, size, and saturation filtering. HFR is the radius at which cumulative flux (sorted by distance from the flux-weighted centroid) reaches half the total, within an aperture sized to the star over a local-annulus background; each sample is the median over every detected star. The hyperbola is fitted as a parabola in HFR² (exact for a defocused star), and with the slope known the vertex is a straight-line fit of HFR² − b²x². The displayed metric is HFR in pixels, the same number Settings uses. Frames captured during AF stay in memory — they are not written to the IMAGES directory.

The First Light / Refocus logic was proven on a simulated rig — the hyperbola, seeing noise up to 7 %, backlash up to twice the focus zone, stars lost or flattening beyond a measurement limit, either focuser direction — over hundreds of random rigs and thousands of nights before it met the sky.

What's deferred

See the Roadmap topic: a min/max focus-altitude guard. Temperature compensation between refocuses is built since v23 as a fixed steps-per-degree setting (above); Starship does not learn the coefficient for you.

Astroworx Starship v23.1.2 · this page is the in-app help of that buildDownload · HTTP API