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)²
- b — how fast the stars grow per focuser step — is set by the telescope's focal ratio and the focuser's travel per step. It is the same every night.
- a — the smallest star — is the seeing. It changes every night.
- focus — drifts with temperature and filters.
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:
- Focus roughly by hand so stars show.
- A normal star field, tracking on, mount settled — and the optical train as you image with it.
- Nothing to enter. It takes about 70 frames (10–15 minutes) and leaves the scope focused.
What it does:
- The stars here — three frames at the starting position, which also measure how much the star size jitters (the noise).
- 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.
- 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.
- 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.
- 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.
- 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.
- The stars where the focuser stands — one frame, approached inward.
- 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. - Every frame approached inward, after an over-travel bigger than First Light's measured backlash.
- 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.
- The landing — inward onto the vertex, then one frame there to report the stars at focus.
What it does when things are not normal:
- No stars where it starts (something moved the focuser a long way): it tries the last focus position, then looks either side in growing steps.
- The same star size everywhere: the formula says the stars should have changed, so this is a real fault — the focuser is not moving, or cloud is spoiling the frames — and Refocus says so, after one look for smaller stars elsewhere. The focuser goes back to where it started.
- A V steeper or shallower than First Light's (by more than a third): the refocus still lands, and its note says the telescope or focuser may have changed.
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.
- A focuser move the sweep depends on being refused fails the run. It is not treated as a shorter sweep. The message names the position and the reason, and the focuser is sent back to where it started.
- First Light saves nothing when that happens.
- A landing whose over-travel was refused is a failure too. Without the over-travel the focuser can sit up to one backlash away from the focus the sweep measured.
- Refocus needs room for its over-travel. If your focus position sits within the backlash clearance of a limit, the refocus fails there; widen the limit when the mechanics allow it.
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:
focus_recipe.json— the last focus position (focus_position, updated by every good refocus, used by Go to focus) and First Light'sformula:slope_px_per_step,slope_um_per_step,af_binning,pixel_um,min_hfr_px(First Light's seeing),backlash_steps,backlash_measured,backlash_clear,range_factor,points_per_arm,focuser(which focuser it belongs to),validatedand the twovalidationrefocuses. The formula is First Light's and is never changed by a refocus.focuser_report.json— First Light's report: the slope, the smallest star, the focus zone, the backlash, the validation, the V-curve and a step-by-step story of the run. Use the measured backlash for manual moves (Settings → Focuser) copies the backlash into[focuser]for the jog buttons too; Refocus uses it without that.autofocus_calibration.json— every First Light's V-curve run, kept for history.
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:
- First Light… — set the focuser up, once (lit up while the focuser needs it).
- Filter dropdown — pick a filter to focus through. Refocus moves the wheel there first, then focuses at that filter's exposure; leave it on Current filter to focus where you are. The slope is the same for every filter.
- Refocus — the formula refocus around the current position.
- Go to focus — moves the focuser straight back to the last focus position.
- Forget First Light — throw the set-up away; First Light has to run again before Refocus works.
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):
- An
autofocusaction step, placed explicitly in the plan. - Refocus triggers. These fire a refocus before the next exposure whenever a condition is met: every N frames, every X minutes, on filter change, on focuser temperature drift, or (v23, opt-in) when the stars have grown. Since v23 a time or temperature refocus that comes due runs between two subs instead of waiting for the end of the block, and a refocus due in the last 10 minutes before the plan's end is skipped (see the Sequencer topic). They come from the plan's own focus policy, and — when you turn on the master Enable auto-refocus switch in Settings → Autofocus → Refocus triggers — from the global
[autofocus].refocus_*fields (refocus_every_n_frames,refocus_every_n_minutes,refocus_on_filter_change,refocus_on_temp_delta_c), which overlay onto whatever the plan set. The master switch is off by default. Afocuser_positionfallback drives to a fixed position when no calibrated autofocus is available.
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:
- Focus final offset (
focus_final_offset_steps) — shifts the focuser by a fixed number of steps after every successful focus (for example, an AF-filter-to-imaging-filter offset). - Per-filter focuser offsets (
filter_offsets, e.g.{"L":0,"R":30,"Ha":120}) — on a filter change the focuser shifts by the delta between filters instead of running a full refocus, so a colour-filter swap doesn't cost a whole AF sweep. Empty = off.
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
exposure_s(5.0) /af_hw_binning(2) — AF exposure and hardware binning for every sample (0= use the acquisition binning). Changing the binning later does not need a new First Light.af_hw_roi_pct(30) — centred hardware subframe % for AF frames; 0 or ≥100 = full framecentral_region_pct(75) — only stars within this central fraction of the (sub)frame are measureddetection_sigma(3.0) — star-detection threshold (lower than science = 5, so defocused stars are still found)star_flux_min_k/star_flux_max_k(×1000 ADU; 0 = off) — detection flux gatesmin_stars(1; new in v23) — the fewest measured stars a focus frame needs. A frame with fewer reads as "no stars" at that position. 1 = any star counts, as before. Raise it if a lone star in thin cloud has been steering your sweeps.
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).
hfd_threshold_binning(0; new in v23; config file only) — which binning the thresholds were written for.0= they are HFR pixels at the autofocus binning in use, compared as they stand (the behaviour before v23).N= they are HFR pixels at bin N, and Starship rescales them to the autofocus binning in use, so changingaf_hw_binninglater does not change what they mean.
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
refocus_range_factor(1.5) — the sweep is ± this × the star size where Refocus starts / First Light's slope. 1.5 puts the ends of an in-focus sweep at 1.8 × the smallest star.refocus_points_per_arm(5) — frames on each side of the centre (11 in a sweep)direction(OUT) — which way "out" is; every sample is approached from the other sidesettle_seconds_after_move(1.0) — wait after each focuser move
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)
refocus_every_n_frames,refocus_every_n_minutes,refocus_on_filter_change,refocus_on_temp_delta_c— the global triggers overlaid onto a running planrefocus_on_hfr_drift_pct(0 = off; new in v23) withrefocus_hfr_drift_frames(5) — refocus when the median star size of the last subs is this many percent worse than right after the last focus. Needs frame acceptance on, because the star size comes from the frame gradingtemp_comp_steps_per_c(0 = off; new in v23) withtemp_comp_min_steps(1) — temperature compensation: between subs, move the focuser this many steps per degree C of change since the last focus. The sign is the direction. This one does not need the master switch;temp_comp_min_stepsis config-file onlyfocus_final_offset_steps(0) — shift the focuser this many steps after every successful focusfilter_offsets({}) — per-filter focuser offsets; a filter change shifts by the delta instead of a full refocus
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.