Filter wheel

Two integration paths. Most users only see one of them.

Standalone filter wheel

A filter wheel that connects independently of the camera — its own ASCOM driver or its own Alpaca service. Shows up as a separate equipment role (filterwheel) on the Console.

Setup: Settings → Filter wheel → Connection → pick ASCOM (Choose a driver) or Alpaca (Discover, then pick the device). Click Connect. Once connected, the filter dropdown on the Console capture card auto-populates with the wheel's filter names, and the Move button next to it moves the wheel to the selected filter without taking a frame.

Camera-attached filter wheel

A filter wheel that's part of the camera (QHY internal, ZWO ASI integrated wheels). The camera driver exposes the filter as a property; there's no separate equipment role.

For now, Starship supports both via the standalone path — if the camera vendor provides an ASCOM filter wheel driver wrapping their integrated wheel, use that. Native pass-through (camera driver exposes filters directly) isn't implemented yet.

Filter names

There are two sources of filter names, and they combine.

The wheel driver reports its names via Names (ASCOM) or /names (Alpaca). If the wheel returns ["Filter 1", "Filter 2", "Filter 3"], that's what it reports.

The Filter library (Settings → Filter wheel → Filter library) is where you name your own filters. Because the set of filters depends on the rig — a mono wheel of L/R/G/B/Ha/OIII/SII, or a colour camera behind a wheel of dual-band filters — you define the list yourself. Library names take priority; any driver-reported names you didn't list are appended after them. If you leave the library empty, Starship falls back to the wheel driver's reported names, and if there are none either, to the built-in defaults L, R, G, B, Ha, OIII, SII.

These combined names are what you see everywhere a filter is chosen: the Console capture card, the focuser Refocus dropdowns, the scheduler filter plans, and the Auto Flat planner.

What a frame is labelled with. The filename (...-<filter>-60s-...fits) and the FITS FILTER keyword carry the Filter library name for the slot that was used - never the wheel driver's generic slot label ("Filter4"), which some wheels report for every position. If the library has no entry for that slot the driver's name is used, and with no wheel at all the text you typed is kept. So name your library the way you want your files named: Luminance, Red, Green, Blue, Ha, OIII, SII.

Short forms resolve. A plan or a capture may ask for l, lum, r, g, b, h, ha, o, o3, s, s2 (or the driver's own slot name, or a slot number) and Starship still finds the right library entry, so renaming the library to full names does not break saved plans. The label written is always the library name.

One-shot colour (OSC)

If your camera's sensor type is set to Colour or DSLR (Settings → Camera), a virtual OSC filter is offered automatically in the filter dropdowns — no wheel required. An OSC camera can also sit behind a wheel of dual-band filters, so OSC is just one more selectable filter, not a separate mode: add your dual-band filters to the library alongside it.

Filter library

Settings → Filter wheel → Filter library. Add one row per filter with the + filter button. Each row has:

• Filter name — L, R, G, B, Ha, OIII, SII, OSC, or whatever your wheel carries. This is the name used everywhere, including in sequences and scheduler goals.
• Refocus exposure (s) — the autofocus exposure used when Starship refocuses on that filter. Dim narrowband needs a longer focus exposure than broadband to find enough stars (e.g. L ~4 s, RGB ~6 s, narrowband ~12 s). Leave it blank to use the global autofocus exposure (Settings → Autofocus).
• Focus offset — a per-filter focuser offset you can record alongside the filter. Leave blank for none.

Deleting a row (× button) removes that filter from the library. An empty library reverts to the driver names / built-in defaults described above.

Refocusing through a filter

On the Console, the Autofocus row has a filter dropdown next to Refocus. Pick a filter and Refocus moves the wheel to that slot first, then focuses through it using that filter's library refocus exposure. Choose "Current filter" to focus through whatever's in the beam without moving the wheel. A library-only or virtual filter (like OSC) that isn't an actual slot on the wheel is used for its exposure but the wheel isn't moved.

Autofocus can also refocus automatically on a filter change during a run — see Refocus on filter change in Settings → Autofocus.

Sequencer integration

Sequencer events use the filter name, not its position. A filter step carries name = "L" (or a position index if you prefer). At run time the executor looks up the slot by name — case-insensitively — in the wheel's reported names and moves there.

Two graceful behaviours worth knowing:

• No wheel connected (e.g. a one-shot-colour camera imaging unfiltered): a filter step is a harmless no-op, not a sequence-failing error, so a stray filter L step won't abort the run.
• Name not found: if a wheel is connected but the requested name isn't one of its slots, that step fails. By default a failing step aborts the sequence; set the step's On error to skip (or continue) if you'd rather carry on past a filter typo.

After a successful filter move the sequencer applies the extra settle dwell described below.

Gotchas

A wheel that's slow to settle after a move can produce frames where the filter motion is still visible. Starship has a built-in Additional safe time after filter change setting (Settings → Camera): an extra dwell, in seconds, applied after every filter move in both single captures and sequences. Set it to a second or two if your wheel needs to settle; 0 = no dwell. If your wheel's own driver offers a comparable "additional safe time" option you can use that instead — the two add up, so don't double it.