argos.server

The headless server of ARGOS 0.5.0: it owns the devices, the state, the jobs, the sequences, the live photometry, Review and the exports, and serves the web interface over REST and two WebSockets. In the desktop app it runs as the frozen sidecar. Where it sits among the other parts: Architecture.

Note

The wire contract (every route, payload, event and error) is argos/server/protocol.md, written before the code. The pages below are the Python side, generated from the docstrings; the first line of each module’s docstring says what it owns. FastAPI, Starlette, pydantic, uvicorn and anyio are mocked for this build (docsrc/conf.py), so route decorators and pydantic bases are not rendered.

Headless ARGOS server — the HTTP + WebSocket back end of the web front-end.

Since 0.5.0 the desktop app is a web front-end (Svelte, in a Tauri shell) that talks to this server over http://127.0.0.1. The server drives the devices (the built-in simulator, or a Seestar through the Alpaca wrappers in argos.core.alpaca) and streams state and frames to the front-end.

No Qt, anywhere. Nothing under argos.server may import PyQt6, directly or transitively — tests/server/test_no_qt.py enforces it. The scientific core is shared with the retired PyQt6 app, which stays in the repository only as the reference for the parity tests.

The wire contract is documented in argos/server/protocol.md. Run with:

python -m argos.server [--host 127.0.0.1] [--port 8742] [--simulator] [--dev-token TOKEN]
                       [--config-dir DIR] [--log-dir DIR] [--connect-timeout S]
argos.server.API_VERSION = 2

Version of the wire contract (GET /api/health → "api"). Bump on any breaking change to routes, payloads or the binary frame layout.

argos.server.DEFAULT_PORT = 8742

Default TCP port. --port 0 lets the OS pick one (the Tauri sidecar reads the actual port from the ARGOS_PORT= line on stdout).

Process and contract

The command line, the application and its routes, authentication, the error shape, the contract’s records, the event bus and the frame wire format, jobs and the log.

Server settings — what the CLI (or a test) hands to create_app().

class argos.server.settings.Settings(token: str, host: str = '127.0.0.1', port: int = 8742, simulator: bool = False, sim: SimOptions = <factory>, config_dir: Path | None = None, log_dir: Path | None = None, log_file: Path | None = None, manage_process: bool = False, connect_timeout_s: float | None = 3.0, network_interval_s: float = 10.0, network_probe_timeout_s: float = 1.5, mount_lost_after: int = 3, mount_retry_s: float = 10.0, site_check_period_s: float = 300.0, site_check_settle_s: float = 2.0, jog_deadman_s: float = 1.0, autofocus_settle_s: float = 1.0, autofocus_poll_s: float = 0.3, desktop: bool = False)[source]

Bases: object

Runtime settings of one server instance.

Parameters:
  • token – Bearer token every protected route and WebSocket must present.

  • host – Interface the CLI bound (informational inside the app).

  • port – Port the CLI bound (informational inside the app).

  • simulator – Connect the simulator during startup (--simulator).

  • sim – Simulator parameters.

  • config_dir – Folder of config.json. None keeps the configuration in memory (defaults, never written): what tests get unless they pass a temporary folder. The CLI always passes a folder.

  • log_dir – Folder of the rotating log file and crash reports (CLI only; informational inside the app, reported by /api/app/info).

  • log_file – The rotating log file in use, if any (informational).

  • manage_process – Let the app change process-wide state: the root log level (ui.log_level) and the core modules’ cache and calibration folders (data_paths.*). The CLI sets it; in-process tests leave it off so one test’s configuration never leaks into the next.

  • connect_timeout_s – TCP pre-check budget before an Alpaca device is opened (--connect-timeout); None skips the pre-check.

  • network_interval_s – Period of the Seestar reachability probe; 0 turns the background probe off (tests), the on-demand check stays.

  • network_probe_timeout_s – TCP connect timeout of one reachability probe.

  • mount_lost_after – Consecutive failed mount polls that declare the connection lost (polling_worker.py:49: 3).

  • mount_retry_s – Period of the mount auto-reconnect (device_session.py:159: 10 s).

  • site_check_period_s – Period of the site-against-mount re-check while the mount is connected (wave 2, site_check.py: 300 s).

  • site_check_settle_s – After a site change, wait until the site has stayed unchanged this long before checking (site_check.py: 2 s).

  • jog_deadman_s – A jogging axis not renewed within this time is stopped by the server (wave 3, jog.py: 1 s).

  • autofocus_settle_s – Settle after each autofocus move (autofocus_worker.py:44: 1 s; tests shorten it).

  • autofocus_poll_s – IsMoving poll period during autofocus (autofocus_worker.py:45: 0.3 s).

  • desktop – Started by the desktop shell (--desktop, wave 8): AppInfo desktop and POST /api/fs/reveal.

class argos.server.settings.SimOptions(width: int = 1080, height: int = 1920, seed: int = 20261101, n_stars: int = 240, slew_rate_deg_s: float = 4.0, mount_poll_s: float = 0.25, focus_best: int = 5300, wheel_slot_s: float = 0.6, focuser_speed_steps_s: float = 2000.0, replay_dir: Path | None = None)[source]

Bases: object

Knobs of the built-in simulator.

The defaults describe a Seestar S50 as it delivers frames: 1080 px wide by 1920 px high (portrait — the Qt viewer’s “auto” rotation exists for exactly this). Tests shrink the frame and speed up the mount so the suite stays fast.

focus_best: int = 5300

Wave 3. Focuser position of the sharpest stars (the V-curve minimum).

focuser_speed_steps_s: float = 2000.0

Wave 3. Speed of the simulated focuser (steps/s).

mount_poll_s: float = 0.25

Mount telemetry period (s). 0.25 s is the contract’s 4 Hz ceiling.

replay_dir: Path | None = None

Wave 6a. A folder of real FITS copies the simulated camera plays in order, the simulated mount reporting their pointing (--sim-replay).

seed: int = 20261101

Base seed of the synthetic sky. Frame n is a pure function of (seed, n, exposure, gain), so a run is reproducible.

slew_rate_deg_s: float = 4.0

Simulated slew speed on each axis (deg/s).

wheel_slot_s: float = 0.6

Wave 3. Time the simulated filter wheel takes per slot (s).

FastAPI application: routes, auth, CORS and the two WebSockets.

Routes are deliberately thin — validate, call one Hub method, return its dict. They are plain def functions, so FastAPI runs them in its threadpool and a blocking device call never stalls the event loop that feeds the WebSockets.

class argos.server.app.AttentionAckBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

Wave 6b: who acknowledged (the client’s label).

class argos.server.app.AutofocusBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.CalibrationPlanBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

Wave 6b: darks per Light series and biases per gain (the guide’s 20 and 30).

class argos.server.app.CaptureBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

A23: v1’s {exposure_s, gain} stays valid; both now default to the settings.

class argos.server.app.CaptureSettingsBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

A22: one commit; the camera’s own limits are checked by the hub (never clamped).

class argos.server.app.CenterBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.CenterTargetBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.ConnectBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.DeviceConnectBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

API 2: one device or all of them; the address defaults to the config’s.

class argos.server.app.DiscoveryBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.ExposureBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.FieldAutoBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.FieldSolveBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

POST /api/field/solve: no option today (strict: unknown fields refused).

class argos.server.app.FilterSelectBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.FocuserMoveBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.FocuserStepBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.GotoBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.JogBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

pause_run: bool = False

“Pause the run and slew” (the interlock, PROPOSAL §7).

Type:

Wave 6a

renew: bool = False

it never restarts an axis the server stopped.

Type:

A periodic renewal

class argos.server.app.JogStopBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.LiveBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

argos.server.app.MAX_EXPOSURE_S = 3600.0

Upper bound on one exposure (s). The Seestar driver’s own ExposureMax is lower; Alpaca rejects what it cannot do.

argos.server.app.MAX_FRAME_CLIENTS = 8

Concurrent /ws/frames clients. Each one can pin an encoded frame (4 MB for a Seestar frame) in its socket buffer; past this, a newcomer is closed with 1013 (try again later).

class argos.server.app.MotionBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

Wave 6a: Park / Unpark with “Pause the run and slew”.

class argos.server.app.NetworkCheckBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.ObservationBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.ObservationTargetBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.OpenFitsBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.PendingStarBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.ProfileBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.RecommendBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.RevealBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

POST /api/fs/reveal (wave 8, A12).

class argos.server.app.SelectBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.SequenceStartBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

Wave 6a (A62): absent = the draft’s start time; null = now.

class argos.server.app.ShutdownBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

POST /api/app/shutdown (wave 8, A7).

class argos.server.app.SiteSearchBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

A82: the free-form place query (an empty one is refused with the Qt text).

class argos.server.app.StellariumBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

A19: both default to the config (stellarium.host, stellarium.port).

class argos.server.app.SupportBundleBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

A5: where to write the ZIP (null = keep it for a download) and what goes in.

class argos.server.app.SyncBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.TargetRoleBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.TrackingBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.app.TrackingRateBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

argos.server.app.app_info(settings: Settings, hub: Hub) → dict[str, Any][source]

GET /api/app/info (row A1): about, paths, help header, support summary.

argos.server.app.create_app(settings: Settings, hub: Hub | None = None) → fastapi.FastAPI[source]

Build the ASGI app. hub is injectable for tests; one is created otherwise.

argos.server.app.wire_json(message: Any) → str[source]

One /ws/events frame: strict JSON, as REST answers.

JSON.parse rejects NaN; one bad float must never make the browser drop a snapshot, so non-finite numbers go out as null (FastAPI’s REST encoding does the same).

Bearer-token authentication and the origin allow-list.

The server binds 127.0.0.1, but any web page the observer opens can still reach localhost. Two independent guards keep such pages out:

  • a per-launch random token (secrets.token_urlsafe) that every route but GET /api/health requires — as Authorization: Bearer over HTTP, as ?token= on WebSockets, because browsers cannot set WebSocket headers;

  • an origin allow-list: CORS for HTTP, and an explicit Origin check on WebSockets, which CORS does not cover;

  • a Host allow-list (loopback names only, when the server is bound to loopback) and a refusal of any HTTP request whose Origin is foreign. CORS only stops a page from reading an answer; a DNS-rebinding page is same-origin once its hostname resolves to 127.0.0.1, so it needs no preflight and its request would still run. Its Host (and Origin) name the attacker’s domain, which these checks refuse.

argos.server.auth.ALLOWED_ORIGIN_REGEX = '^(http://(localhost|127\\.0\\.0\\.1)(:\\d{1,5})?|tauri://localhost|http://tauri\\.localhost)$'

the Vite dev server or a preview on any localhost port, and the Tauri webview on each platform.

Type:

Origins the front-end can legitimately run from

argos.server.auth.LOOPBACK_HOSTS = frozenset({'127.0.0.1', '::1', 'localhost', 'tauri.localhost'})

Host names a loopback-bound server answers to (the Tauri webview included).

class argos.server.auth.TokenAuth(token: str)[source]

Bases: object

Constant-time comparison against the launch token.

require(request: fastapi.Request) → None[source]

FastAPI dependency: raise 401 unauthorized without a valid bearer token.

argos.server.auth.WS_CLOSE_UNAUTHORIZED = 4401

WebSocket close codes (4000–4999 is the application range).

argos.server.auth.allowed_hosts(bound_host: str) → frozenset[str] | None[source]

Host names to accept, or None (any) when bound to a network interface.

A server deliberately bound to a LAN address is reached under names and addresses this process cannot know; the token and the origin checks then stand alone (the CLI already warns about such a bind).

argos.server.auth.host_name(header: str | None) → str | None[source]

The host part of a Host header, lower-cased, without port or brackets.

argos.server.auth.is_loopback(host: str) → bool[source]

True for the interfaces that keep the server off the network.

argos.server.auth.make_token() → str[source]

A fresh random token for one server launch.

argos.server.auth.origin_allowed(origin: str | None) → bool[source]

True when origin may talk to the server.

A missing Origin header means a non-browser client (curl, a test, the Tauri sidecar supervisor): the token alone authenticates it.

The contract’s error envelope and the handlers that enforce it.

Every 4xx/5xx leaves the server as:

{"error": {"code": "<snake_case>", "message": "<human text>"}}

including FastAPI’s own validation failures (mapped to 400 invalid_argument), unknown routes (404 not_found) and any unexpected exception (500 internal_error, traceback in the server log), so the front-end has exactly one shape to handle.

exception argos.server.errors.ApiError(status: int, code: str, message: str, headers: dict[str, str] | None = None, details: dict[str, Any] | None = None)[source]

Bases: Exception

An error with a contract code, raised anywhere and rendered by the handler.

Parameters:
  • status – HTTP status code.

  • code – Stable snake_case identifier the front-end can switch on.

  • message – Human-readable explanation, safe to show to the observer.

  • headers – Extra response headers (WWW-Authenticate for a 401).

details

fields for a config commit, owner for a job that holds the resource.

Type:

Extra members of the error object (API 2)

class argos.server.errors.CatchAllMiddleware(app: starlette.types.ASGIApp)[source]

Bases: object

Answer an unexpected exception with the envelope, inside CORS.

Starlette sends its own 500 from the outermost layer, past the CORS middleware, so a browser would only see an opaque network failure. This pure ASGI layer sits under CORS (added before it): the 500 gets the CORS headers and the front-end can read internal_error. The traceback goes to the server log.

argos.server.errors.install_error_handlers(app: fastapi.FastAPI) → None[source]

Route every error the app can raise through error_body().

The three state records of the contract, as immutable snapshots.

ConnectionState, CameraState and MountState are frozen dataclasses: the hub swaps whole records under its lock and hands the same objects to any thread, so a reader can never observe a half-updated state. to_dict() gives exactly the JSON shape documented in protocol.md.

argos.server.state.CAMERA_BUSY = frozenset({'downloading', 'exposing', 'live'})

Camera states during which a new exposure (or an opened file) is refused.

class argos.server.state.CameraState(state: 'CameraStateName' = 'idle', exposure_s: 'float' = 2.0, gain: 'int' = 80, last_frame_seq: 'int | None' = None, sensor: 'SensorInfo | None' = None, owner: 'CameraOwner' = 'idle', settings: 'dict[str, Any] | None' = None, current: 'dict[str, Any] | None' = None, save_pending: 'int' = 0, waiting_for: "Literal['filterwheel'] | None" = None, limits: 'dict[str, Any] | None' = None, offset: 'dict[str, int] | None' = None, binning: 'dict[str, int] | None' = None, temperature_c: 'float | None' = None)[source]

Bases: object

current: dict[str, Any] | None = None

FrameSettings of the frame being exposed now, or None.

exposure_s: float = 2.0

the frame being exposed (current) while one is, else the settings.

Type:

v1

owner: Literal['idle', 'live', 'single', 'autofocus', 'sequence'] = 'idle'

Who drives the camera (camera_service.py:60-77).

save_pending: int = 0

Take shots still waiting for their frame (0 or 1).

settings: dict[str, Any] | None = None

what the NEXT frame uses.

Type:

CaptureSettings as a dict

waiting_for: Literal['filterwheel'] | None = None

A Dark/Bias Take shot waiting for the wheel to reach Dark.

class argos.server.state.ConnectionState(state: 'ConnectionStateName' = 'disconnected', mode: "Literal['simulator', 'alpaca'] | None" = None, device_name: 'str | None' = None, message: 'str | None' = None)[source]

Bases: object

class argos.server.state.MountState(state: 'MountStateName' = 'idle', ra_hours: 'float' = 0.0, dec_deg: 'float' = 0.0, alt_deg: 'float | None' = None, az_deg: 'float | None' = None, tracking: 'bool' = False, pier_side: "Literal['east', 'west'] | None" = None, target: 'Target | None' = None, alignment: "Literal['altaz', 'eq', 'eq_gem'] | None" = None, tracking_rate: 'str | None' = None, tracking_rates: 'tuple[str, ...]' = (), goto_blocked: 'dict[str, Any] | None' = None, center_available: 'bool' = False, jog: 'dict[str, Any] | None' = None)[source]

Bases: object

discrete() → tuple[source]

Everything but the continuously moving coordinates.

A change here is a state transition and is announced with a status event; coordinate changes alone only feed the 4 Hz mount telemetry.

class argos.server.state.SensorInfo(width: 'int', height: 'int', bitpix: 'int' = 16, bayer: 'str | None' = None)[source]

Bases: object

bayer: str | None = None

CFA layout of a raw colour sensor ("GRBG"…), None for mono data.

class argos.server.state.Target(ra_hours: 'float', dec_deg: 'float')[source]

Bases: object

argos.server.state.utc_iso(when: datetime | None = None) → str[source]

ISO 8601 UTC with millisecond precision and a Z suffix.

Thread-safe pub/sub between device threads and the asyncio WebSocket senders.

Devices run on plain threads (an exposure blocks for seconds, an Alpaca call blocks on HTTP); WebSocket clients live on the event loop. EventBus is the only crossing point: EventBus.publish() and EventBus.publish_frame() may be called from any thread and hand over with loop.call_soon_threadsafe — the loop thread alone touches the subscriber sets and queues, so they need no lock.

Every per-client buffer is bounded, so a stalled browser can never grow the server’s memory:

  • events — a FIFO, so a client that keeps up sees every transition (connecting before connected, exposing before idle…). Past EVENT_BACKLOG pending messages it is compacted: only the newest snapshot of each kind survives (status, camera, mount, devices, network, activity, config, and job:<id> per job), then the oldest log lines go. Snapshots are complete, so a lagging client loses history, never the current state.

  • frames — one pending slot per client, latest-frame-wins: a slow client skips frames instead of queueing them.

Snapshots carry a sequence number assigned under the hub lock, in the same order as the state changes. A subscriber drops any snapshot older than what it already holds, which closes the one race left: the status a client receives on connect is read directly, while an older event may still sit in the loop’s callback queue.

argos.server.events.EVENT_BACKLOG = 256

Pending messages per client before the backlog is compacted.

class argos.server.events.EventBus[source]

Bases: object

Fan-out of events and encoded frames to every connected client.

add_tap(tap: Callable[[str, dict[str, Any]], None]) → None[source]

Observe every published event, before any client (wave 6b, attention).

detach() → None[source]

Stop accepting publications and release every waiting client.

publish(kind: str, seq: int | None, payload: dict[str, Any]) → None[source]

Queue one JSON event (a snapshot kind with its seq, or log).

publish_frame(frame: bytes) → None[source]

Queue one encoded binary frame for every frame client.

subscribe_events(initial: tuple[int, dict[str, Any]] | None = None, history: list[dict[str, Any]] | None = None, snapshots: list[tuple[str, int, dict[str, Any]]] | None = None, after_history: list[tuple[str, int, dict[str, Any]]] | None = None) → EventSubscriber[source]

Register a client, pre-loaded with a status snapshot, the other current snapshots (network, activity) and past log lines.

A log line published just before this call can arrive twice (once from history, once from the loop’s queue); the front-end drops the lines whose seq it already holds.

subscribe_frames() → FrameSubscriber[source]

Register a client, pre-loaded with the most recent frame if any.

class argos.server.events.EventSubscriber(capacity: int = EVENT_BACKLOG)[source]

Bases: object

One /ws/events client’s pending messages (loop thread only).

dropped

Messages discarded by compaction (diagnostics).

async next_batch() → list[dict[str, Any]][source]

Wait for pending messages and take them all, in order; [] once closed.

class argos.server.events.FrameSubscriber[source]

Bases: object

One /ws/frames client: a single latest-frame-wins slot (loop thread only).

async next_frame() → bytes | None[source]

Wait for the newest frame; None once closed.

skipped

Frames overwritten before this client took them (diagnostics).

argos.server.events.STREAM_KINDS = frozenset({'conditions', 'frame_saved', 'log', 'photometry_point', 'photometry_reset'})

every message counts (no snapshot floor, never replaced by a newer one). Under backpressure log lines are dropped first, then the oldest of the wave 3 and 5 streams; each stream carries its own seq so a client that sees a gap re-reads the REST page (protocol.md “Backpressure”).

Type:

Stream kinds

Binary frame encoding for /ws/frames (see protocol.md).

Layout of one WebSocket binary message:

[0, 4)              uint32 LE   N = byte length of the JSON header
[4, 4 + N)          UTF-8 JSON  header (seq, geometry, stats, …)
[4 + N, offset)     zero padding, so that offset % 8 == 0
[offset, …)         width × height × channels uint16 LE, row-major,
                    channels interleaved, row 0 = top of the image

Row 0 is the top row as displayed, which in ARGOS is simply row 0 of the array: the Qt viewer (fits_viewer.py) shows arrays row-major with the y-axis inverted, and neither the camera download nor Open FITS flips. The 8-byte alignment lets the browser build a Uint16Array view straight on the message buffer, with no copy.

The statistics come from one 65 536-bin histogram of the uint16 pixels, which gives the exact median and MAD (identical to np.median) in a few milliseconds — sorting two million pixels twice would cost ~45 ms.

argos.server.frames.encode_frame(pixels: ndarray, *, seq: int, exposure_s: float, timestamp: str, source: Literal['simulator', 'alpaca', 'file'], stats: dict[str, Any] | None = None, extra: dict[str, Any] | None = None) → bytes[source]

Encode one frame as a /ws/frames binary message.

Parameters:
  • pixels – uint16 array, (height, width) or (height, width, 3), row 0 = top of the image as displayed.

  • seq – Frame sequence number (monotonic per server process).

  • exposure_s – Exposure time, 0.0 when unknown (opened file).

  • timestamp – ISO 8601 UTC time of the frame.

  • source – "simulator", "alpaca" or "file".

  • stats – Precomputed frame_stats(), computed here when omitted.

  • extra – Additive header fields (wave 3: bayer, origin, the frame’s settings, an opened file’s path / date_obs / epoch_utc); they never replace a v1 field.

Raises:

ValueError – Unsupported dtype or shape.

argos.server.frames.frame_stats(pixels: ndarray) → dict[str, Any][source]

min/max/median/mad/mean over every sample of pixels.

pixels must be uint16 (any shape; colour channels are pooled). mad is the raw median absolute deviation — not scaled by 1.4826.

The generic long-running job model (web/spec/README.md §4.2, row A80).

A job is one-off work of seconds to minutes (discovery today; site search, support bundle, session scans, file solves, re-runs and exports in later waves). It runs on its own thread, never on the event loop, and reports through one record:

  • POST on the domain route starts it and answers 202 {"job_id"}; a second job of the same kind on the same resource is 409 busy with owner = the running job’s id;

  • progress is published as {"type": "job", "job": {...}} events, at most every MIN_PUBLISH_INTERVAL_S per job, the final state always;

  • DELETE /api/jobs/{id} sets the job’s cancel event; the job function honours it at a safe boundary by raising JobCancelled (JobContext.check()) and the job ends cancelled;

  • finished jobs are kept KEEP_S seconds for GET /api/jobs/{id}; GET /api/jobs lists the active ones and the last KEEP_LISTED.

Events are published on the bus under the kind job:<id>: the per-client backlog compaction keeps the newest snapshot per kind, so each job keeps its own latest state instead of one job’s event replacing another’s.

exception argos.server.jobs.JobCancelled[source]

Bases: Exception

Raised inside a job function to end it as cancelled.

class argos.server.jobs.JobContext(manager: JobManager, job: _Job)[source]

Bases: object

What a job function receives: progress reporting and the cancel flag.

check() → None[source]

Raise JobCancelled if a cancel was requested (a safe boundary).

progress(done: float | None = None, total: float | None | Any = ..., stage: str | None | Any = ..., message: str | None | Any = ...) → None[source]

Update the record; published within MIN_PUBLISH_INTERVAL_S.

sleep(seconds: float) → None[source]

Wait, waking at once on cancel (then raise JobCancelled).

class argos.server.jobs.JobManager(publish: Callable[[str, dict[str, Any]], None] | None = None, *, keep_s: float = KEEP_S, keep_listed: int = KEEP_LISTED, min_interval_s: float = MIN_PUBLISH_INTERVAL_S)[source]

Bases: object

Starts, tracks, publishes and cancels jobs; thread-safe.

shutdown(timeout_s: float = 3.0) → None[source]

Cancel every running job and wait for them (bounded).

start(kind: str, fn: Callable[[JobContext], Any], *, resource: str | None = None, cancellable: bool = True, total: float | None = None, stage: str | None = None) → dict[str, Any][source]

Run fn on a new thread; returns the job record (409 busy if taken).

argos.server.jobs.KEEP_LISTED = 20

Finished jobs listed by GET /api/jobs.

argos.server.jobs.KEEP_S = 600.0

How long a finished job stays readable.

argos.server.jobs.MIN_PUBLISH_INTERVAL_S = 0.25

Shortest gap between two progress events of one job (≤ 4 Hz).

argos.server.jobs.Publisher

(bus kind, payload).

alias of Callable[[str, dict[str, Any]], None]

The observer log: a bounded ring of structured lines (API 2, row A2).

Every line the server shows the observer goes through LogBook: it numbers the line (seq, also id), stamps it in UTC and keeps the last LOG_RING lines, so a page that reloads can replay the night with GET /api/logs?after=<seq> instead of losing it (v1 kept 200).

Levels follow the Qt activity log (148 log_message.emit sites use CMD, INFO, OK, WARN and ERROR) plus debug, which the server records only while ui.log_level is DEBUG.

argos.server.logbook.LEVEL_ORDER: dict[str, int] = {'cmd': 1, 'debug': 0, 'error': 5, 'info': 2, 'ok': 3, 'warning': 4}

Severity order, for the level filter of GET /api/logs.

argos.server.logbook.LOG_HISTORY = 200

Lines replayed to a /ws/events client right after its first status.

argos.server.logbook.LOG_RING = 5000

Lines kept for GET /api/logs.

class argos.server.logbook.LogBook(capacity: int = LOG_RING)[source]

Bases: object

Thread-safe ring of log entries with a monotonic sequence number.

append(level: str, message: str, source: str, topic: str) → dict[str, Any][source]

Record one line and return its log event payload.

page(after: int = 0, limit: int = 1000, level: str | None = None) → dict[str, Any][source]

Lines with seq > after, oldest first (GET /api/logs).

recent(count: int = LOG_HISTORY) → list[dict[str, Any]][source]

The newest count lines, oldest first.

Process-wide effects of the configuration (row A3, part of A9).

The Qt app applies these when its Settings page is built (configuration_page.py:823-824) and when a field changes (:1040-1084), and the log level once in main.py:144. The headless server applies them at start-up, before the first request, and again on every config commit that touches them. They change module-level state of the core, so only a server that owns its process does this (Settings.manage_process); in-process tests leave them alone.

argos.server.runtime.LOG_FILENAME = 'argos.log'

30-32).

Type:

Same bounds as the Qt app’s journal (support_bundle.py

class argos.server.runtime.RedactTokens(name='')[source]

Bases: Filter

Keep the bearer token out of logs (uvicorn logs WebSocket URLs with ?token=).

filter(record: LogRecord) → bool[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

argos.server.runtime.add_file_log(directory: Path, formatter: Formatter) → Path | None[source]

Rotating argos.log in directory, as configure_local_logging.

support_bundle.configure_local_logging cannot be reused as is: it replaces every root handler (basicConfig(force=True)), dropping the token redaction and stderr routing the CLI set up. A failure only loses the file; the server keeps logging to stderr.

argos.server.runtime.apply_data_paths(get: Callable[[str, Any], Any]) → None[source]

Point the core modules at the configured cache and calibration folders.

Port of ConfigurationPage._apply_catalogue_paths and _apply_local_data_paths (configuration_page.py:1040-1084): same targets, same expanduser; nothing is created or read here.

argos.server.runtime.apply_log_level(level: Any) → None[source]

ui.log_level for the whole process (main.py:144), applied live.

argos.server.runtime.default_config_dir() → Path[source]

$ARGOS_CONFIG_DIR, else ~/.argos (the Qt app’s folder, config.py:16).

argos.server.runtime.default_log_dir() → Path[source]

$ARGOS_LOG_DIR, else the platform folder of the Qt app (support_bundle.py:57-64).

argos.server.runtime.install_crash_reporter(directory: Path) → None[source]

Uncaught exceptions of any thread leave a report (support_bundle.py:124-145).

Devices and connection

The hub that owns the four device slots, the Alpaca adapter and the built-in simulator, discovery, the network monitor, telescope profiles and the Stellarium bridge.

The hub: device ownership, state machine, worker threads and event emission.

The HTTP layer is thin: every route calls one Hub method from FastAPI’s threadpool. The hub keeps the contract records and is the only writer of them.

Devices (API 2, rows A13-A15). Four device slots — mount, camera, filter wheel, focuser — each with its own state (disconnected, connecting, connected, error; busy is derived from the camera and mount records), its own handle and its own generation. This is a Qt-free port of DeviceSession (argos/core/session/device_session.py:230-501) with the problems of 02 §1.2-1.3 fixed: connects run in worker threads (the Qt app ran them on the UI thread, freezing it for up to ~40 s on a dead address), connect-all skips connected devices (the Qt app started a second mount poller), and error texts are kept whole (Qt cut them to 48 characters). The v1 ConnectionState is derived from the camera and mount slots, so the v1 routes keep working on top of the per-device model.

Threads:

  • the request threads (FastAPI’s pool) run commands and device connects; a slow Alpaca call blocks only its own request;

  • one exposure job thread at a time runs a single capture or a live loop;

  • one mount poller thread reads the mount every poll_interval_s (0.25 s for the simulator — the contract’s 4 Hz ceiling) and publishes it; after mount_lost_after consecutive failures it hands over to a mount retry thread (device_session.py:155-160, 299-333, 557-567);

  • the network monitor and job threads (network.py, jobs.py);

  • the Stellarium bridge thread, with its own event loop (stellarium.py, row A19); a GoTo it receives is run on a short-lived thread, never on the bridge’s loop.

Locking: _lock guards the records and is never held across device I/O, a thread join or a configuration write. Every state change happens under it together with the publication of its event and a fresh sequence number, so events leave in the order the changes happened. Lock order, outermost first: _profile_guard → the config store’s lock → _lock → the site check’s own lock (site_check.py, wave 2), which never calls out while held; the hub never waits for the store while holding _lock.

Wave 2 (Settings) adds services that are no device: the read-only file listing (fs.py), the session list (sessions.py), the support bundle and crash reports (support.py), the Settings helpers (settings_helpers.py: ASTAP, caches, place search) and the site check (site_check.py), fed by the mount poller.

Wave 3 (Observe: acquisition) drives the devices: capture settings and the Take shot with its FITS save (capture.py, on the save thread), the filter wheel (wheel.py, a thread per move), the focuser (focuser.py, its poll thread), autofocus (autofocus.py, its own thread), the jog dead-man (jog.py, a watcher thread), the observation identity and catalogue lookups (observation.py) and the metrics thread with the conditions rows (conditions.py). Every one keeps its records under _lock and never holds it across device I/O.

Wave 4 (Field identification) adds the field service (field.py: plate solve jobs and the automatic identification, the catalogue fetch, the overlay layers, the per-frame tracking transform, the star selection) fed with every published frame, and the target set (targets.py). The mount poller checks every reading against the solution (a slew from elsewhere invalidates it); GoTo and Centre invalidate it at once.

A command or connect that was already talking to a device when the observer disconnected it must not write its answer into the state afterwards: every connect and teardown bumps that slot’s generation, and a result read under an older generation is discarded.

argos.server.hub.CONNECT_ORDER = ('mount', 'camera', 'filterwheel', 'focuser')

its connect syncs the mount clock, which every later GoTo depends on.

Type:

device_session.py

Type:

252-256 — the mount first

argos.server.hub.DISCONNECT_ORDER = ('camera', 'mount', 'filterwheel', 'focuser')

258-263 — the camera first, so its exposure stops first.

Type:

device_session.py

class argos.server.hub.Hub(bus: EventBus | None = None, sim: SimOptions | None = None, *, config: ConfigStore | None = None, settings: Settings | None = None)[source]

Bases: object

Owns the devices and the contract state; thread-safe.

astap_state(path: str | None = None, database_path: str | None = None, database: str | None = None) → dict[str, Any][source]

GET /api/astrometry/astap (row A81); each argument defaults to the config.

boot_id

Identifies this server process (/api/health, status, GET /api/logs): log seq numbers start again at 1 in a new process, so a client that sees another id knows its lines come from a restarted server.

caches() → dict[str, Any][source]

GET /api/caches (row A83).

capture(exposure_s: float | None = None, gain: int | None = None, frame_type: str | None = None, save: bool = False) → dict[source]

POST /api/camera/capture: one frame, or a Take shot with save.

clear_cache(kind: str) → dict[str, Any][source]

DELETE /api/caches/{kind} (row A83): local only, nothing downloaded.

client_gone(client: str | None) → None[source]

A /ws/events socket opened with ?client= closed: stop its jog.

client_message(client: str | None, message: Any) → None[source]

A text message from a /ws/events client; only jog_stop is known.

connect(mode: str, host: str | None = None, port: int | None = None) → dict[source]

v1 POST /api/connection: mount then camera, both must succeed.

connect_all(mode: str = 'alpaca', host: str | None = None, port: int | None = None) → dict[str, Any][source]

POST /api/devices/connect-all: skips the devices already connected.

Every device still to connect is claimed at once: it is connecting with info: "queued" until its turn, so the profile is locked, the clients show the run and Disconnect all (or a row’s Cancel) can stop it from the first moment. The address is then checked once: when nothing answers there, every claimed device fails at once with that reason, instead of the observer waiting for one timeout per device.

connect_device(device_id: str, mode: str = 'alpaca', host: str | None = None, port: int | None = None) → dict[str, Any][source]

POST /api/devices/{id}/connect.

crash_reports(since: str | None = None) → dict[str, Any][source]

GET /api/diagnostics/crash-reports (row A6).

disconnect() → dict[source]

v1 DELETE /api/connection: stop everything and release every device.

disconnect_all() → dict[str, Any][source]

DELETE /api/devices (device_session.py:258-263).

Also cancels a connect-all in progress: it connects no further device.

disconnect_device(device_id: str) → dict[str, Any][source]

DELETE /api/devices/{id} (also “Stop retrying” for the mount).

discovery_layers: DiscoveryLayers

The layered discovery’s network operations (tests replace them).

field_snapshots() → list[tuple[str, int, dict[str, Any]]][source]

Wave 4 snapshots a new client gets after the replayed log lines.

fs_list(path: str | None, kind: str = 'any', ext: str | None = None, counts: str | None = None, hidden: bool = False) → dict[str, Any][source]

GET /api/fs/list (row A11).

fs_roots

Folders the file listing and the support bundle may touch (row A11).

initial_snapshots() → list[tuple[str, int, dict[str, Any]]][source]

Snapshots a new /ws/events client gets right after status.

job_download(job_id: str) → tuple[Path, str][source]

GET /api/jobs/{id}/download: the file a finished job left for the browser.

log(level: Literal['debug', 'cmd', 'info', 'ok', 'warning', 'error'], message: str, *, source: str = 'server', topic: str = 'app') → None[source]

Log to Python logging and to every /ws/events client.

log_history() → list[dict[str, Any]][source]

The last LOG_HISTORY log events, oldest first.

mount_center(target: dict[str, Any] | None = None, pause_run: bool = False) → dict[source]

POST /api/mount/center (_center_selected_target, imaging_page.py:2692-2715; center_target_from_solution, device_session.py:734-765).

mount_jog(axis: str, rate_deg_s: float, client: str | None = None, seq: int | None = None, renew: bool = False, pause_run: bool = False) → dict[source]

POST /api/mount/jog: start or renew one axis (dead-man in jog.py).

mount_jog_stop(axis: str | None = None, client: str | None = None, seq: int | None = None) → dict[source]

POST /api/mount/jog/stop: one axis, or both whatever the server believes.

mount_sync(pause_run: bool = False) → dict[source]

POST /api/mount/sync {"source": "solution"} (Q-O3: Sync to plate solution, no slew; telescope.py:540-562).

mount_tracking_rate(rate: str, pause_run: bool = False) → dict[source]

POST /api/mount/tracking-rate (telescope.py:610-634), read back (H6).

open_fits(path: str) → dict[source]

Open a raw FITS frame as the current frame (A27; works without a connection).

place_http_get: Callable[[str, dict[str, Any], dict[str, str], float], Any]

The place search’s HTTP getter (tests replace it; row A82).

publish_event(kind: str, payload: dict[str, Any]) → None[source]

Publish a ready-made event under a bus kind (jobs use job:<id>).

publish_log(level: Literal['debug', 'cmd', 'info', 'ok', 'warning', 'error'], message: str, *, source: str = 'server', topic: str = 'app') → None[source]

Record one observer log line and send it (no Python logging).

refuse_if_run_active(what: str) → None[source]

409 run_active while a sequence is active (the plan half’s lock, Q-P9).

The link a connect request names, with the config’s address as default.

saved(after: int = 0, limit: int = 200) → dict[str, Any][source]

GET /api/camera/saved (A24): the saves after after.

sessions_page(offset: int = 0, limit: int = 50) → dict[str, Any][source]

GET /api/sessions (row A67, list only).

set_activity(text: str, *, source: str = 'server', topic: str = 'app', log: bool = True) → None[source]

The status-bar activity text (row A4); also a cmd log line if log.

set_camera_settings(changes: dict[str, Any]) → dict[str, Any][source]

PUT /api/camera/settings (A22): one commit, applied from the next frame.

set_profile(key: str) → dict[str, Any][source]

PUT /api/profile: port of apply_telescope_profile.

connection_page.py:237-258: refused while equipment is connected; choosing the active profile again is always accepted.

shutdown(stage: Callable[[str], None] | None = None) → None[source]

Release everything at server exit, once; a second caller waits for the first.

Wave 8: stage hears each stage id before it runs (desktop.STAGES, the shutdown events of POST /api/app/shutdown).

site_check

Settings site against the mount (PROPOSAL §7; protocol.md “Site check”).

site_check_now() → dict[str, Any][source]

POST /api/site/check: compare the latest mount reading now.

site_check_state() → dict[str, Any][source]

GET /api/site/check.

start() → None[source]

Start the background services (the event loop is attached).

start_autofocus(exposure_s: float | None = None, gain: int | None = None, half_range: int | None = None, num_steps: int | None = None, *, for_sequence: bool = False) → dict[str, Any][source]

POST /api/autofocus/start (acquisition_engine.py:923-961).

for_sequence: a run hands its camera over (_on_seq_autofocus_due, begin_sequence_autofocus); the camera goes back to the run at the end.

POST /api/site/search (row A82): a cancellable site_search job.

start_support_bundle(destination: str | None = None, include_session: bool = False, session_dir: str | None = None, include_site: bool = False, include_crash_reports: bool = True, overwrite: bool = False) → dict[str, Any][source]

POST /api/support-bundle (row A5): a support_bundle job (not cancellable).

status() → dict[str, Any][source]

GET /api/status body.

status_event() → tuple[int, dict[str, Any]][source]

The current status event with its sequence number (for a new client).

stellarium_start(host: str | None = None, port: int | None = None) → dict[str, Any][source]

POST /api/stellarium: port of start_stellarium (device_session.py:783-798).

The host and port are the config’s unless given; both are written to the config before the bridge starts, as the Qt app did (the port is now also saved by the Planetarium card on commit). A bind error is answered 502 bind_failed and stays in the record until the next start (the Qt card never showed it, 02 H14).

stellarium_stop() → dict[str, Any][source]

DELETE /api/stellarium: port of stop_stellarium (device_session.py:800-806).

stop_autofocus() → dict[str, Any][source]

POST /api/autofocus/stop: cancel and return to the start (S23).

stop_camera() → dict[source]

Stop a capture or live view; also clears a camera error.

update_live(exposure_s: float, gain: int) → dict[source]

Change the running live view’s exposure and gain from its next frame on.

The exposure in progress finishes with the old settings; the camera record (exposure_s, gain) changes when the next one starts, so it always describes the frame being taken. Wave 3: an alias of PUT /api/camera/settings limited to these two fields.

Bases: object

Where devices are connected: the simulator, or one Alpaca server.

argos.server.hub.QUEUED = 'queued'

info of a device that a Connect all has claimed but not opened yet.

Device back ends of the headless server: simulator and Alpaca adapters.

Each back end implements the small protocols of base; the hub never knows which one it is driving.

What the hub needs from a camera and a mount.

Both protocols are synchronous and blocking: the hub calls them from worker threads (exposure job, mount poller) or from FastAPI’s threadpool, never from the event loop.

class argos.server.devices.base.AuxDevice(*args, **kwargs)[source]

Bases: Protocol

A filter wheel or a focuser, as the device table describes it.

info() → str[source]

One line for the device table (filter slot, focuser position…).

class argos.server.devices.base.CameraDevice(*args, **kwargs)[source]

Bases: Protocol

abort() → None[source]

Abort a running exposure (best effort, never raises).

expose(exposure_s: float, gain: int, cancel: Event, on_readout: Callable[[], None], *, light: bool = True, on_start: Callable[[], None] | None = None) → ndarray[source]

Take one exposure and return it as uint16, row 0 = top.

Blocks for the exposure time; returns early with ExposureCancelled once cancel is set. on_start is called right before StartExposure (the frame’s DATE-OBS, as exposure_worker.py:160), on_readout when ImageReady turns true, before the download (the end of the exposure). light is the ASCOM Light flag: a Seestar has no shutter, so it closes nothing (wave 3: only the wheel’s Dark slot blocks the light).

class argos.server.devices.base.CameraExtras(*args, **kwargs)[source]

Bases: Protocol

Optional camera features (AlpacaCamera, SimCamera).

fits_readings() → dict[str, object][source]

What a FITS save reads from the camera (acquisition_engine.py:1856-1859): ccd_temp, egain_driver, offset, readout_mode (each may be None).

temperature() → float | None[source]

Sensor temperature (°C), None when unavailable (never raises).

class argos.server.devices.base.CameraLimits(gain_min: int, gain_max: int, exposure_min_s: float, exposure_max_s: float, offset_range: tuple[int, int] | None = None, max_bin: int = 1)[source]

Bases: object

The driver’s ranges, read at connect (camera.py:70-133).

max_bin: int = 1

min(MaxBinX, MaxBinY); 1 = no binning.

offset_range: tuple[int, int] | None = None

(min, max) of Offset, or None when the driver has none.

argos.server.devices.base.ConnectReport

(level, message) lines a device reports right after it connected; the hub logs them, and keeps the warning / error ones as the device’s warnings. Adapters expose them as an optional connect_report().

alias of list[tuple[str, str]]

exception argos.server.devices.base.DeviceError[source]

Bases: Exception

A device refused a command or stopped answering.

exception argos.server.devices.base.ExposureCancelled[source]

Bases: Exception

The exposure was aborted through its cancel event.

class argos.server.devices.base.FilterWheelDevice(*args, **kwargs)[source]

Bases: Protocol

A filter wheel (argos.core.alpaca.filterwheel.FilterWheel).

get_position() → int[source]

Current slot index; −1 while the wheel turns.

position_name() → str[source]

Slot name, "Moving…" while turning (filterwheel.py:129-134).

set_position(index: int) → None[source]

Start a move (asynchronous: get_position reads −1 until it ends).

slots: tuple[str, ...]

Slot names in wheel order (the active profile’s filter_names).

class argos.server.devices.base.FocuserDevice(*args, **kwargs)[source]

Bases: Protocol

A focuser (argos.core.alpaca.focuser.Focuser).

class argos.server.devices.base.MountDevice(*args, **kwargs)[source]

Bases: Protocol

poll_interval_s: float

Period of the hub’s telemetry poll for this mount (s).

stop() → None[source]

Abort a slew (ASCOM AbortSlew); tracking is left as it was.

class argos.server.devices.base.MountExtras(*args, **kwargs)[source]

Bases: Protocol

Optional mount features (wave 3, rows A29-A31).

alignment: str | None

"altaz", "eq", "eq_gem" or None (AlignmentMode at connect).

clock_error_s: float | None

Mount-vs-computer clock offset measured at connect (s), or None.

move_axis(axis: int, rate_deg_s: float) → None[source]

ASCOM MoveAxis: 0 = primary, 1 = secondary; 0.0 stops the axis.

exception argos.server.devices.base.MountParked[source]

Bases: DeviceError

The command needs an unparked mount.

class argos.server.devices.base.MountReading(state: Literal['parked', 'idle', 'slewing', 'tracking', 'error'], ra_hours: float, dec_deg: float, alt_deg: float | None, az_deg: float | None, tracking: bool, pier_side: Literal['east', 'west'] | None)[source]

Bases: object

One poll of the mount, in Argos coordinates (ICRS/J2000).

Real Seestar over ASCOM Alpaca — thin adapters over argos.core.alpaca.

argos.core.alpaca.camera.Camera and argos.core.alpaca.telescope.Telescope are already Qt-free and synchronous (the Qt app calls them from QThreads); this module only maps them onto the server’s device protocols. Every scientific decision stays in the core: the J2000 ↔ topocentric-of-date conversion and the clock-sync guard of Telescope, the ImageBytes download and its row-major (height, width) orientation in Camera.

The exposure loop mirrors LivePreviewWorker: set gain, start the exposure, poll ImageReady every 100 ms with a deadline of exposure + 20 s, then download.

argos.server.devices.alpaca.ALPACA_MOUNT_POLL_S = 2.0

Telemetry period for a real mount. Each poll is ~8 Alpaca GETs; the Qt app polls every 2 s (POLL_INTERVAL_MS) and the Seestar copes with that.

class argos.server.devices.alpaca.AlpacaCamera(host: str, port: int)[source]

Bases: object

Implements CameraDevice.

connect_report() → list[tuple[str, str]][source]

The Qt connect messages (device_session.py:368-415), as data.

Profile mismatches are advisory: the profile is never switched here (detect.py module docstring); the observer decides.

fits_readings() → dict[str, object][source]

The four camera reads of a Take-shot save (acquisition_engine.py:1856-1859).

class argos.server.devices.alpaca.AlpacaFilterWheel(host: str, port: int)[source]

Bases: object

Implements FilterWheelDevice (device_session.py:430-448; moves :85-122, 681-701).

slots: tuple[str, ...]

Slot names from the active profile (filterwheel.py:24-31).

class argos.server.devices.alpaca.AlpacaFocuser(host: str, port: int)[source]

Bases: object

Implements FocuserDevice (device_session.py:460-488; moves :705-739).

class argos.server.devices.alpaca.AlpacaMount(host: str, port: int)[source]

Bases: object

Implements MountDevice.

connect_report() → list[tuple[str, str]][source]

The Qt mount connect messages (device_session.py:276-291), as data.

driver_site

The driver’s own site (lat, lon, elev|None), or None when it does not expose one; read once here, at connect time, on the connecting thread (the site check compares it, wave 2).

sync(ra_hours: float, dec_deg: float) → None[source]

sync_to (telescope.py:540-562: clock checked, tracking required, J2000 converted to the mount’s system).

tracking_rates() → list[str][source]

TrackingRates as the driver lists them (Q-O15); [] when unknown.

Synthetic 16-bit camera: a plausible Seestar star field, deterministic per frame.

Not a physics engine — a test pattern with the statistics a photometry UI must cope with: a sky pedestal near 2000 ADU, shot noise plus read noise, a few hundred Gaussian stars over a steep luminosity function (a handful saturate), fixed hot pixels, a gentle sky gradient, slight seeing changes and a small pointing drift between frames.

Frame n is a pure function of (seed, n, exposure, gain): the star field comes from the seed, the noise and the jitter from (seed, n). Units are 16-bit ADU throughout; the “reference” settings are a 2 s exposure at the Seestar’s default gain of 80.

Wave 3: with a SimOptics the frame also follows the simulated focuser (the stars blur away from best focus, their flux conserved, so compute_hfd traces a V-curve) and the filter wheel (the Dark slot blocks the light: sky and stars vanish, the pedestal, read noise and hot pixels stay). The light flag of an exposure closes nothing, as on a Seestar. Offset shifts the pedestal by 2 ADU per unit.

argos.server.devices.sim_camera.FWHM_PX = 2.8

6.7″ at the S50’s 2.39″/px (206.265 × 2.9 µm / 250 mm).

Type:

Median seeing (px FWHM)

argos.server.devices.sim_camera.PEDESTAL_ADU = 1600.0

Zero-exposure level (ADU), as a bias frame would read.

argos.server.devices.sim_camera.READ_NOISE_ADU = 12.0

Read noise (ADU rms) and system gain (ADU per photo-electron) at the reference gain.

argos.server.devices.sim_camera.REFERENCE_OFFSET = 10

Offset (ASCOM Offset) at which the pedestal is PEDESTAL_ADU, and its slope.

argos.server.devices.sim_camera.SENSOR_TEMPERATURE_C = 21.0

Sensor temperature the simulator reports (°C).

argos.server.devices.sim_camera.SIM_LIMITS = CameraLimits(gain_min=0, gain_max=600, exposure_min_s=0.001, exposure_max_s=3600.0, offset_range=(0, 255), max_bin=1)

Driver ranges the simulator advertises (wave 3, CameraLimits).

argos.server.devices.sim_camera.SKY_RATE_ADU_S = 200.0

2 s brings the frame to ~2000 ADU.

Type:

Sky brightness at the reference gain (ADU/s)

class argos.server.devices.sim_camera.SimCamera(width: int = 1080, height: int = 1920, seed: int = 20261101, n_stars: int = 240, optics=None)[source]

Bases: object

Implements CameraDevice.

drift(index: int) → tuple[float, float][source]

Pointing offset (px) of frame index: slow periodic wander + jitter.

light_flags: list[bool]

Light flags of the exposures, newest last (tests read them).

render(index: int, exposure_s: float, gain: int, *, fwhm_factor: float = 1.0, transmission: float = 1.0, offset: int = REFERENCE_OFFSET) → ndarray[source]

Synthesize frame index — deterministic, ~25 ms at 1080×1920.

fwhm_factor widens every star (defocus) with its flux conserved; transmission scales sky and stars (0 = the wheel’s Dark slot).

Simulated equatorial mount: slews, sidereal tracking, park/unpark, abort.

The model is evaluated lazily from the wall clock: every call first advances the state to “now” (finishing a slew whose time is up), so no thread is needed and SimMount.read() is microseconds.

  • Slew — each axis moves at slew_rate_deg_s (RA measured as an angle, 15°/h, the short way round); the slew ends when the slower axis arrives. A GoTo turns tracking on, like Telescope.slew_to.

  • Tracking on — RA/Dec stay fixed on the sky.

  • Tracking off (idle or parked) — the axes stand still, so the hour angle is fixed and the RA advances with local sidereal time.

  • Park — slews to the celestial pole and stops tracking.

  • Jog (wave 3) — MoveAxis moves the primary axis (RA, positive east) and the secondary axis (Dec, positive north) at up to MAX_AXIS_RATE_DEG_S, on top of tracking or drift; a GoTo, an abort or a park stops both axes.

  • Tracking rates (wave 3) — sidereal, lunar, solar and king are listed and read back; the model tracks at the sidereal rate whatever is set.

Alt/az use a closed-form GMST and the textbook spherical triangle — no astropy in a 4 Hz loop, and no IERS table to download in the field. They ignore precession, nutation and refraction (≈0.4° from J2000 in 2026), which tests/server/test_sim_mount.py checks against astropy. Pier side follows the German-equatorial convention from the hour angle (the real Seestar is alt-az and reports none).

argos.server.devices.sim_mount.DEFAULT_SITE = Site(latitude_deg=48.8277, longitude_deg=2.3826, elevation_m=60.0)

APC laboratory, Paris — a fixed, plausible default observing site.

argos.server.devices.sim_mount.MAX_AXIS_RATE_DEG_S = 5.0

Fastest MoveAxis rate the simulator accepts (deg/s), the Qt dialog’s top speed.

argos.server.devices.sim_mount.PARK_DEC_DEG = 90.0

the celestial pole, as on an equatorial mount.

Type:

Park position

class argos.server.devices.sim_mount.SimMount(slew_rate_deg_s: float = 4.0, site: Site = DEFAULT_SITE, poll_interval_s: float = 0.25, clock: Callable[[], float] = time.time)[source]

Bases: object

Implements MountDevice.

alignment = 'eq_gem'

a German equatorial model.

Type:

ASCOM AlignmentMode (wave 3)

axis_calls: list[tuple[int, float]]

Every MoveAxis call, oldest first (tests read them).

clock_error_s: float | None = None

the simulator uses the computer’s clock.

Type:

Mount-vs-computer clock offset

driver_site

The mount’s own site, as an Alpaca driver’s SiteLatitude / SiteLongitude / SiteElevation (the hub’s site check compares it).

move_axis(axis: int, rate_deg_s: float) → None[source]

ASCOM MoveAxis (telescope.py:564-583): 0 = RA, 1 = Dec; 0.0 stops.

sync(ra_hours: float, dec_deg: float) → None[source]

ASCOM SyncToCoordinates (telescope.py:540-562): the current pointing now reads ra_hours, dec_deg (wave 4, A32 / A33).

class argos.server.devices.sim_mount.Site(latitude_deg: 'float', longitude_deg: 'float', elevation_m: 'float' = 0.0)[source]

Bases: object

argos.server.devices.sim_mount.TRACKING_RATES = ('sidereal', 'lunar', 'solar', 'king')

ASCOM DriveRates the simulator lists, in enum order.

argos.server.devices.sim_mount.altaz(ra_hours: float, dec_deg: float, unix_time: float, site: Site) → tuple[float, float][source]

(altitude, azimuth) in degrees, azimuth from north through east.

argos.server.devices.sim_mount.gmst_hours(unix_time: float) → float[source]

Greenwich mean sidereal time (h) — IAU 1982 linear form, ~0.1 s accuracy.

Simulated filter wheel and focuser, and the optics they share with the camera.

API 2 wave 1 had connect-only stand-ins; wave 3 drives them, so they behave like the Alpaca devices the hub talks to:

  • the filter wheel takes time to turn (SimOptions.wheel_slot_s per slot) and reads position −1 meanwhile, as FilterWheel.get_position does on a Seestar (filterwheel.py:88-98);

  • the focuser moves at SimOptions.focuser_speed_steps_s, reports IsMoving, stops where it is on Halt and clamps a move to 0…MaxStep (focuser.py:127-139).

Both write into a SimOptics the simulated camera reads, so the pixels follow the hardware: stars blur away from best focus (a V-curve autofocus can find), and the wheel’s Dark slot blocks the light (the only thing that does on a Seestar, which has no shutter). The motion is evaluated lazily from the clock, like SimMount: no thread.

argos.server.devices.sim_aux.DEFOCUS_SCALE_STEPS = 450.0

the FWHM grows as √(1 + (Δ/scale)²) with Δ the distance to best focus.

Type:

Defocus scale of the simulated optics (focuser steps)

argos.server.devices.sim_aux.FOCUSER_START = 5000

Where the simulated focuser starts (and stays, between connections).

class argos.server.devices.sim_aux.SimFilterWheel(optics: SimOptics | None = None, slot_s: float = 0.6, clock: Callable[[], float] = time.monotonic)[source]

Bases: object

Implements FilterWheelDevice.

slots: tuple[str, ...]

The active profile’s internal slots (Dark, IR, LP on a Seestar).

class argos.server.devices.sim_aux.SimFocuser(optics: SimOptics | None = None, speed_steps_s: float = 2_000.0, clock: Callable[[], float] = time.monotonic)[source]

Bases: object

Implements FocuserDevice.

property position: int

The connect log’s pos= (hub._connect_device).

class argos.server.devices.sim_aux.SimOptics(best_focus: int = 5_300, defocus_scale: float = DEFOCUS_SCALE_STEPS)[source]

Bases: object

What the simulated camera sees: focus and filter, shared across devices.

The hub creates one per server and hands it to the simulated camera, focuser and wheel. The physical state survives a disconnect (the focuser stays where it was, the wheel on its slot), as on a telescope.

fwhm_factor() → float[source]

Star FWHM relative to the seeing-limited one (1.0 at best focus).

transmission() → float[source]

Fraction of the sky light reaching the sensor (0 on the Dark slot).

Simulator replay source (wave 6a): a folder of real FITS copies played by the simulator.

--sim-replay DIR (SimOptions.replay_dir) makes the simulator mode serve real frames, so field identification, the aperture tracker and the photometry of a sequence can be exercised on the simulator, which cannot be solved or measured on its synthetic sky:

  • ReplayCamera returns, exposure after exposure, the pixels of the folder’s FITS files in file-name order (raw 16-bit, the Open FITS rule of load_raw_fits_frame()), starting again after the last one. The exposure time is still waited, and Stop interrupts it; exposure, gain, focus and wheel never change the pixels.

  • ReplayMount is the simulated mount, started unparked and tracking, whose readings carry the pointing of the file being exposed (RA / DEC of an ARGOS frame, else OBJCTRA / OBJCTDEC, and ALTITUDE / AZIMUTH when the header has them) whenever it tracks; a GoTo or a park behave as the simulator’s.

Nothing is written into the folder. The subs a sequence saves are dated by the server clock, not by the replayed headers.

class argos.server.devices.sim_replay.ReplayCamera(replay: ReplaySource)[source]

Bases: object

Implements CameraDevice over a replay folder.

time_scale

really waited). A test hook: the parity runs replay 10 s subs without waiting 10 s.

Type:

The exposure wait is exposure × time_scale (1

class argos.server.devices.sim_replay.ReplayMount(replay: ReplaySource, slew_rate_deg_s: float = 4.0, site: Site = DEFAULT_SITE, poll_interval_s: float = 0.25)[source]

Bases: SimMount

The simulated mount, reporting the replayed frames’ pointing while it tracks.

Alt-az, as the Seestar that took the frames: the photometry tracker then allows the field rotation (_wcs_for_frame) and no pier side is reported.

alignment = 'altaz'

a German equatorial model.

Type:

ASCOM AlignmentMode (wave 3)

class argos.server.devices.sim_replay.ReplayPointing(ra_hours: 'float', dec_deg: 'float', alt_deg: 'float | None', az_deg: 'float | None')[source]

Bases: object

class argos.server.devices.sim_replay.ReplaySource(folder: Path | str)[source]

Bases: object

The folder, its order and the file being exposed (shared by camera and mount).

begin_exposure() → int[source]

The next file’s index; the mount reports its pointing from now on.

argos.server.devices.sim_replay.header_pointing(header: Any) → ReplayPointing | None[source]

Where the mount pointed for this frame, from its header.

An ARGOS frame’s RA is in hours (fits_writer); other software writes degrees, so for them only the sexagesimal OBJCTRA / OBJCTDEC are used.

Alpaca discovery as a cancellable job (row A16).

Qt-free port of DiscoveryWorker.run (argos/workers/discovery_worker.py:50-64) and of the layered search it calls, argos.core.alpaca.discovery.discover_all (discovery.py:167-199): UDP broadcast, then direct HTTP probes of the candidates (the last-used host and the profile’s access-point address, device_session.py:203-205), then a TCP sweep of the local /24. The core functions block for their whole duration (8 s of broadcast, a pool sweep), so the two long layers are re-implemented here with short waits that check the job’s cancel event (discover discovery.py:48-97 and scan_subnet discovery.py:138-164); the HTTP probe, local_ipv4 and the constants are the core’s own.

Differences from the Qt app, by design (web/spec/02 §1.2 #4, §2.5): every device found is returned (Qt kept the first), the probe layer tries every candidate, each device’s ServerName is read, and the whole search can be cancelled.

class argos.server.discovery.DiscoveryLayers(broadcast: Callable[[float, Event], list[tuple[str, int]]], probe: Callable[[str, int], bool], scan: Callable[[int, Event], list[tuple[str, int]]], name: Callable[[str, int], str | None])[source]

Bases: object

The network operations of one search; tests replace them with fakes.

argos.server.discovery.NAME_TIMEOUT_S = 1.0

Timeout of the ServerName read per device (s).

argos.server.discovery.broadcast(timeout_s: float, cancel: Event) → list[tuple[str, int]][source]

Alpaca UDP discovery (port of discovery.py:48-97), cancellable.

argos.server.discovery.probe(host: str, port: int) → bool[source]

The core’s management-API probe (discovery.py:105-119, 2 s).

argos.server.discovery.run_discovery(ctx: JobContext, *, port: int, candidates: tuple[str, ...], broadcast_timeout_s: float, layers: DiscoveryLayers = DEFAULT_LAYERS) → dict[str, Any][source]

The job body: layered search, stopping at the first layer with a result.

argos.server.discovery.scan(port: int, cancel: Event) → list[tuple[str, int]][source]

TCP sweep of the local /24 (port of discovery.py:138-164), cancellable.

argos.server.discovery.server_name(host: str, port: int) → str | None[source]

ServerName from the Alpaca management API, or None.

Network reachability for the status bar and the Link card (row A18).

Qt-free port of NetworkMonitor (argos/workers/network_monitor.py:40-84, a QThread), with the owner’s decision Q-G13 applied:

  • the configured Seestar address (alpaca.host / alpaca.port, re-read on every cycle as network_monitor.py:80-82) is probed with one TCP connect every CHECK_INTERVAL_S, and at once after the address changes; seestar is None while no address is configured, which the UI shows as “not configured” (fixes 01 P22);

  • the internet is not probed in the background (Qt contacted 1.1.1.1 and 8.8.8.8 every 10 s with no opt-in): NetworkMonitor.check() with internet=True does it on demand, with the Qt targets and timeout; internet stays None until then.

Every probe publishes a network snapshot with its time, so the Link card can say “checked 4 s ago”.

argos.server.network.CHECK_INTERVAL_S = 10.0

32 (10 000 ms).

Type:

network_monitor.py

argos.server.network.CONNECT_TIMEOUT_S = 1.5
Type:

network_monitor.py

argos.server.network.INTERNET_TARGETS: tuple[tuple[str, int], ...] = (('1.1.1.1', 53), ('8.8.8.8', 53))

37 — TCP/53 on public resolvers, tried in order.

Type:

network_monitor.py

class argos.server.network.NetworkMonitor(address: Callable[[], tuple[str, int]], publish: Callable[[dict[str, Any]], None] | None = None, *, interval_s: float = CHECK_INTERVAL_S, timeout_s: float = CONNECT_TIMEOUT_S, probe: Callable[[str, int, float], bool] = tcp_reachable, internet_targets: tuple[tuple[str, int], ...] = INTERNET_TARGETS)[source]

Bases: object

Periodic Seestar probe plus the on-demand internet check; thread-safe.

Parameters:
  • address – Returns the configured (host, port); host "" = none.

  • publish – Called with the network snapshot after every probe.

  • interval_s – Probe period.

  • timeout_s – TCP connect timeout of one probe.

  • probe – The reachability test (tests inject a fake).

  • internet_targets – Hosts tried, in order, by the internet check.

check(internet: bool = False) → dict[str, Any][source]

Probe the Seestar (and the internet if asked); publish and return the state.

wake() → None[source]

Probe again now (the configured address changed).

argos.server.network.tcp_reachable(host: str, port: int, timeout: float = CONNECT_TIMEOUT_S) → bool[source]

network_monitor.py:40-45.

Telescope profiles as JSON records (row A17).

Wraps argos.core.hardware: the built-in catalogue (catalog.py:99-112), the frozen TelescopeProfile with its derived quantities (profile.py:91-121: focal ratio, plate scale and field of view are computed, never stored) and the active-profile registry with the user’s overrides (active.py:56-110). The change guard of the Qt Connection page (connection_page.py:237-258: refused while equipment is connected) is enforced by the hub, which knows the device states.

argos.server.profiles.applied_overrides(raw: Any) → dict[str, Any][source]

The entries of hardware.overrides that apply_overrides honours.

argos.server.profiles.profiles_state(locked_reason: str | None, raw_overrides: Any) → dict[str, Any][source]

GET /api/profiles.

argos.server.profiles.record(profile: TelescopeProfile, overrides: dict[str, Any] | None = None) → dict[str, Any][source]

One Profile record; overrides lists what was applied (active profile).

argos.server.profiles.summary(profile: TelescopeProfile) → dict[str, Any][source]

The profile field of the status record.

The Stellarium bridge (API 2, row A19): Stellarium’s Telescope Control over TCP.

Qt-free port of argos/workers/stellarium_worker.py:24-130 (the QThread that owned an asyncio loop running argos.core.stellarium.server. StellariumServer) and of DeviceSession.start_stellarium / stop_stellarium (argos/core/session/device_session.py:783-816). The protocol server itself is the core module, unchanged.

The bridge runs on its own thread with its own asyncio loop, as the Qt worker did, so a Stellarium client can never hold the server’s HTTP loop. Every crossing into that loop goes through call_soon_threadsafe.

Fixed on the way (02 H14): a bind error is part of the state (the Qt card never showed it), the host is reported, the port is written to the config when the bridge starts (the hub does that), and the last GoTo carries its outcome and time instead of a label that never reverted.

argos.server.stellarium.START_WAIT_S = 3.0

How long start waits for the listening socket (or the bind error).

argos.server.stellarium.STOP_WAIT_S = 3.0

How long stop waits for the loop thread (the Qt card waited 3 s).

class argos.server.stellarium.StellariumBridge(on_goto: Callable[[float, float], None], on_change: Callable[[], None])[source]

Bases: object

One Stellarium server at a time, restartable (stop, change port, start).

on_goto(ra_hours, dec_deg) is called on the bridge’s loop thread for every valid GoTo; it must not block (the hub hands it to a thread). on_change() is called whenever snapshot() changes (start, stop, a client connects or leaves, an error).

set_position(ra_hours: float, dec_deg: float, slewing: bool) → None[source]

The mount’s pointing, pushed to Stellarium’s reticle (any thread, cheap).

start(host: str, port: int) → str | None[source]

Start listening on host:port; returns the bind error, or None.

A running bridge is stopped first (device_session.py:784-785). Blocks until the socket is open or refused (≤ START_WAIT_S).

stop(announce: bool = True) → bool[source]

Close the server and its clients; returns True if one was running.

Settings and files

The configuration file and the metadata of every key the interface may read or write, the site check, the folder browser, the sessions list and the support bundle.

The configuration file, read and written by the server (rows A8-A10).

The same config.json the Qt app uses (argos/core/config.py), so both UIs see one configuration during the transition. Config itself cannot be reused as is: its location is a module constant (~/.argos, which tests and smoke runs must never touch), Config.set writes the file on every key (config.py:241-248) without atomicity, and nothing reports what changed. This store keeps the core’s format and loading rules — the shipped defaults deep-merged under the file, then the five migrations, exactly as Config.load (config.py:196-219) — and adds:

  • a configurable folder (None = in memory, never written);

  • one validated commit per request: every key checked against argos.server.config_meta first, nothing written if one fails;

  • an atomic write: temporary file in the same folder, fsync, os.replace; a crash leaves the old or the new file, never a mix;

  • external changes: the file’s stamp (mtime, size, inode) is compared before every commit and every GET; when another program (the Qt app) wrote it, it is re-read first, so a commit never overwrites that change, and the change is announced;

  • a listener called with (changed, values, revision, source) while the store lock is held, so announcements leave in commit order.

Reads (get(), values()) take no lock: the data dict is replaced whole on every change, never mutated, so a reader always sees one version.

class argos.server.config_store.ConfigStore(directory: Path | None = None)[source]

Bases: object

Thread-safe owner of the configuration (see the module docstring).

get(key: str, default: Any = None) → Any[source]

Any dotted key of the file (exposed or not), like Config.get.

load_error: str | None

Why the file could not be read at start-up (it is kept aside before the first write replaces it), or None.

patch(changes: dict[str, Any], source: str = 'api') → PatchResult[source]

PATCH /api/config: validate every key, then commit them together.

refresh() → dict[str, Any][source]

Re-read the file if it changed on disk; returns (and announces) what changed.

set_internal(changes: dict[str, Any], source: str = 'server') → PatchResult[source]

Commit values the server itself decided (profile, last Alpaca address).

Read-only keys are allowed here; values are still validated.

snapshot() → dict[str, Any][source]

GET /api/config: re-reads the file first if another program wrote it.

argos.server.config_store.Listener

(changed, values, revision, source); called with the store lock held.

alias of Callable[[dict[str, Any], dict[str, Any], int, str], None]

class argos.server.config_store.PatchResult(values: 'dict[str, Any]', changed: 'dict[str, Any]', warnings: 'list[dict[str, str]]', revision: 'int')[source]

Bases: object

argos.server.config_store.load_config_data(path: Path) → dict[str, Any][source]

Defaults + file + migrations, as Config.load (config.py:206-216).

Raises OSError or ValueError when the file cannot be read or parsed.

Metadata of every configuration key the web UI may read or write (row A8).

The source is web/spec/02-connection-and-settings.md appendix A, which inventories every key of ~/.argos/config.json with its default (argos/core/config.py:19-176), its Qt editor and widget range, and every reader. Each KeyMeta carries what the Settings form needs (type, default, range, step, options, unit, label, help, category) and the “About this setting” column needs (used_by).

Ranges are the Qt widgets’ where one exists (cited per key); keys the Qt app never exposed (Q-C4, now under “advanced”) get a range wide enough for any sensible value, stated here.

This module also validates one value against its meta (validate_value()): strict types (80.0 is not an int, True is not a number), ranges, options, path checks. Validation never touches the network; path checks only stat the filesystem.

argos.server.config_meta.DATA_PATH_KEYS = frozenset({'data_paths.aavso_cache_directory', 'data_paths.camera_calibration_directory', 'data_paths.exoplanet_cache', 'data_paths.field_catalogue_cache_directory', 'data_paths.gaia_cache_directory', 'data_paths.object_catalogue_cache'})

Keys that change process-wide data locations (applied to core modules).

exception argos.server.config_meta.InvalidValue[source]

Bases: ValueError

A value refused for one key; the message is shown under the field.

class argos.server.config_meta.KeyMeta(key: 'str', type: 'KeyType', default: 'Any', label: 'str', help: 'str', category: 'Category', used_by: 'tuple[str, ...]' = (), min: 'float | None' = None, max: 'float | None' = None, step: 'float | None' = None, options: 'tuple[tuple[Any, str], ...] | None' = None, unit: 'str | None' = None, nullable: 'bool' = False, advanced: 'bool' = False, read_only: 'bool' = False, read_only_reason: 'str | None' = None, path_kind: "Literal['dir', 'file', 'exe']" = 'dir', allow_empty: 'bool' = False, max_length: 'int' = 200, pattern: 'str | None' = None, upper: 'bool' = False, personal: 'bool' = False, extra: 'dict[str, Any]' = <factory>)[source]

Bases: object

options: tuple[tuple[Any, str], ...] | None = None

(value, label) pairs; the value must be one of them.

path_kind: Literal['dir', 'file', 'exe'] = 'dir'

what the path names, and whether “” (auto) is allowed.

Type:

path keys

pattern: str | None = None

a full-match pattern and an upper-casing normaliser.

Type:

str keys

read_only_reason: str | None = None

Why a read_only key cannot be changed through PATCH /api/config (shown under the field; wave 2).

argos.server.config_meta.LEGACY_MIRROR = {'hardware.overrides.full_well_adu': ('camera.full_well_adu', 'full_well_adu'), 'hardware.overrides.linearity_max_adu': ('camera.linearity_max_adu', 'linearity_max_adu')}

Override key -> the legacy camera.* key the Qt app still reads (Q-C1).

argos.server.config_meta.OMITTED: tuple[tuple[str, str], ...] = (('observer.latitude', 'Legacy site key, migrated to site.latitude on load (config.py:328-342).'), ('observer.longitude', 'Legacy site key, migrated to site.longitude on load.'), ('observer.elevation', 'Legacy site key, migrated to site.elevation on load.'), ('ui.window_state', 'Dead default: no reader (decision Q-C7).'), ('ui.window_geometry', 'Dead default: no reader (decision Q-C7).'), ('ui.language', 'No translation exists; the selector is dropped (decisions Q-G12, Q-C7).'), ('ui.shell.geometry', 'Qt window state; the web UI keeps its layout per viewer.'), ('ui.shell.state', 'Qt window state; the web UI keeps its layout per viewer.'), ('ui.shell.mode', 'Qt window state; the web UI keeps its section per viewer.'), ('ui.imaging.layout', 'Qt dock layout; the web UI keeps its layout per viewer.'), ('ui.sequencer.layout', 'Qt dock layout; the web UI keeps its layout per viewer.'), ('ui.review.layout', 'Qt dock layout; the web UI keeps its layout per viewer.'), ('camera.adc_bits', 'Deprecated (config.py:75-77), no reader; the profile gives the ADC depth (decision Q-C7).'), ('catalog.field_stars_max_results', 'Dead: no reader (decision Q-C7).'), ('catalog.named_objects_max_results', 'Dead: no reader (decision Q-C7).'), ('catalog.display_limit_version', 'Internal migration marker (config.py:354).'), ('diagnostics.local_opt_in_v1', 'Internal marker, written with diagnostics.enabled (configuration_page.py:1200-1206).'))

Keys of web/spec/02-connection-and-settings.md appendix A that are deliberately not exposed, with the reason (ConfigSnapshot.omitted). With META this covers every key of that table (wave 2 exit criterion); the file keeps them untouched.

argos.server.config_meta.validate_value(meta: KeyMeta, value: Any) → tuple[Any, str | None][source]

Check value for meta; returns (normalised value, warning or None).

Raises InvalidValue with a message meant for the observer.

Settings helpers: ASTAP detection, catalogue caches, place search (A81-A84).

Each is a Qt-free port of what the Qt Settings page does inline:

  • astap_state() — ConfigurationPage._refresh_astap_status (configuration_page.py:1208-1231) on find_astap / find_astap_db / _database_args (platesolve.py:119-144, 305-319), with the database choice of astrometry_session.py:64 (a folder wins over a set);

  • cache_records() / clear_cache() — _refresh_catalogue_cache_status / _clear_catalogue_cache (configuration_page.py:1104-1163): same five caches, same globs;

  • search_places() — search_locations (location_resolver.py:34-87) with the User-Agent from the running version, an injectable HTTP getter (tests never reach the network) and a cancel check between requests.

argos.server.settings_helpers.CACHE_KINDS: tuple[CacheKind, ...] = (CacheKind(kind='object', label='CDS/SIMBAD target-name cache', key='data_paths.object_catalogue_cache', path_kind='file', pattern=None, subdirs=()), CacheKind(kind='exoplanet', label='NASA exoplanet ephemeris cache', key='data_paths.exoplanet_cache', path_kind='file', pattern=None, subdirs=()), CacheKind(kind='aavso', label='AAVSO VSX/VSP field cache', key='data_paths.aavso_cache_directory', path_kind='dir', pattern='[0-9a-f]{40}\\.json', subdirs=()), CacheKind(kind='gaia', label='Gaia DR3 field-star cache', key='data_paths.gaia_cache_directory', path_kind='dir', pattern='[0-9a-f]{64}\\.csv', subdirs=()), CacheKind(kind='field_catalogue', label='SIMBAD / NASA field-identification cache', key='data_paths.field_catalogue_cache_directory', path_kind='dir', pattern='[0-9a-f]{64}\\.json', subdirs=('simbad', 'nasa')))

1104-1163. The Qt page clears every *.json / *.csv of the folder (recursively for the field-identities cache, configuration_page.py:1149-1152); with the in-app FilePicker any folder of the home is one click away as a cache location, so the server clears only the names each cache writes: aavso.py:188-189 (SHA-1 hex .json), gaia.py:57-58 (SHA-256 hex .csv), field_objects.py:52,66 and exoplanets.py:37,91 (SHA-256 hex .json in simbad/ and nasa/).

Type:

configuration_page.py

class argos.server.settings_helpers.CacheKind(kind: 'str', label: 'str', key: 'str', path_kind: 'str', pattern: 'str | None', subdirs: 'tuple[str, ...]' = ())[source]

Bases: object

pattern: str | None

the full-match pattern of the file names the cache itself writes (a hash digest), so Clear never deletes a file ARGOS did not write.

Type:

Folder caches

subdirs: tuple[str, ...] = ()

the folder.

Type:

Folder caches written one level down (simbad/, nasa/); empty

argos.server.settings_helpers.HttpGet

(url, params, headers, timeout_s) -> decoded JSON; raises on failure.

alias of Callable[[str, dict[str, Any], dict[str, str], float], Any]

exception argos.server.settings_helpers.LookupFailed[source]

Bases: Exception

No usable answer from the network (job error lookup_failed).

exception argos.server.settings_helpers.PlaceNotFound[source]

Bases: Exception

The query matched nothing usable (job error not_found).

argos.server.settings_helpers.astap_state(path: str, database_path: str, database: str) → dict[str, Any][source]

GET /api/astrometry/astap (protocol.md “ASTAP detection”).

argos.server.settings_helpers.clear_cache(kind_name: str, get: Callable[[str, Any], Any]) → tuple[dict[str, Any], int][source]

Delete the cached responses of one kind; returns (record, removed).

argos.server.settings_helpers.search_places(query: str, *, http_get: Callable[[str, dict[str, Any], dict[str, str], float], Any] = requests_get, timeout_s: float = PLACE_TIMEOUT_S, cancel: Event | None = None, progress: Callable[[int, int, str], None] | None = None) → list[dict[str, Any]][source]

Port of search_locations (location_resolver.py:34-87).

Settings site against the mount (web/lab/PROPOSAL.md §7).

The mount reports where it points (altitude, azimuth) from its own site and clock; the Seestar takes them from the phone. ARGOS computes airmass, BJD_TDB and FITS SITELAT / SITELONG from the Settings site. Nothing compared the two, so a site left from an earlier trip went unnoticed for a whole run: on 2026-09-25 the Settings site was on another continent, the mount and the Settings site put RR Lyr 88.5° apart on the sky, and that run’s photometry airmass and AAVSO AMASS are wrong.

This is a Qt-free port of the reference implementation of release 0.5.0 (X3, merged into this branch):

  • horizontal_at() and angle_between_directions() are argos.core.imaging.sky_geometry’s (sky_geometry.py:60-90), imported since the 0.5.0 merge (wave 3; the wave 2 copies were identical);

  • observing_site() is argos.core.config.observing_site (config.py:277-297, X2) behind a getter adapter (the store passes get);

  • SiteCheck follows DeviceSession._check_site_against_mount (device_session.py:646-676): the whole direction is compared, never the altitude alone, with the same 5° tolerance and the same texts.

The server adds what the Qt release does not do: a periodic re-check every SITE_CHECK_PERIOD_S while the mount is connected, a re-check after a site change, the comparison with the driver’s own SiteLatitude / SiteLongitude when it exposes them, and a published record.

argos.server.site_check.DRIVER_SITE_TOLERANCE_KM = 100.0

Driver site farther than this from the Settings site is a mismatch. About 0.9° of arc on the Earth, so at most about 0.9° of altitude: a choice of this server (the direct comparison has no pointing-model noise), not a bound measured on sessions.

argos.server.site_check.SITE_CHANGE_SETTLE_S = 2.0

A site change is checked once the site has stayed unchanged this long (s): latitude and longitude are separate commits, so checking at once compared the mount with a half-typed site (one WARN said 174 km while Paris was being typed, wave 2 integration). Find a place and Saved sites commit the keys together and are checked after the same pause.

argos.server.site_check.SITE_CHECK_PERIOD_S = 300.0

Re-check period while the mount is connected (s).

argos.server.site_check.SITE_CHECK_TOLERANCE_DEG = 5.0

More than this between the direction the mount reports and the one computed from the Settings site means the site is not where the telescope is (de5732f: SITE_CHECK_TOLERANCE_DEG). The owner’s sessions with the right site agree within 1.9-3.1°; the 2026-09-25 run with a stale site was 83.6-88.5° off, while its altitudes alone came within 6.2° at the end.

argos.server.site_check.SITE_KEYS = frozenset({'site.latitude', 'site.longitude', 'site.name'})

Config keys whose change re-runs the check.

class argos.server.site_check.SiteCheck(get: Callable[[str, Any], Any], announce: Callable[[], None], log: Callable[[str, str], None], *, period_s: float = SITE_CHECK_PERIOD_S, settle_s: float = SITE_CHANGE_SETTLE_S, clock: Callable[[], datetime] = _utcnow, monotonic: Callable[[], float] = time.monotonic)[source]

Bases: object

The site check of the connected mount; thread-safe.

The hub calls mount_connected(), mount_disconnected(), on_reading() (every successful poll), site_changed() and check_now(). announce is called (no argument, no lock of this object held) after every change: the hub reads record() under its own lock and publishes it, so the lock order is hub → this object. log receives (level, message).

check_now() → dict[str, Any] | None[source]

POST /api/site/check: compare the latest reading now (None: no mount).

mount_connected(generation: int, driver_site: tuple[float, float, float | None] | None) → None[source]

A (re)connection: check again on its first reading that is not a slew.

mount_disconnected(before: int | None = None) → None[source]

The mount went away; before: only a connection older than that generation.

on_reading(reading: MountReading, generation: int) → None[source]

Every successful poll; checks when one is due and the mount is not slewing.

site_changed() → None[source]

site.* changed: check again on the next reading that is not a slew.

argos.server.site_check.evaluate(reading: MountReading, get: Callable[[str, Any], Any], when: datetime, driver_site: tuple[float, float, float | None] | None = None, trigger: str | None = None) → dict[str, Any][source]

One comparison: the SiteCheck record for reading at the clock when.

argos.server.site_check.ground_distance_km(lat1: float, lon1: float, lat2: float, lon2: float) → float[source]

Great-circle distance between two sites on a 6 371 km sphere (haversine).

argos.server.site_check.observing_site(get: Callable[[str, Any], Any]) → tuple[float, float, float] | None[source]

The site the observer set, (lat, lon, elev), or None (X2).

argos.core.config.observing_site on a getter: the 0/0 default is never a site; a site counts as set when it has a name, or coordinates other than 0/0.

Read-only folder listing for the in-app file picker (row A11).

Decisions D20 / Q-G7 (one in-app FilePicker everywhere, Night Red included) and Q-R4 (the browser build opens nothing outside the data paths unless the token holder types it): the server lists folders, read-only, only inside its allowed roots — the observer’s home folder and the ARGOS data folders. Every path is resolved (realpath) before it is compared with the roots, which are resolved too, so neither .. nor a symbolic link can lead outside; entries whose link points outside (or nowhere) are left out of a listing.

Nothing here opens a file, writes, or touches the network. It replaces the 18 QFileDialog sites of the Qt app (web/spec/01-shell-and-global.md appendix A.2) on the server side.

class argos.server.fs.AllowedRoots(get: Callable[[str, Any], Any], extra: Callable[[], Iterable[Path | None]] = lambda : ..., home: Callable[[], Path] = Path.home)[source]

Bases: object

The folders the server may browse, from the live configuration.

get reads a config key; extra gives further folders (the config and log folders). Recomputed on every call, so a data_paths change applies at once.

resolve(raw: str | PathLike[str], *, what: str = 'path') → tuple[Path, Path][source]

(resolved path, its root); 400 relative, 403 outside the roots.

root_of(real: Path) → Path | None[source]

The allowed root containing the resolved path real (outermost), or None.

roots() → list[Path][source]

Resolved roots, most specific (longest) first, no duplicates.

argos.server.fs.MAX_COUNT_SCAN = 10000

Names looked at per folder when counting its FITS files.

argos.server.fs.MAX_ENTRIES = 5000

Entries returned by one listing at most.

class argos.server.fs.Place(id: 'str', label: 'str', path: 'Path')[source]

Bases: object

argos.server.fs.list_folder(roots: AllowedRoots, path: str | None, *, default: Path, kind: str = 'any', exts: tuple[str, ...] = (), counts: str | None = None, hidden: bool = False, places: list[Place] | None = None) → dict[str, Any][source]

GET /api/fs/list (see protocol.md “File listing”).

argos.server.fs.parse_exts(ext: str | None) → tuple[str, ...][source]

".fits,.fit,FTS" → (".fits", ".fit", ".fts").

The list of recorded sessions (row A67, list only; wave 2).

A session is a folder directly inside sessions_path that holds a session.json (argos/core/imaging/session_log.py). The summary is a Qt-free port of argos/core/session/review.py:76-175 (load_session(read_temperature=False) and readiness_issues): that module cannot be imported here, because the argos.core.session package loads PyQt6 (tests/server/test_no_qt.py). Differences, on purpose: missing FITS frames are counted in one issue line instead of one line each, and the per-star curves are counted by their file prefix (target_, comparison_, check_) instead of being loaded.

Summaries are cached per folder, keyed by the stamps of the folder and of session.json; nothing is ever written into a session.

class argos.server.sessions.SessionIndex[source]

Bases: object

Cached summaries of the sessions under one root; thread-safe.

refresh(folder: Path) → dict[str, Any][source]

Summarise folder again, whatever the cache holds (the sessions_scan job).

argos.server.sessions.summarise(root: Path) → dict[str, Any][source]

One SessionSummary (protocol.md “Session list”).

Local support bundle and crash reports (rows A5, A6).

A port of argos.core.support_bundle.create_support_bundle (support_bundle.py:162-221) and of its session-metadata pass (:224-302) for the headless server, with what the server needs on top:

  • the bearer token is removed from every text (its value, token=…, Bearer …, ARGOS_TOKEN=…), although the log handlers already mask token= (runtime.RedactTokens);

  • the observer’s coordinates are removed from the logs too, not only from session files: every writing of the Settings site’s and saved sites’ latitude, longitude and elevation, lat= / lon= / elev= values (the core logs the mount’s site as Mount site: lat=… lon=…, telescope.py:208) and every (lat°, lon°) pair (the site check names a site that way, also one changed since). The observer may ask for them (include_site), never by default;

  • session metadata is left out unless asked (decision Q-G17);

  • crash reports of the log folder (support_bundle.py:104-122) can go in, redacted the same way;

  • the ZIP is written to a temporary name in the destination folder and renamed when complete, so a failure never leaves half a bundle.

Nothing here opens a network connection.

exception argos.server.support.BundleError[source]

Bases: Exception

The bundle could not be written (the message is the OS reason).

class argos.server.support.BundleResult(path: 'Path', files: 'tuple[str, ...]', bytes: 'int')[source]

Bases: object

argos.server.support.MAX_CRASH_REPORTS = 20

Crash reports added at most, newest first, and their size bound.

argos.server.support.MAX_FILE_BYTES = 10000000

33-35).

Type:

Same bounds as the Qt bundle (support_bundle.py

argos.server.support.MAX_LISTED_CRASHES = 50

Crash reports listed by GET /api/diagnostics/crash-reports.

class argos.server.support.Redactor(token: str | None = None, home: Path | None = None, include_site: bool = False, coordinates: Iterable[Any] = ())[source]

Bases: object

Every text that enters the ZIP goes through text().

coordinates: Iterable[Any] = ()

Latitudes, longitudes and elevations to remove from free text.

argos.server.support.crash_reports(directory: Path | None, home: Path | None = None) → list[dict[str, Any]][source]

GET /api/diagnostics/crash-reports: the crash files of the log folder.

argos.server.support.create_bundle(destination: Path, *, redactor: Redactor, log_directory: Path | None, session_directory: Path | None = None, include_crash_reports: bool = True, config_summary: Mapping[str, Any] | None = None) → BundleResult[source]

Write the ZIP at destination (complete, or not at all).

argos.server.support.site_coordinates(get) → list[Any][source]

The coordinates to redact: the Settings site and every saved site.

Observe

Take shot and the FITS save, the filter wheel, the focuser and the autofocus, the jog and its dead-man, the conditions, the observation metadata and Open FITS.

Take shot: capture settings, per-frame snapshots and the FITS save (rows A21-A24).

A Qt-free port of the fixed (release 0.5.0) Take-shot path of argos/core/session/acquisition_engine.py:

  • FrameSettings is the per-frame snapshot of S2 (exposure_worker.py:139-149, FrameSettings): the exposure loop takes one when a frame starts, and the save uses it, never the settings at the time the frame arrives;

  • wheel_filter_name() is _wheel_filter_name (acquisition_engine.py:154-180, S3): FILTER is read back from the wheel when the file is written;

  • save_frame() is _save_fits_async’s task (acquisition_engine.py:1796-1910): folder and name of the Qt Take shot, never overwriting, QA headers measured on the saved array (S20), pointing only from a live mount (X1), the site only when one is set (X2);

  • raw_adu() and fits_exposure_mid() are _raw_adu and fits_exposure_mid (acquisition_engine.py:87-151, S4), for Open FITS.

The decisions that need the hub’s state (is the wheel on Dark, did it move during this exposure) live in the hub; this module holds the data and the pure steps, so the FITS parity tests can drive save_frame() directly.

class argos.server.capture.CaptureSettings(exposure_s: float = 2.0, gain: int = 80, frame_type: str = 'light', filter: str = 'IR', offset: int | None = None, binning: int = 1)[source]

Bases: object

What the next frame uses; server state shared by every client (Q-O13).

argos.server.capture.DEFAULT_FILTER = 'IR'

the first light slot.

Type:

The Qt Camera form’s default filter (camera_dock.py:58-61)

argos.server.capture.FALLBACK_EXPOSURE_MAX_S = 3600.0

Without a camera, the v1 bounds of a capture body (app.py).

class argos.server.capture.FrameSettings(exposure_s: float, gain: int, frame_type: str, filter: str, object_name: str, light: bool, origin: Literal['single', 'live', 'autofocus', 'sequence'], save: bool = False, started_utc: str | None = None)[source]

Bases: object

One frame’s own settings, snapshotted when its exposure starts (S2).

save: bool = False

this frame is the one a Take shot saves.

Type:

Set at arrival

started_utc: str | None = None

taken just before StartExposure.

Type:

DATE-OBS of the frame

argos.server.capture.LogFn

(level, message) sink of the save task (the hub’s log, topic camera).

alias of Callable[[str, str], None]

class argos.server.capture.Pointing(ra_hours: float, dec_deg: float, alt_deg: float | None, az_deg: float | None)[source]

Bases: object

The mount reading a saved frame records (X1: None when no live mount).

class argos.server.capture.SaveJob(arr: ndarray, start: datetime, end: datetime, frame: FrameSettings, frame_seq: int, sessions_path: Path, pointing: Pointing | None, target: tuple[float, float] | None, site: tuple[float, float, float] | None, observer: str, camera: Any = None, wheel: Any = None, software: str = 'Argos v0.5.0', extra: dict[str, ~typing.Any]=<factory>, egain_table: dict[str, ~typing.Any]=<factory>)[source]

Bases: object

Everything the save thread needs; collected when the frame arrives.

camera: Any = None

The camera handle (fits_readings), or None.

egain_table: dict[str, Any]

its entry for the frame’s gain is the header EGAIN (S42).

Type:

camera.egain_table

wheel: Any = None

The filter wheel handle (FILTER read-back), or None without a wheel.

class argos.server.capture.SaveRequest(frame_type: str, live: bool, accepted_utc: str, exposure_s: float | None = None, gain: int | None = None)[source]

Bases: object

A pending Take shot (_capture_pending of the Qt engine).

exposure_s: float | None = None

What the shot asked for (a live Take shot saves the frame in progress with its own values, S2; the log says when they differ).

live: bool

Live view keeps exposing after the save; single releases the camera.

class argos.server.capture.SaveResult(path: 'Path', filter_name: 'str', record: 'dict[str, Any]')[source]

Bases: object

argos.server.capture.fits_exposure_mid(header: Any) → datetime | None[source]

Exposure midpoint (UTC) of a saved frame, from its header, or None.

fits_exposure_mid of acquisition_engine.py: DATE-AVG, else DATE-OBS + EXPTIME/2 (EXPOSURE accepted); a frame of Argos before 0.5.0 always by DATE-OBS + EXPTIME/2 (S39); never guessed.

argos.server.capture.frame_context(job: SaveJob, filter_name: str, readings: dict[str, Any]) → FrameContext[source]

The FrameContext of _save_fits_async (acquisition_engine.py:1811-1873).

argos.server.capture.image_type(frame_type: str) → str[source]

FITS IMAGETYP of an API frame type (fits_writer.IMAGE_TYPE_MAP).

argos.server.capture.is_light_frame(frame_type: str) → bool[source]

Shutter semantics sent with StartExposure (acquisition_engine.py:81-84).

argos.server.capture.raw_adu(data: Any) → ndarray[source]

An opened frame as the sensor’s 16-bit ADU, or ValueError.

_raw_adu (acquisition_engine.py:125-151): integer values in 0..65535 are accepted whatever the stored type; non-integral or non-finite floats, negative values and values above 65535 are refused (a plain cast would wrap them).

argos.server.capture.save_frame(job: SaveJob, log: Callable[[str, str], None]) → SaveResult[source]

Write one Take-shot frame (the body of _save_fits_async._Task.run).

Raises the writer’s exception (OSError…); the caller logs “FITS save failed: …” as the Qt task does.

argos.server.capture.wheel_filter_name(wheel: Any, requested: str, log: Callable[[str, str], None]) → str[source]

Filter the wheel actually sits on, for a Take-shot header (S3).

Port of _wheel_filter_name (acquisition_engine.py:154-180): without a wheel the frame’s filter stands; an unreadable or still-turning wheel keeps it with a warning; a readable wheel that differs wins. A device read: runs on the save thread.

Filter wheel (row A28): moves off the event loop, every outcome published.

A Qt-free port of DeviceSession.move_filter and _FilterMoveRunnable (device_session.py:85-122, 681-746) with the 0.5.0 fixes:

  • H9: errors always end moving. A refused move reads the wheel back and reports the slot it is really on (idle with the refusal as message), or error “position unknown” when it cannot be read;

  • S1 review: the slot the wheel last reported it settled on and the time that move ended are kept (_note_filter_move_ended, device_session.py:704-708), so a Dark Take shot can require the wheel settled on Dark and a frame exposed while it turned is never saved;

  • S3: every mover goes through here and publishes (a Camera-card select, a Dark Take shot, later a sequence), and the hub makes CameraState.settings.filter follow the settled slot.

The settle poll is the Qt one: position −1 while turning, read every 0.15 s, 20 s at most.

class argos.server.wheel.FilterWheelService(hub: Hub, settle_poll_s: float = SETTLE_POLL_S)[source]

Bases: object

The wheel’s record and its moves; the hub’s lock guards the record.

attach(handle: Any, generation: int) → None[source]

A wheel connected: read where it is (connect thread, before the hub lock).

property has_dark_slot: bool

A wheel is connected and its profile has an opaque Dark slot (S1).

moved_since(start: datetime | None) → bool[source]

The wheel turned, or is turning, since start (_wheel_moved_during, acquisition_engine.py:495-510).

not_on_dark() → str | None[source]

Why the wheel cannot be trusted to sit on Dark (_wheel_not_on_dark, acquisition_engine.py:477-493), or None.

on_settled: Callable[[str | None], None] | None

Called with the settled slot name after every move, under the hub lock and in the same step as _moving = False (a waiting Take shot then sees the new filter); on attach, with the slot found.

select(name: str, *, reason: str | None = None) → dict[str, Any][source]

Start a move to the slot name (POST /api/filterwheel/select).

Answers at once (moving); a worker thread waits for the wheel to settle and publishes the outcome. reason replaces the CMD line (a Dark Take shot says why the wheel moves).

property slot: str | None

unknown or moving).

Type:

The slot the wheel last reported it settled on (None

slot_index(name: str) → int | None[source]

Slot whose name matches name, case-insensitive (filter_position_for).

wait_settled(cancel: Event, timeout_s: float = SETTLE_TIMEOUT_S + 5) → bool[source]

Block until no move is in flight; False on cancel or timeout.

argos.server.wheel.SETTLE_POLL_S = 0.15

118-122).

Type:

_FilterMoveRunnable._settle (device_session.py

Focuser (rows A34, A35): polled record, Go to, steps, halt and the D9 queue.

A Qt-free port of the focuser commands of DeviceSession (device_session.py:705-739) over argos.core.alpaca.focuser.Focuser, with the 0.5.0 fixes and what the Qt app left to the web UI:

  • H10: Go to is bounded by the connected focuser’s MaxStep and never clamped silently (400); a step is clamped to 0…MaxStep and the clamp is reported; moves are refused while autofocus owns the focuser, Halt stays accepted;

  • polling (absent in Qt, 05 P4): position and IsMoving every 0.5 s while moving, every 5 s when idle, the temperature every 10 s;

  • D9: a move or a step that arrives while the focuser moves is queued (steps add up) and sent as one move when the current one ends.

Device calls run on the request thread (FastAPI’s threadpool) or on the poll thread, never on the event loop; they are serialised by one command lock so a queued move and a halt cannot cross.

class argos.server.focuser.FocuserService(hub: Hub, poll_moving_s: float = POLL_MOVING_S, poll_idle_s: float = POLL_IDLE_S, temperature_s: float = TEMPERATURE_S)[source]

Bases: object

The focuser’s record, its poll thread and the manual commands.

attach(handle: Any, generation: int) → None[source]

A focuser connected (connect thread): read it, start the poll thread.

halt() → dict[str, Any][source]

Halt at once and clear the queue; during autofocus, end it where it is (Q-O6).

lock(owner: str | None) → None[source]

Autofocus takes ("autofocus") or releases (None) the focuser.

move(position: int) → dict[str, Any][source]

Go to (POST /api/focuser/move): refused outside 0…MaxStep (H10).

note_position(position: int | None, moving: bool | None = None) → None[source]

Autofocus reports where it drove the focuser (between polls).

note_target(target: int) → None[source]

Autofocus reports a move it sent: the record’s target is the last move sent, whoever sent it (the commanded target drawn by the Focuser card).

on_halt_during_autofocus: Callable[[], dict[str, Any] | None] | None

Called by a Halt while autofocus runs (the hub ends the sweep where it is).

step(delta: int) → dict[str, Any][source]

Out (−) / In (+) from the queued or current target, clamped and reported.

argos.server.focuser.SEQUENCE_BUSY = 'A sequence owns the focuser.'

a sequence locks the focuser for its run (its autofocus passes excepted).

Type:

Wave 6a

Autofocus (row A36): the two-stage HFD V-curve sweep on a server thread.

A Qt-free port of AutofocusWorker (argos/workers/autofocus_worker.py, release 0.5.0) with argos.core.imaging.focus unchanged:

  1. coarse sweep of num_steps positions across ±``half_range`` (autofocus_worker.py:117-131);

  2. the degenerate-sweep guard: fewer than three valid samples, a flat curve or an edge minimum restore the start and end rejected (:133-147);

  3. four fine samples around the raw minimum, the parabola fitted on them and the coarse minimum (:149-167);

  4. a move to the best position and one verification exposure (:169-185).

With the 0.5.0 fixes:

  • S22: the requested gain is applied: it is sent with every sample exposure (CameraDevice.expose sets it);

  • S23: Stop = cancel and return to the start. The sweep move is halted first, then the flag is raised (autofocus_worker.py:84-93); the return is waited for whatever the flag (30 s at most) and the position is read back; the camera is released only when the thread has ended. A stop on the way to best focus also returns to the start.

  • Halt (Q-O6, left to the web UI by 0.5.0): POST /api/focuser/halt during a sweep stops it where it is, with no return.

Halt, Stop and every sweep move go through one control lock, so no sweep move is sent after a stop or a halt, and a halt never freezes the return move (it is ignored once the return has started).

class argos.server.autofocus.AutofocusParams(exposure_s: 'float', gain: 'int', half_range: 'int' = 2000, num_steps: 'int' = 9)[source]

Bases: object

class argos.server.autofocus.AutofocusRun(hub: Hub, camera: Any, focuser: Any, params: AutofocusParams, run: int, *, settle_s: float = SETTLE_S, poll_s: float = POLL_S, deadline_s: float = MOVE_DEADLINE_S, publish_frame: Callable[[np.ndarray, float, int, str, str], int], on_end: Callable[['AutofocusRun'], None])[source]

Bases: object

One sweep: the thread body and its stop / halt controls.

halt() → bool[source]

Focuser Halt during a sweep: stop where it is, no return (Q-O6).

Ignored (False) once a stop’s return move runs: a halt must never freeze it (S23).

mode: str | None

“return” (Stop AF) or “halt” (focuser Halt); the first one wins.

stop() → bool[source]

Stop AF: halt the sweep move, then raise the flag (return to the start).

Returns False when a stop or halt was already requested (harmless).

argos.server.autofocus.DEFAULT_HALF_RANGE = 2000

63-82).

Type:

Defaults of AutofocusWorker.__init__ (autofocus_worker.py

argos.server.autofocus.MAX_DEFAULT_EXPOSURE_S = 10.0

the capture exposure, at most 10 s.

Type:

acquisition_engine.py

Type:

945

argos.server.autofocus.MOVE_DEADLINE_S = 30.0

220).

Type:

Bound of every focuser wait (autofocus_worker.py

argos.server.autofocus.SETTLE_S = 1.0

44-46.

Type:

autofocus_worker.py

Mount jog with a server-side dead-man (row A30).

A port of the Manual Control dialog’s MoveAxis jog (telescope.py: 564-592, device_session.py:45-67, 665-679) with the 0.5.0 fix H3 and the parts it left to the web UI:

  • every axis it moved is tracked on its own; a stop names its axis, and “stop” without an axis stops both whatever the server believes (the ■ button);

  • a failed stop is retried: the axis stays in stop_pending (WARN), retried every 0.5 s, five times, then an ERROR says to use Abort, and it stays pending (stop_failed), retried every 5 s until a stop or Abort succeeds: the record never shows a failed stop as resolved;

  • a dead-man (new): an axis whose renewal does not arrive within deadman_s is stopped by the server; so are the axes of a client whose event socket closes or reports a blur ({"type": "jog_stop"});

  • MoveAxis runs off the event loop, and every device call goes through one lock in arrival order, so a stop can never overtake its start (the reason 0.5.0 kept it on the UI thread).

Admission (review of wave 3): a renewal is answered under the hub lock and never waits on device I/O (a slow MoveAxis would otherwise pile up renewals in the request threads); command numbers are compared per client and per axis, and a stop is never dropped as stale; a start that waited longer than the dead-man for the device lock, or that was sent before its client’s socket closed or blurred, is dropped; a renewal (renew: true) never restarts an axis the server stopped; another client’s axis is busy.

class argos.server.jog.JogService(hub: Hub, deadman_s: float = DEADMAN_S, retry_s: float = STOP_RETRY_S, retries: int = STOP_RETRIES, max_rate_deg_s: float = MAX_RATE_DEG_S)[source]

Bases: object

Per-axis jog state, the dead-man watcher and the stop retries.

client_gone(client: str | None, why: str = "the client's socket closed") → None[source]

Stop every axis this client is jogging (socket closed, blur, hidden tab).

jog(axis: str, rate: float, client: str | None = None, seq: int | None = None, renew: bool = False) → dict[str, Any][source]

Start an axis, or renew it when the rate is unchanged (no device call).

The answer is the MountState plus jog_command: started, renewed, pending (a renewal of a start still in its MoveAxis) or ignored with why (stale: an older number than one this client already sent for the axis; stopped: a renewal of an axis the server stopped; late: a start that waited longer than the dead-man, or was sent before this client’s socket closed or blurred).

mount_gone() → None[source]

The mount was disconnected or lost: nothing can be stopped any more.

stop(axis: str | None = None, *, reason: str = 'client', client: str | None = None, seq: int | None = None, quiet: bool = False) → dict[str, Any][source]

Stop one axis, or both whatever the server believes (axis=None).

A stop is never dropped as stale (it is idempotent and safe); its number only invalidates this client’s older starts of that axis.

stop_all_before(action: str) → None[source]

Abort, Park and GoTo first stop any jogging axis (device calls in order).

argos.server.jog.MAX_RATE_DEG_S = 5.0

0.5, 2 and 5 °/s).

Type:

The Qt dialog’s top speed (manual_control_dialog.py

Type:

49-58

argos.server.jog.STOP_FAILED_SLOWDOWN = 10

After the ERROR, a failed stop keeps being retried, this much slower.

Frame metrics and the conditions timeline (rows A26, A37).

  • MetricsWorker: one thread measures every frame on the full resolution array (S20 display side, Q-O14): frame_metrics (HFD of the brightest star, star count, sky, peak) and detect_stars (mean FWHM, eccentricity) of argos.core.imaging.metrics, the measurements of PreviewProcessor (preview_processor.py:58-123). Latest frame wins: a frame still waiting when a newer one arrives is skipped.

  • ConditionsLog: one row per metered camera frame (live and single), with what the Qt HFD history and metrics panel showed (hfd_history_dock.py:107-136, metrics_panel.py:62-80) plus the airmass from the mount and from the target, the temperatures and the focuser position; the last 20 000 rows of this server process.

class argos.server.conditions.ConditionsLog(capacity: int = MAX_ROWS)[source]

Bases: object

The conditions rows of this server process (seq increasing).

argos.server.conditions.MAX_ROWS = 20000

Rows kept in memory (GET /api/session/conditions).

class argos.server.conditions.MetricsJob(seq: 'int', arr: 'np.ndarray', origin: 'str', radius: 'int', row: 'dict[str, Any] | None'=None, extra: 'dict[str, Any]'=<factory>)[source]

Bases: object

row: dict[str, Any] | None = None

no row).

Type:

Context of a camera frame for its conditions row (None

class argos.server.conditions.MetricsWorker(on_result: Callable[[MetricsJob, dict[str, Any]], None])[source]

Bases: object

Latest-frame-wins measurement thread.

skipped

Frames replaced before they were measured (diagnostics).

argos.server.conditions.measure(arr: ndarray, radius: int) → dict[str, Any][source]

The FrameMetrics record of one frame (green-plane px).

Observation identity and catalogue lookups (rows A20, A38-A41).

  • One observation identity (D11): the object name every Take shot writes to OBJECT and its folder, and the catalogue target the Mount card’s Slew uses. A Qt-free port of ImagingPage.set_catalogue_target (imaging_page.py:2733-2756): a catalogue choice sets the name and the coordinates, and only a variable-star type (is_variable_object_type, Q-P8) — or an exoplanet programme — becomes the photometry target of <sessions_path>/targets/<object>.json (acquisition_engine.py: 1247-1302; comparisons are chosen in wave 5).

  • Lookups: resolve_object, cached_object_suggestions and resolve_nearby_objects of argos.core.catalog.object_resolver, always with the configured cache file (data_paths.object_catalogue_cache), run by the request thread (FastAPI’s pool), never on the event loop.

class argos.server.observation.ObservationService(hub: Hub)[source]

Bases: object

The observation record, the catalogue routes and the Stellarium suggestions.

nearby(ra_hours: float, dec_deg: float, network: bool = False, radius_arcsec: float = 90.0) → dict[str, Any][source]

GET /api/catalog/nearby (resolve_nearby_objects).

resolve(query: str) → dict[str, Any][source]

GET /api/catalog/resolve (object_resolver.resolve_object).

resolve_object: Callable[[...], Any]

no network).

Type:

Injectable resolver functions (tests

set_locked(reason: str | None) → None[source]

Wave 6a: a sequence owns the observation while it runs (None unlocks).

set_target(name: str, ra_hours: float, dec_deg: float, object_type: str = '', source: str = '', programme: str | None = None) → dict[str, Any][source]

set_catalogue_target (imaging_page.py:2733-2756).

suggest(query: str, limit: int = 8) → dict[str, Any][source]

GET /api/catalog/suggest (cached_object_suggestions), offline.

The core lists names in lexical order (“M 1, M 100, M 104…”, which skips M 10-M 19): a wider page is read and ordered by match quality (the name itself, then names starting with the text) and then in natural order, numbers by value (design review of wave 3).

suggest_after_goto(ra_hours: float, dec_deg: float) → None[source]

target_suggestions after a Stellarium GoTo (imaging_page.py:2809-2841).

Offers names; never sets one. Online only when stellarium.online_target_lookup is on. Runs on its own thread.

argos.server.observation.Resolver

Resolver entry points; tests replace them (no network in the suite).

alias of Callable[[…], Any]

argos.server.observation.resolved_record(result: Any) → dict[str, Any][source]

A ResolvedObject as the API’s Resolved.

argos.server.observation.target_file(sessions_path: Path, object_name: str) → Path[source]

_target_path (acquisition_engine.py:1247-1249).

Read a FITS file as a displayable uint16 frame for POST /api/camera/open-fits.

Same orientation as the Qt app’s Open FITS: the data array is used as is, row 0 first — no flip, so a frame ARGOS saved comes back exactly as it was shown live. Conversions, all display-oriented (the file is never modified):

  • integer data (BZERO/BSCALE applied by astropy) is clipped to 0…65535;

  • float data normalised to [0, 1] (Siril’s 32-bit default) is scaled by 65535, other float data is clipped; NaN and −inf become 0, +inf (often a saturated pixel) becomes 65535;

  • a (3, H, W) colour cube becomes (H, W, 3) interleaved RGB.

The image size is read from the header before any pixel is loaded: a frame larger than the viewer’s GPU texture limit (MAX_SIDE per side) or than MAX_ELEMENTS samples is refused, so a huge stack or mosaic can neither exhaust the server’s memory nor reach a viewer that cannot show it.

exception argos.server.fits_source.FitsReadError[source]

Bases: Exception

The file is not a FITS image this server can display.

argos.server.fits_source.MAX_ELEMENTS = 100000000

100 M, i.e. a 200 MB uint16 frame.

Type:

Largest number of samples (all axes)

argos.server.fits_source.MAX_SIDE = 16384

Largest image side the web viewer can upload (WebGL MAX_TEXTURE_SIZE, 16384 on current GPUs).

class argos.server.fits_source.OpenedFrame(pixels: ndarray, exposure_s: float, timestamp: str, date_obs: str | None, epoch_utc: str | None, bayer: str | None, pointing: tuple[float, float] | None = None, epoch: datetime | None = None, gain_header: Any = None, filter_name: str | None = None)[source]

Bases: object

A raw frame opened from a file, with what its header says about time.

epoch

The exposure midpoint itself (the photometry epoch, wave 5).

filter_name

absent.

Type:

The header’s FILTER (S49

Type:

the photometry curve of that filter); None

gain_header

the frame’s own e-/ADU (S41).

Type:

The header’s GAIN and EGAIN

pointing

the solve hint (wave 4).

Type:

(ra_hours, dec_deg) from OBJCTRA / OBJCTDEC

argos.server.fits_source.load_fits_frame(path: Path) → tuple[ndarray, float, str][source]

Return (pixels, exposure_s, timestamp) for the first image HDU of path.

Raises:

FitsReadError – Unreadable file, no image data, or an unsupported shape.

argos.server.fits_source.load_raw_fits_frame(path: Path) → OpenedFrame[source]

The first image HDU of path as raw 16-bit counts, dated from its header.

Port of AcquisitionEngine.open_fits_frame (acquisition_engine.py: 741-767) with _raw_adu and fits_exposure_mid (:103-151): one 2-D image of integer values 0…65535 whatever the stored type, else FitsReadError with the reason; the epoch is DATE-AVG, else DATE-OBS + EXPTIME/2, else None.

Field

Plate solving with ASTAP, the field catalogue, frame-to-frame tracking, measurements on the field and the target set.

The live field: identification, catalogue, layers, tracking and star selection.

Rows A32-A33 (inputs), A43-A49 of web/spec/README.md §4.3. A Qt-free port of what the Qt app split between AstrometryController (astrometry_controller.py), AcquisitionEngine (solve, catalogue, tracker: acquisition_engine.py:1017-1240, 1542-1603) and ImagingPage (overlays, click identification, invalidation: imaging_page.py:746-1300, 1393-1800, 2501-2563, 2667-2715).

Threads (none is the event loop; none holds the hub lock across work):

  • a solve thread per solve (manual: a field_solve job; automatic: a plain thread), running ASTAP through field_solve.solve_green(), killed on cancel;

  • the frame thread: per new frame (latest wins) the geometry guard, the tracking transform (A48), the followed selection and the automatic identification policy;

  • the catalogue thread: one fetch per field (A46);

  • the projection thread: rebuilds the layers (A47) after a solve, a catalogue, a role or a display setting (bursts coalesce);

  • an identify thread per point identification (A49), superseded by a newer click.

State is guarded by the hub lock and published with Hub._publish under it, so events leave in the order of the changes.

0.5.0 S50 (release AstrometryController._on_worker_solved): a camera frame’s solution whose plate scale is more than 1 % from the session’s reference (the active profile and frame geometry) is refused, the last good solution kept; the reference is the first good solve, moved to the mean of 3 consecutive solves that agree within 0.3 % (S55). S54: a camera frame’s solution on which fewer than half the photometry tracker’s anchors show a star is refused the same way (PhotometryService.solution_refusal). S48: the photometry’s lock check makes the next solve due at once (FieldService.resolve_due()).

argos.server.field.DEFAULT_TOL_PX = 20.0

Qt’s 10 green px.

Type:

Default hit tolerance (frame px) when the client sends none

argos.server.field.DISPLAY_KEYS = frozenset({'catalog.display_mag_limit', 'catalog.field_stars_detected_only', 'catalog.show_cached_exoplanets', 'catalog.show_essential_objects', 'photometry.aperture_fwhm_mult', 'photometry.aperture_min_px'})

Keys that only change how the cached field is drawn (re-projection).

argos.server.field.FETCH_KEYS = frozenset({'catalog.exoplanet_hosts_allow_network', 'catalog.exoplanet_hosts_enabled', 'catalog.field_stars_enabled', 'catalog.field_stars_mag_limit', 'catalog.identification_max_objects', 'catalog.include_suspected', 'catalog.mag_limit', 'catalog.max_results', 'catalog.named_objects_allow_network', 'catalog.named_objects_enabled'})

Keys that change what a catalogue fetch asks (debounced refetch, A9).

class argos.server.field.FieldService(hub: Hub)[source]

Bases: object

Owns the field state and its events (field, catalog, field_layers, field_transform, selection).

arm_for_sequence() → None[source]

Q-O12: a sequence keeps the field identified, even without a solution.

cancel_solve() → dict[str, Any][source]

DELETE /api/field/solve: kill the running ASTAP (manual or automatic).

catalog_api: Any

Injectable for tests (no network in the suite).

check_mount(ra_hours: float, dec_deg: float) → None[source]

mount_moved_since_solution (astrometry_controller.py:156-174) for every mount reading (imaging_page.py:2667-2686).

clear_selection() → dict[str, Any][source]

DELETE /api/field/select (_on_card_cleared, 2056-2061).

idle() → bool[source]

No background work queued or running (tests).

invalidate(reason: str) → None[source]

Drop the solution and everything built on it (_clear_astrometry).

maybe_fetch_catalog(*, force: bool = False) → bool[source]

maybe_fetch_catalog (acquisition_engine.py:1105-1173); True if started.

on_frame(seq: int, raw: ndarray, origin: str, hint: tuple[float, float] | None = None, epoch: datetime | None = None, egain: float | None = None, filter_name: str | None = None, scintillation: dict | None = None, gain: int | None = None) → None[source]

A new frame was published (camera or file); latest wins on the frame thread.

on_targets_changed() → None[source]

The set changed: re-anchor the tracker and re-project.

Qt dropped the tracker (_reset_tracker, acquisition_engine.py:1301) and restarted from the identity, which is wrong once the field has drifted: the new constellation starts from the current pose.

pending_for(selection_id: int) → dict[str, Any][source]

The pending star of the current selection (POST /api/targets).

pilot() → Pilot | None[source]

The newest full frame of the solved geometry, through the tracked solution.

project_reference(ra_deg: float, dec_deg: float) → tuple[float, float] | None[source]

A sky position in reference frame px, or None (unsolved / off frame).

rebase_mount_reference(ra_hours: float, dec_deg: float) → None[source]

After a Sync the mount reads new coordinates for the same field.

record() → dict[str, Any][source]

The Field record (hub lock held or not: a consistent copy).

reference_solution() → tuple[Any, int] | None[source]

The reference WCS and its generation, or None (wave 6a: a sequence measures each saved sub through it, as Qt’s _on_seq_frame_saved uses self._astrometry.wcs).

reference_with_frame() → tuple[Any, int, int | None, ndarray | None] | None[source]

The reference WCS, its generation, and the seq and raw pixels of the frame it was solved on, read under one lock, or None (a sequence’s sub is measured with them: S56, a solution of this sub or the previous one is fresh, and the tracker’s anchors are chosen on the solved frame, where it is exact; release AstrometryController.solved_raw). Read apart, a solve landing between the two reads paired the old solution with no frame.

refetch() → dict[str, Any][source]

POST /api/field/catalog/refetch (refetch_catalog, 1086-1103).

refresh_center() → None[source]

Hub lock held: Centre availability follows the mount, the set and GoTo.

reset_scale_reference() → None[source]

Another camera may follow (a camera disconnect): the next good solve is the new plate-scale reference (S50, release reset_scale_reference).

resolve_due(frame_seq: int, *, now: bool = False) → None[source]

The photometry lost the field (S35 or the S48 lock check): solve again at once.

The next frame is due whatever the cadence. With now (a sequence sub) the frame in hand is solved now when it is still the newest: its solution serves the next sub. Outside a run only the next frame is due: a live point follows each solve, and solving the same frame again would repeat it (release AcquisitionEngine._resolve_now).

select(x: float, y: float, seq: int | None = None, tol_px: float | None = None)[source]

POST /api/field/select: the click identification of _on_star_clicked.

set_auto(enabled: bool, *, source: str = 'observer') → dict[str, Any][source]

PUT /api/field/auto (astrometry_controller.py:82-85).

snapshots(seq: int) → list[tuple[str, int, dict[str, Any]]][source]

Hub lock held: what a new /ws/events client receives.

solve() → dict[str, Any][source]

POST /api/field/solve: a field_solve job on the newest frame.

solved_centre() → tuple[float, float][source]

RA (h), Dec (°) of the current frame’s centre through the tracked solution.

Only a camera frame says where the mount points: a solution of an opened file (another night, another pointing) must never sync it.

variable_pending(index: int) → dict[str, Any][source]

_on_variable_target_requested (imaging_page.py:2252-2274).

variables_record() → dict[str, Any][source]

GET /api/field/variables (A50): the Qt Variables tab rows (_refresh_variable_table, imaging_page.py:2230-2250) from the variables layer (VSX inside the solved frame, catalogue order).

class argos.server.field.Frame(seq: int, raw: ndarray, origin: str, hint: tuple[float, float] | None = None, epoch: datetime | None = None, egain: float | None = None, scintillation: dict | None = None, filter_name: str | None = None, gain: int | None = None)[source]

Bases: object

The newest frame the field works on.

egain: float | None = None

An opened frame’s own e-/ADU (frame_egain, S41); None → the live chain.

epoch: datetime | None = None

the photometry epoch (wave 5); None when unknown.

Type:

Exposure midpoint (UTC)

filter_name: str | None = None

The frame’s filter (a live frame’s Camera form, an opened file’s FILTER card): its photometry curve (S49). None: unknown.

gain: int | None = None

its e-/ADU (the Camera form’s when None).

Type:

S83

Type:

a camera frame’s gain setting

scintillation: dict | None = None

a camera frame.

Type:

S74

Type:

an opened frame’s exposure, airmass and site height; None

argos.server.field.LOST_TEXT = 'Tracking: no anchor star found — overlays and apertures unguided'

Logged once per loss of the tracking lock (Qt logged it on every frame, acquisition_engine.py:1563-1564).

argos.server.field.MAX_DETECTED_ANCHORS = 6

Fallback tracking anchors detected on the solved frame (no target set).

argos.server.field.MAX_DETECTED_SOURCES = 2000

Sources detected on the solved frame for the detected-only rules (Qt kept the 120 brightest, metrics._MAX_STARS: too few on a rich field, so measurable comparisons read “not detected”).

class argos.server.field.Pilot(wcs: Any, green_shape: tuple[int, int], raw: ndarray, seq: int, egain: float | None = None)[source]

Bases: object

The newest frame of the solved geometry with the tracked solution.

argos.server.field.REACQUIRE_REFERENCE_STARS = 300

Brightest solved-frame sources that vote when a lost lock is re-acquired.

argos.server.field.SCALE_AGREE_SOLVES = 3

the reference moves to the mean of this many consecutive camera solves that agree within this fraction.

Type:

S55 (release SCALE_AGREE_SOLVES, SCALE_AGREEMENT)

argos.server.field.SCALE_TOLERANCE = 0.01

a camera frame’s solution more than this fraction from the session’s first good solve is refused (release astrometry_controller.SCALE_TOLERANCE). The owner’s 270 solves span 0.3 % around their night’s first; the wrong one, 3.4 %.

Type:

S50

Plate solving for the live field (rows A43, A45): ASTAP, WCS and grid in frame px.

A Qt-free port of the solve path of the Qt app with one change: the ASTAP process can be cancelled (killed). Everything else is the fixed 0.5.0 behaviour, reused from argos.core wherever it is not Qt-coupled:

  • solve_green() is solve_array (platesolve.py:197-247) — the temporary FITS of the green plane, the downsample clamp, the retry at native sampling, the whole-sky retry of a hinted solve — with subprocess.Popen instead of subprocess.run so a cancel kills the process. The command is core’s _build_command (platesolve.py: 284-303), so the ASTAP database flags keep the S24 rule (-D <set> -d <folder>, platesolve.py:306-319).

  • Settings come from build_solve_settings (astrometry_session.py: 36-75), the WCS from wcs_from_result and the grid from overlay_for (astrometry_session.py:95-153) — green-plane px — and are converted here to the wire’s frame px (protocol.md “Positions: frame pixels”): x_frame = 2·x_green + 0.5.

exception argos.server.field_solve.SolveCancelled[source]

Bases: Exception

The solve was cancelled; the ASTAP process was killed.

argos.server.field_solve.frame_shape_of(green_shape: tuple[int, int]) → list[int][source]

The frame size [h, w] a green shape comes from (even dimensions).

argos.server.field_solve.frame_wcs_record(wcs: FrameWCS, green_shape: tuple[int, int]) → dict[str, Any][source]

The solution’s TAN WCS expressed in frame px (FrameWcs of protocol.md).

A green 0-based pixel g is frame pixel 2g + 0.5; FITS pixels are 1-based, so crpix_frame = 2·(crpix_green − 1) + 0.5 + 1 and the CD matrix (degrees per pixel) halves.

argos.server.field_solve.grid_record(overlay: Any) → dict[str, Any] | None[source]

A WCSOverlay (green px, NaN breaks) as the wire’s Grid (frame px).

argos.server.field_solve.header_hint(header: Any) → tuple[float, float] | None[source]

(ra_hours, dec_deg) from OBJCTRA / OBJCTDEC (sexagesimal), else None.

An opened file was taken elsewhere: the mount’s pointing is no hint for it. RA / DEC are not used: ARGOS writes RA in hours, other software in degrees.

argos.server.field_solve.solve_green(green: ndarray, settings: SolveSettings, cancel: Event, progress: Callable[[str], None] | None = None) → SolveResult[source]

Plate-solve a green plane — solve_array (platesolve.py:197-247), cancellable.

Raises SolveCancelled when cancel is set while ASTAP runs.

argos.server.field_solve.to_frame(x_green: float, y_green: float) → tuple[float, float][source]

Green-plane px -> frame px (numpy convention, protocol.md).

argos.server.field_solve.to_green(x_frame: float, y_frame: float) → tuple[float, float][source]

Frame px -> green-plane px (inverse of to_frame()).

argos.server.field_solve.wire_mirrored(wcs: FrameWCS) → bool | None[source]

Whether the sky is mirrored as the wire draws it (frame px, y down).

ASTAP’s mirrored is for a FITS display (y up). In px, east is CD⁻¹·(1, 0) and north CD⁻¹·(0, 1); an unmirrored view (north up, east left, y down) has north × east < 0, i.e. det(CD) > 0. The client’s compass uses the same rule.

Field catalogue, overlay layers and comparison candidates (rows A46, A47, A49).

Qt-free ports, in green-plane px internally and frame px on the wire:

  • CatalogRequest / CatalogResult / run_request() are CatalogWorker (catalog_worker.py:32-172); build_request() is the request half of maybe_fetch_catalog (acquisition_engine.py: 1105-1173).

  • project_field() is _project_catalog / _project_targets (imaging_page.py:1497-1783) with the helpers it calls (1801-2027): the Gaia / SIMBAD cross-match, marker de-duplication, object categories, generic identifiers and every tooltip text. It also returns the hit-test index of _on_star_clicked (804-978), so a click identifies exactly what Qt would.

  • candidates() is the FieldBand table (PROPOSAL §7): the VSP comparison stars with b_minus_v and neighbours_in_aperture.

argos.server.field_catalog.COUNTERPART_ARCSEC = 3.0

The candidate’s own Gaia counterpart lies within at least this separation (wider with the seeing: max(3″, FWHM/2)) and within this G − V.

class argos.server.field_catalog.CatalogRequest(ra_deg: float, dec_deg: float, radius_deg: float, fov_arcmin: float, mag_limit: float = 15.0, max_results: int = 250, include_suspected: bool = True, want_comparisons: bool = True, comparison_target_name: str | None = None, comparison_ra_deg: float | None = None, comparison_dec_deg: float | None = None, want_field_stars: bool = True, field_star_mag_limit: float = 18.0, field_star_max_results: int = 2000, want_named_objects: bool = True, named_object_max_results: int = 500, named_objects_allow_network: bool = True, want_exoplanet_hosts: bool = True, exoplanet_hosts_allow_network: bool = True)[source]

Bases: object

A field query, derived from a solved frame’s WCS (catalog_worker.py:32-54).

class argos.server.field_catalog.CatalogResult(variables: list = <factory>, comparisons: list = <factory>, field_stars: list = <factory>, named_objects: list = <factory>, exoplanet_hosts: list = <factory>, field_star_limit: int = 0, named_object_limit: int = 0, field_star_mag_limit: float | None = None, warnings: list[str] = <factory>, source_warnings: list[str] = <factory>, error: str = '')[source]

Bases: object

Outcome of a CatalogRequest (catalog_worker.py:57-79).

field_star_mag_limit: float | None = None

no Gaia query).

Type:

The G limit the Gaia query asked (None

source_warnings: list[str]

the catalog record states it so an empty layer has its reason; the log lines stay Qt’s.

Type:

A source that failed and is only logged by Qt (Gaia, SIMBAD, NASA)

argos.server.field_catalog.DETECTED_TOLERANCE_PX = 4.0

A detected source this close to a catalogue position “is” that source (_is_detected_near, imaging_page.py:1991-1997), green px.

class argos.server.field_catalog.FieldContext(wcs: ~typing.Any, green_shape: tuple[int, int], detected: list[tuple[float, float]], result: ~argos.server.field_catalog.CatalogResult, point_identities: list = <factory>)[source]

Bases: object

What a projection needs: the reference solve and the field’s catalogue.

argos.server.field_catalog.LAYERS = ('stars', 'variables', 'galaxies', 'nebulae_clusters', 'exoplanets', 'other_objects', 'vsp', 'selected')

Layers of FieldLayers.layers (A47), in the overlay bar’s order.

argos.server.field_catalog.NEIGHBOUR_DELTA_MAG = 3.0

A Gaia neighbour counts when at most this much fainter than the candidate.

class argos.server.field_catalog.Projection(layers: dict[str, list[dict]], counts: dict[str, int], hits: list[tuple[str, list]], deep_sky: list = <factory>, exoplanet_hosts: list = <factory>)[source]

Bases: object

FieldLayers content plus the hit-test index (reference green px).

argos.server.field_catalog.SELF_GREEN_PX = 0.5

Any source this close to the candidate (green px = 1 frame px) is itself.

argos.server.field_catalog.VSX_MATCH_ARCSEC = 3.0

A VSX entry this close to a comparison is the same star (variable?).

argos.server.field_catalog.b_minus_v(c) → float | None[source]

VSP B − V of a comparison star, None unless both bands are given.

argos.server.field_catalog.build_request(cfg: Callable[[str, Any], Any], wcs: Any, green_shape: tuple[int, int] | None, source: TargetStar | None) → CatalogRequest | None[source]

The CatalogRequest of maybe_fetch_catalog (acquisition_engine.py:1105-1173).

argos.server.field_catalog.candidates(ctx: FieldContext, tset: TargetSet, *, aperture_green_px: float, quality: dict[str, Any] | None, measured_seq: int | None, target_b_minus_v: float | None, counterpart_arcsec: float = COUNTERPART_ARCSEC) → list[dict][source]

The FieldBand rows: VSP comparison stars inside the frame (PROPOSAL §7).

argos.server.field_catalog.comparison_tooltip(comparison) → str[source]

_comparison_tooltip (imaging_page.py:1999-2007).

argos.server.field_catalog.deduplicate(points: list[dict], radius_px: float = 8.0) → list[dict][source]

_deduplicate_marker_points (imaging_page.py:1839-1856); green px gx/gy.

argos.server.field_catalog.deep_sky_tooltip(item) → str[source]

_deep_sky_tooltip (imaging_page.py:1945-1952).

argos.server.field_catalog.exoplanet_tooltip(host) → str[source]

_exoplanet_tooltip (imaging_page.py:1978-1989).

argos.server.field_catalog.gaia_body(star, identity=None) → str[source]

_field_catalogue_body (imaging_page.py:1919-1938), also its tooltip.

argos.server.field_catalog.gaia_depth(result: CatalogResult) → float | None[source]

The G magnitude the held Gaia list is complete to, or None.

The query asks the brightest sources to field_star_mag_limit within the identification budget: when the budget truncated it, the list is only complete to its faintest source.

argos.server.field_catalog.is_generic_identifier(name: str) → bool[source]

_is_generic_catalogue_identifier (imaging_page.py:1898-1917).

argos.server.field_catalog.match_field_catalogue_names(field_stars, named_objects) → tuple[set[int], list][source]

_match_field_catalogue_names (imaging_page.py:1801-1836): Gaia ↔ SIMBAD ≤ 3″.

argos.server.field_catalog.named_object_tooltip(item) → str[source]

_named_object_tooltip (imaging_page.py:1955-1963).

argos.server.field_catalog.nearest(entries, gx: float, gy: float, tol: float) → int | None[source]

_nearest (imaging_page.py:980-994) with the client’s tolerance.

argos.server.field_catalog.neighbours_in_aperture(comparison, comp_green: tuple[float, float], field_stars: list, gaia_green: list[tuple[float, float] | None], aperture_green_px: float, *, depth_g: float | None = None, counterpart_arcsec: float = COUNTERPART_ARCSEC) → int | None[source]

Gaia sources inside the candidate’s photometry aperture (blend risk).

The candidate’s own counterpart is the nearest Gaia source within counterpart_arcsec whose G is within COUNTERPART_DELTA_MAG of the VSP V (any source within 1 frame px is the candidate itself); every other source whose reference position lies within aperture_green_px of the candidate’s and that is at most NEIGHBOUR_DELTA_MAG fainter (G ≤ m + 3, m = the counterpart’s G, else the VSP V) counts. None when the count cannot be stated: no Gaia sources, no magnitude, or a held list not complete to m + 3 (depth_g).

argos.server.field_catalog.object_category(object_type: str) → str[source]

_object_category (imaging_page.py:1868-1896).

argos.server.field_catalog.point_identity_tooltip(identity) → str[source]

_point_identity_tooltip (imaging_page.py:1966-1975).

argos.server.field_catalog.project_field(ctx: FieldContext, cfg: Callable[[str, Any], Any], tset: TargetSet, *, display_mag_limit: float) → Projection[source]

The overlay layers of one field and its hit-test index (reference solve).

argos.server.field_catalog.result_log_lines(result: CatalogResult) → list[tuple[str, str]][source]

The log lines of _on_catalog (acquisition_engine.py:1175-1223), as data.

argos.server.field_catalog.run_request(r: CatalogRequest, api: Any = core_catalog) → CatalogResult[source]

CatalogWorker.run (catalog_worker.py:90-172); api holds the query functions.

argos.server.field_catalog.target_tooltip(star: TargetStar) → str[source]

_target_tooltip (imaging_page.py:2010-2025).

argos.server.field_catalog.variable_body(v) → str[source]

_variable_body (imaging_page.py:1199-1215).

argos.server.field_catalog.variable_key(v) → str[source]

The TargetStar key a VSX variable gets (imaging_page.py:2245).

argos.server.field_catalog.vsx_match(comparison, variables: list) → dict[str, Any] | None[source]

The VSX entry at the comparison’s position (a known or suspected variable).

Following the solved field from frame to frame (row A48) on core’s tracker.

ApertureTracker (argos/core/photometry/tracking.py:235-339) follows an anchor constellation and fits the rigid transform reference -> frame. In the Qt app only photometry used it; the web also draws every overlay, hit-tests clicks and computes Centre and Sync through it, so a wrong lock is visible and harmful. FieldTracker keeps core’s fit and adds (protocol.md “Layers (A47) and the tracking transform (A48)”, Tracking):

  1. a converged centroid: each anchor’s window is re-centred on its centroid until it converges, then refined in a 4 px window (core S69, _converged_centroid_measurement): a window centred on the prediction lags a moving star, and two passes still kept 0.31-0.44° of lag on XX Cyg 2026-09-07 040723Z (0.7° of field rotation per sub);

  2. baselines from the reference: each anchor’s signal baseline (core’s MIN_SIGNAL_FRACTION test) is measured on the solved frame, where the anchor is known to sit, never on the first tracked frame;

  3. a kept pose: a rebuilt constellation (a role change) starts from the previous transform, not from the identity;

  4. consistent anchors only: with three or more anchors, an update needs at least two matched anchors whose separations agree with the reference (a rigid motion keeps distances); one window that slid onto another star or onto noise is not a lock;

  5. health on the wire: ok, degraded or lost;

  6. re-acquisition: a lost lock is found again by matching the frame’s detected stars to the solved frame’s with a translation vote (vote_transform()).

class argos.server.field_track.FieldTracker(anchors_xy: list[tuple[float, float]], frame_center: tuple[float, float], search_r: float = 8.0, *, reference_green: ndarray | None = None, pose: RigidTransform | None = None)[source]

Bases: ApertureTracker

Core’s tracker with reference baselines, a kept pose and consistent anchors.

property health: str

ok, degraded (fewer anchors than it should have) or lost.

property size: int

Anchors in the constellation.

update(green: ndarray, *, allow_rotation: bool = True) → int[source]

Core’s update (tracking.py:278-339) with the consistency rule.

argos.server.field_track.PAIR_TOL_GREEN_PX = 1.5

Two matched anchors agree when their separation differs from the reference’s by less than this (green px; 3 frame px). Centroids of unsaturated anchors scatter by ~0.1-0.3 green px; a window locked on a neighbour or on sky is several px off.

argos.server.field_track.VOTE_MATCH_GREEN_PX = 2.0

a match is within this many green px of the voted pose.

Type:

Re-acquisition

argos.server.field_track.VOTE_MIN_MATCHES = 6

matches needed to accept the voted pose.

Type:

Re-acquisition

argos.server.field_track.VOTE_STARS = 80

brightest stars of each list that vote.

Type:

Re-acquisition

argos.server.field_track.consistent_pairs(refs: Sequence[tuple[float, float]], meas: Sequence[tuple[float, float]], tol: float = PAIR_TOL_GREEN_PX) → list[int][source]

Indices of the matched anchors whose separations agree with the reference.

An anchor is kept when it agrees with at least max(1, (n - 1) // 2) others: a minority of wrong locks cannot carry the fit. The core tracker has the same rule since S80 (tracking.consistent_pairs), used when present.

argos.server.field_track.vote_transform(reference: Sequence[tuple[float, float, float]], current: Sequence[tuple[float, float, float]], prior: RigidTransform, *, allow_rotation: bool = True, match_px: float = VOTE_MATCH_GREEN_PX, min_matches: int = VOTE_MIN_MATCHES) → tuple[RigidTransform, int] | None[source]

The reference -> frame transform found by matching two star lists, or None.

The prior’s rotation is kept and the translation voted: every pair of the brightest stars of both lists casts one vote for their offset; the peak is refined by a rigid (or translation-only) fit on the matched stars.

Many star measurements on one frame, with the core’s exact results.

measure_star_at (metrics.py:225-276) builds the green plane and its robust sky of the whole frame on every call: right for one click, but a field’s VSP sequence (often 50-100 stars) then costs seconds on a 3840 x 2160 Seestar frame. FrameMeasurer computes the plane and the sky once and runs the same snap and measurement (the core’s private _measure_star and _hfd_window), so every number is identical to measure_star_at (tests/server/test_field_units.py checks it).

class argos.server.field_measure.FrameMeasurer(raw: ndarray)[source]

Bases: object

measure_star_at for many positions of one raw frame (green px).

measure_star_at(x: float, y: float, radius: int = 5, search: int | None = None) → StarMeasurement | None[source]

Same body as metrics.measure_star_at (metrics.py:244-276).

The photometry target set and its roles (rows A51-A53).

A Qt-free port of the target-set half of AcquisitionEngine:

  • the set is keyed by the observation’s object name (D11) and stored as <sessions_path>/targets/<object>.json by TargetSet.save — the Qt file, byte for byte (_target_path / target_set / _save_target_set, acquisition_engine.py:1242-1264);

  • set_role / remove are set_target_role / remove_target (1295-1302, 1506-1511) with the card’s “object name if empty” rule (imaging_page.py:2035-2044);

  • a new target gets its comparisons from the field’s VSP sequence through _auto_select_comparisons and the pilot quality gate (_pilot_comparison_quality), 1348-1491;

  • geometry is photometry_geometry (1493-1504).

Locking: the set has its own lock, taken before the hub’s and never while the hub’s is held; events are published after the set lock is released. The newest record is cached for a new client’s snapshots.

class argos.server.targets.TargetService(hub: Hub)[source]

Bases: object

The target set of the current object (targets event).

assign(star: TargetStar) → dict[str, Any][source]

POST /api/targets: the card’s role buttons (imaging_page.py:2035-2044).

backfill_chart_ids(comparisons) → int[source]

S68 (AcquisitionEngine._backfill_chart_ids): comparisons kept from before 0.4.2 take the VSP chart of this answer, in the object’s set and the running run’s targets.json. GUARD: TargetSet.backfill_chart_ids; returns how many stars changed.

backfill_comparisons() → None[source]

The VSP answer arrived after the target (_on_catalog, 1225-1240).

backfill_proper_motions(field_stars) → int[source]

S77 (AcquisitionEngine._backfill_proper_motions): the set’s VSX/VSP stars take the proper motion of their Gaia DR3 source (field_stars), in the object’s set and the running run’s targets.json. GUARD: TargetSet.backfill_proper_motions; returns how many stars changed.

crowding(tset: TargetSet) → tuple[dict, float][source]

S79 (release AcquisitionEngine.crowding; GUARD: crowded_stars): the set’s crowded comparison and check stars and the radius (arcsec), about 2 aperture radii of the series FWHM at the active profile’s green-plane scale.

egain(gain: int | None = None) → float[source]

_egain: config table → the observer’s photon-transfer file → the profile’s photon transfer (S73) → driver → active sensor reference (hardware.egain.live, the file’s step on a core with from_calibration; GUARD: a core without live keeps the 0.4.x order, table → driver → reference). At gain, the frame’s own setting (S83: a sequence step’s, a camera frame’s), else the Camera form’s.

fwhm_for(seq: int) → tuple[float | None] | None[source]

(fwhm,) of metered frame seq when it is the newest metered one.

geometry() → dict[str, Any][source]

photometry_geometry (1493-1504), green and frame px.

on_frame_fwhm(fwhm: float | None, seq: int | None = None) → None[source]

A metered frame’s mean FWHM (green px): the aperture follows it.

on_object_changed() → None[source]

on_object_changed (1281-1293): the set follows the object name, and the live curves start afresh (clear_lightcurves).

pilot_measure(pilot: Any, egain: float | None = None)[source]

The measure(ra, dec) closure of _pilot_comparison_quality (1450-1478).

An opened frame keeps its own e-/ADU (Pilot.egain, S41).

recommend(mode: str, count: int | None = None) → dict[str, Any][source]

POST /api/photometry/comparisons/recommend.

replace = reselect_comparison_stars (1324-1346, “Recommend from pilot”, imaging_page.py:2213-2224); complete = propose_comparison_stars (1304-1322); count = the “Automatically propose” spin (_on_auto_comparison_count_changed, 2196-2211). Unlike Qt 0.4.2 (S32, extended in the release branch), nothing is removed when no comparison can be chosen: none known, or none passing the gate. Allowed during a run (Q-P9, Qt S15: the comparison selection stays available), journalled in the run folder.

reload() → None[source]

Re-read the file (another writer, a new sessions folder).

remove(key: str, also: list[str] | None = None) → dict[str, Any][source]

DELETE /api/targets/{key} (remove_target, 1506-1511).

also: the comparisons auto-selected with a new target (its Undo); each is taken out only while it is still an automatic (vsp_auto) comparison.

snapshot() → TargetSet[source]

A copy of the current set (the photometry thread measures it unlocked).

write_role_for(object_name: str, star: TargetStar) → Path[source]

Set a role in another object’s set (a catalogue target, observation.py).

argos.server.targets.pending_star(ra_deg: float, dec_deg: float, *, auid: str | None, name: str | None, source: str, mags: dict | None = None, chart_id: str | None = None) → dict[str, Any][source]

The Qt card’s pending dict (imaging_page.py:804-978), with ra_hours.

argos.server.targets.star_from_pending(pending: dict[str, Any], role: str) → TargetStar[source]

TargetStar(role=role, **pending) (imaging_page.py:2039).

argos.server.targets.star_record(star: TargetStar, xy: tuple[float, float] | None = None, crowded: dict | None = None) → dict[str, Any][source]

A TargetStar on the wire (protocol.md “Target set”). S77: its proper motion (None without one; GUARD: a core TargetStar before S77 has none); S79: crowded, why a comparison or check star is crowded (None: it is not).

Photometry, plan and run

Live photometry (the method is the core’s), sequence plans, the run and its mount interlock, visibility and transits.

Live differential photometry (rows A54-A58 of web/spec/README.md §4.3).

A Qt-free port of the live photometry half of AcquisitionEngine (argos/core/session/acquisition_engine.py, 0.5.0):

  • when: one point per field solution outside a sequence (measure_photometry_if_idle, 1062-1065, called by _on_astrometry_solved, imaging_page.py:1417), on the newest frame of the solved geometry (Qt’s _last_raw); a sequence measures every saved sub (_on_seq_frame_saved, 772-797: measure_saved_frame());

  • what: _measure_photometry (1604-1667) over the unchanged core measure_frame with the apertures placed by core’s ApertureTracker (_wcs_for_frame / _build_live_tracker, 1542-1582: an owner decision, the wave 4 FieldTracker keeps placing the overlays), the series FWHM (P7), _emit_live_point (1700-1765), the run-level floor (_apply_systematic_floor, 1767-1795), the CSVs (_photometry_csv_path, 1531-1540) and the leave-one-out report (_write_live_quality_report, 1669-1698), the flight recorder (_diagnostics, 887-913);

  • reset: an object change clears the curves (on_object_changed → clear_lightcurves, 258-274, 1281-1293); a set change or a new solution drops the tracker (_reset_tracker, 1595-1602);

  • 0.5.0 S48 (release branch): the lock check of each measured frame (fewer than ceil(n/2) anchors showing a star where the tracked solution puts them: no point, a re-solve due at once); S49: one curve and one CSV per (star, filter), the filter in the file name, the comparisons vetted per filter; S54: a new solution must show the tracker’s anchors (solution_refusal(), called by the field before it applies one), unless 3 consecutive refused ones agree (a re-pointing the mount did not report); S56: a lock on fewer than 3 anchors is unverified, its points flagged suspect and a re-solve due at once, unless the frame is measured within 2 px of a solution of this sub or the previous one; the anchors are chosen on the solved frame (anchor_frame()) and a run’s sub verified through the previous sub’s solution is solved too (S56 as amended on 2026-11-15, second set); S57: every vetting file names its filter; S85 (GUARD, no_detection_rule()): a target measured below SNR 3 has its point flagged suspect and no_detection and left out of the curve’s sigma_syst.

One deliberate difference with the Qt 0.5.0 code: the series FWHM is frozen on the first measured frame. Qt read it before _diagnostics reset it on a new object, so its first point had its own aperture and the series used the second frame’s FWHM (notes/release_0_5_0.md S31, fixed in the release branch; the owner’s CSVs show it: fwhm 2.16 on the first row, 2.12 on the 194 others).

Threads: measurements run on one photometry thread (FIFO), never on the event loop. Lock order: the service lock, then the hub’s; the target set’s lock is never held while this one is taken. The newest records are kept for a new client’s snapshots and read without the service lock.

argos.server.photometry.LOCK_FRESH_MAX_SHIFT_PX = 10.0

…unless the frame is measured through a solution of this sub or the previous one and the tracker moved no aperture of the set this many green px or more from where that solution puts it (release _LOCK_FRESH_MAX_SHIFT_PX, S56 as amended).

argos.server.photometry.LOCK_LOST_TEXT = 'Photometry skipped: fewer than half the anchor stars show a star where the solution places them — the field moved since the solve, or clouds. Re-solving.'

S48 (release branch _measure_photometry).

argos.server.photometry.LOCK_MIN_SNR = 5.0

an anchor is seen at SNR 5 or more (S35’s threshold); the lock holds when ceil(n/2) of the n anchors are seen (S43’s rule).

Type:

S48

argos.server.photometry.LOCK_UNVERIFIED_TEXT = 'Photometry: only {n} anchor star{s} steer the apertures — the lock cannot be verified; points are flagged suspect while fewer than 3 anchor stars steer the apertures (except within 10 px of a solution of this sub or the previous one). Re-solving.'

until a verified frame, a slew or invalidation, or a set change.

Type:

S56 (release lock_unverified_text), once per episode

argos.server.photometry.LOCK_VERIFY_MIN_ANCHORS = 3

with fewer anchors ceil(n/2) is met by the very anchor that moved the solution: the lock is unverified…

Type:

S56 (release _LOCK_VERIFY_MIN_ANCHORS)

class argos.server.photometry.MeasureRequest(frame_seq: int, raw: ndarray, wcs: Any, epoch: datetime | None, generation: int, fwhm: float | None = None, run_root: Path | None = None, origin: str = 'live', reset_tracker: bool = False, egain: float | None = None, gain: int | None = None, scintillation: dict | None = None, exposure_s: float | None = None, filter_name: str | None = None, solved_seq: int | None = None, solved_raw: ndarray | None = None)[source]

Bases: object

One frame to measure through one solution.

exposure_s: float | None = None

the Camera form’s.

Type:

S74

Type:

a camera frame’s exposure (s); None

filter_name: str | None = None

a sub’s read-back FILTER, an opened file’s FILTER card, a live frame’s Camera form; None: the wheel’s settled slot, else the form.

Type:

The frame’s filter (S49)

gain: int | None = None

the live chain’s e-/ADU at it (the Camera form’s when None).

Type:

S83

Type:

a camera frame’s gain setting

scintillation: dict | None = None

an opened frame’s EXPTIME, AIRMASS and SITEELEV (frame_scintillation_inputs); None: a camera frame.

Type:

S74

solved_raw: ndarray | None = None

the raw frame wcs was solved on (None: unknown): the tracker’s anchors are chosen there, where the solution is exact.

Type:

S56 (2026-11-15, second set)

solved_seq: int | None = None

unknown). A solution of this frame or the previous one (seq - 1) is fresh.

Type:

S56

Type:

the seq of the frame wcs was solved on (None

argos.server.photometry.NO_EPOCH_TEXT = 'Photometry skipped: the frame has no exposure time (DATE-OBS/EXPTIME).'

The Qt texts (acquisition_engine.py:1612-1615; S35 in the release branch).

argos.server.photometry.OFF_CENTRE_TEXT = "Photometry: {n} comparison/check star{s} more than 1 px from the aperture centre — left out of the frame's ensemble, their points flagged suspect."

until a frame with none.

Type:

S69 (b) (release off_centre_text), once per episode

class argos.server.photometry.PhotometryService(hub: Hub)[source]

Bases: object

The live curves, their points and the leave-one-out report.

begin_run() → None[source]

Wave 6a: a sequence starts (start_sequence: clear_lightcurves; at its first save _on_seq_frame_saved closes the recorder, so the series FWHM and the frame counter restart with the run).

clear(reason: str = 'cleared') → None[source]

clear_lightcurves (258-274); also a sequence start (650-692, wave 6).

idle() → bool[source]

Nothing queued or measuring (tests).

live_record() → dict[str, Any][source]

GET /api/photometry/live (A54).

measure(request: MeasureRequest) → int[source]

_measure_photometry (1604-1667) on one frame; returns the points kept.

measure_saved_frame(request: MeasureRequest) → None[source]

A sequence’s saved sub (_on_seq_frame_saved, 793-797; wave 6).

on_field_invalidated() → None[source]

The solution was dropped (a slew, another source or geometry): the tracker and its anchors go with it (release invalidate_astrometry → _reset_tracker), so the next field’s first solution is not held to the previous field’s anchors (S54).

on_object_changed(object_name: str) → None[source]

on_object_changed (1281-1293): fresh curves for the new object.

on_solved(request: MeasureRequest) → None[source]

A new solution was applied: measure_photometry_if_idle (1062-1065).

on_targets_changed() → None[source]

A set change drops the tracker (release _anchors_changed, S52).

The next tracker is built on the solution as tracked so far, frozen here, never on the raw solution: the field has drifted since that solve, and a tracker rebuilt there kept only a neighbour seen at a stale position, passed the S48 check with 1 anchor of 1 and measured every aperture on blank sky until the next solve (the science review’s replay of RR Lyr 0-79). In a run the next sub is solved at once.

When the set’s stars changed, the status waits for the next measurement: the last one was of the previous set (its points, its frame).

refresh_status() → None[source]

Re-derive and publish the status when it changed (set, field, outcome).

reset_series_fwhm() → None[source]

An autofocus ended (Qt _on_af_finished): re-sample the series FWHM (P7).

series_fwhm() → float | None[source]

The frozen series FWHM (green px), read without the lock.

snapshots(seq: int) → list[tuple[str, int, dict[str, Any]]][source]

Hub lock held: what a new /ws/events client receives.

solution_refusal(raw: ndarray, wcs: Any, generation: int) → str | None[source]

Why a camera frame’s new solution is refused (S54), or None to accept it.

Release AcquisitionEngine._solution_refusal: a new solution rebuilds the tracker from the stars seen where it puts them, so a wrong match passes the S48 check by construction (XX Cyg 2026-09-07 045156Z frame 1: 1 anchor of 6 seen, the next frame measured 24 px off every star). Fewer than ceil(k/2) of the current tracker’s k anchors showing a star (SNR >= 5) where the new solution puts them on the frame it solved refuses it. Only a tracker built for the field’s current solution (generation) counts: none after a slew, an opened file or a set change. Called by the field’s solve thread, never with the hub lock held.

3 consecutive refused solutions that agree within REPOINT_AGREE_PX (S54 as amended on 2026-11-15, as S55 moves the scale reference): the field moved without a reported slew, the third is accepted and logged.

argos.server.photometry.REPOINT_SOLVES = 3

3 consecutive solutions refused by the anchor check that agree within 20 green px are a re-pointing the mount did not report: the third is accepted.

Type:

S54 as amended (release _REPOINT_SOLVES, _REPOINT_AGREE_PX)

class argos.server.photometry.SessionDiagnostics(path: Path | str, enabled: bool = True)[source]

Bases: object

The live flight recorder (argos/core/session/diagnostics.py, P11).

A line-for-line port: the core module sits in the argos.core.session package, whose __init__ imports the Qt DeviceSession (the server never imports Qt, tests/server/test_no_qt.py). One JSON object per line; a write error disables it with one warning; a no-op when disabled.

star(frame: int, star, phot, x: float, y: float, **extra: Any) → None[source]

extra: more fields (S69’s centroid_offset_px and off_centre).

argos.server.photometry.anchor_frame(green, wcs, solved_raw: ndarray | None)[source]

The frame the tracker’s anchors are chosen on and the solution exact there, or None (release AcquisitionEngine._anchor_frame, S56 as amended on 2026-11-15, second set): the frame wcs was solved on, of the measured frame’s geometry.

Chosen on the measured sub through a solution of an earlier one, only the stars that happened to show at the stale positions qualified after a jump, and the lock check (S48, S56) verified the very star that moved the apertures (real RR Lyr subs moved 500 px without a slew: 1 anchor, 2.16 px of tracker motion, the target 496 px off). On the solved frame every anchor qualifies, and the check counts those the measured sub shows (1 of 6 there: the lock is lost).

argos.server.photometry.bundled_iers_only() → None[source]

Never let astropy download IERS or leap-second tables (release S37).

Core’s bjd_tdb lets astropy fetch finals2000A.all and the leap seconds on first use; offline it then refuses its bundled table and every BJD_TDB is lost (2.3 s per frame refused, ~18 s on a hanging network). The bundled tables give the same BJD to the bit. Same settings as the mount’s coordinate conversion (telescope.py) and the release branch’s fix.

argos.server.photometry.centred_anchors(anchor_stars, tracker, offsets) → int[source]

S69 (b) (release _centred_anchors): the tracker’s anchors less those more than 1 px off their aperture centre on this frame and the one its fit rejected (it verified nothing); without the centring check (GUARD), all of them.

argos.server.photometry.curve_key(star, token: str) → str[source]

One curve per (star, filter) (S49, release lightcurve.curve_key): <AUID or name>@<filter token>.

argos.server.photometry.filter_token(filter_name: str | None) → str[source]

The filter as frame and curve file names spell it (release fits_writer.filter_token, S49): the abbreviation (FILTER_ABBREV), ASCII letters, digits, _ and -, lower case; clear for none. Its parity with the core’s is a guarded test.

argos.server.photometry.new_preview_csv(folder: Path, obj: str, tag: str, now: datetime, taken=(), token: str = '') → Path[source]

_new_preview_csv (S40, S49): <folder>/<object>_<YYYYMMDDTHHMMSSZ>_<filter>_<star>.csv, a file not yet used; -2, -3… on the time for curves started in the same second. Review still finds <object>.json and the star.

argos.server.photometry.no_detection_rule()[source]

GUARD (S85, release/0.5.0): the core review’s flag_no_detection, S67’s per-target rule applied when a point is measured (a target below SNR 3: its point suspect and no_detection, out of sigma_syst), else None: until the release core is merged such a point is written unflagged, as before S85. The module is path-loaded (review.core_review, imported here: it imports this module).

argos.server.photometry.point_record(point: LcPoint, frame_seq: int | None, t: str | None, zero_point: float | None = None, zp_rms: float | None = None) → dict[str, Any][source]

An LcPoint on the wire (every field of lightcurve.py:38-62, unrounded).

Plus the star’s ensemble zero point and its rms on that frame (DiffResult, the flight recorder’s ensemble record): not in the CSV, the night’s extinction and transparency trend for the plot’s ensemble facet.

argos.server.photometry.s69_core()[source]

GUARD (S69, release/0.5.0): the core’s tracking module when it has S69’s centring check and rotation rule (centring_offsets, off_centre, rotation_resolve_due, TrackedWCS.rotation_deg; measure_frame and measure_targets take exclude) and the neighbour rule of the S69 review (neighbour_distance; select_tracking_anchors and centring_offsets take neighbours, ApertureTracker.rejected_anchor), else None: until the release core is merged the live path, the sequence path and the re-run (rerun.py) measure as before, S70 included (S70 is applied together with S69).

argos.server.photometry.safe_name(text: str) → str[source]

_photometry_csv_path / _diagnostics file-name rule (1531-1540, 897).

argos.server.photometry.set_neighbours(tset) → dict[source]

S69 (GUARD: s69_core()): neighbours= the set’s stars, targets included, for select_tracking_anchors and centring_offsets (a star beside a brighter one of the set is no anchor, and its centring centroid stays clear of it).

argos.server.photometry.solutions_span_px(solutions: list, green_shape: tuple[int, int]) → float[source]

S54 (release solutions_span_px): the largest distance (green px) between where the solutions put the newest one’s frame centre.

argos.server.photometry.star_curve_key(star) → str[source]

Qt’s star key (_emit_live_point, 1740): the AUID, else the display name.

argos.server.photometry.write_csv_atomic(curve: LightCurve, path: Path) → None[source]

LightCurve.to_csv written beside the file and renamed over it (release S38).

A reader (Review, a spreadsheet) or a crash mid-write sees the previous file or the new one, never a truncated one. The same bytes as to_csv.

The sequence plan draft, its presets and plan files (rows A59-A61).

A Qt-free port of the Plan editor’s model side (sequence_panel.py, sequencer_page.py) over the unchanged core model (argos.core.imaging. sequencer): SequencePlan / SequenceStep, total_frames, estimated_duration_s, plan_to_dict and plan_from_dict, so the totals, the estimate and the preset files are Qt’s by construction.

Two things change on purpose (web/spec/06-plan-sequencer.md §1.16):

  • No silent clamp (P11, S7). The Qt spin boxes clamp a value to their range and the combos substitute an unknown filter or frame type; here the plan is stored exactly as typed and every such value is an issue (plan_issues()). Issues of level error refuse a run (PlanService.plan_for_run()).

  • The draft persists (P13, Q-P3) in sequence_draft.json beside config.json, written atomically, and keeps its planning metadata for the object it was prepared for (P1, S5).

argos.server.sequence_plan.COUNT_RANGE = (1, 9999)

The other Qt spin-box ranges (sequence_panel.py:333, 338, 410, 766, 772, 780).

argos.server.sequence_plan.DEFAULT_FILTERS: tuple[str, ...] = ('IR', 'LP', 'Dark')

Qt’s Plan editor filters before a wheel reports its slots (sequence_panel.py:66).

argos.server.sequence_plan.DEFAULT_GAIN_RANGE: tuple[int, int] = (0, 600)

Qt’s fallback spin-box limits without a camera (sequence_panel.py:70-71).

class argos.server.sequence_plan.ExportBody(*args: Any, **kwargs: Any)[source]

Bases: _Strict

class argos.server.sequence_plan.ImportBody(*args: Any, **kwargs: Any)[source]

Bases: _Strict

class argos.server.sequence_plan.PlanBody(*args: Any, **kwargs: Any)[source]

Bases: _Strict

A plan as plan_to_dict writes it, plus schema and start_at_utc.

class argos.server.sequence_plan.PlanService(hub: Hub, clock: Callable[[], datetime] | None = None)[source]

Bases: object

The draft plan (A59), its presets (A60) and plan files (A61).

export_plan(body: ExportBody) → dict[str, Any][source]

POST /api/sequence/plan/export: Qt’s preset format at an absolute path.

filter_names() → list[str][source]

The filter names a step is checked against (wheel, profile, Qt’s defaults).

import_plan(body: ImportBody) → dict[str, Any][source]

POST /api/sequence/plan/import: Qt’s Load preset (metadata not restored).

plan_for_run() → SequencePlan[source]

The draft for the engine; 400 naming the first error (Fix step N: …).

presets_directory() → Path[source]

_presets_dir (sequence_panel.py:963-971).

publish() → dict[str, Any][source]

Re-send sequence_plan (the sequence engine calls it at a run’s start and end).

put(body: PlanBody) → dict[str, Any][source]

PUT /api/sequence/plan: stored as typed, every clamp an issue.

record() → dict[str, Any][source]

GET /api/sequence/plan (the draft follows the observation’s object).

run_active() → bool[source]

Whether a sequence runs (the plan is then locked, Q-P9).

set_transit_plan(plan: SequencePlan, notes: list[str], start_at_utc: str | None = None) → dict[str, Any][source]

POST /api/transit/plan: the prepared plan becomes the draft, with its metadata.

start_at_utc schedules the run at the coverage start (Q-P2; Qt P7: a transit plan is a fixed frame count, started by hand).

class argos.server.sequence_plan.StepBody(*args: Any, **kwargs: Any)[source]

Bases: _Strict

One SequenceStep; missing keys take the model’s defaults.

argos.server.sequence_plan.core_plan(plan: dict[str, Any]) → SequencePlan[source]

The stored plan as the core model the engine runs.

argos.server.sequence_plan.default_plan(filters: list[str], object_name: str = '') → dict[str, Any][source]

Qt’s first editor row (SequencePanel.__init__: _add_row()), on a light slot.

argos.server.sequence_plan.derived_values(plan: dict[str, Any], now: datetime) → dict[str, Any][source]

Totals and estimate with the core’s own functions (sequencer.py:172-198).

argos.server.sequence_plan.light_filter_default(filters: list[str]) → str[source]

_light_filter_default (sequence_panel.py:694-703): never the Dark slot.

argos.server.sequence_plan.light_filters_warning(plan: dict[str, Any]) → str | None[source]

S49 (release sequencer.light_filters_warning): the enabled Light steps use two filters or more (two names of one filter token count once), or None.

argos.server.sequence_plan.normalise_object(name: Any) → str[source]

The observation’s own rule (ObservationService.set_name): one space.

argos.server.sequence_plan.observation_json(plan: SequencePlan) → str | None[source]

The exact text Qt writes (indent=2, sort_keys=True).

argos.server.sequence_plan.observation_payload(plan: SequencePlan) → dict[str, Any] | None[source]

observation.json of a run, as SequenceWorker._write_observation_metadata (sequence_worker.py:462-480); None when the plan has no metadata.

argos.server.sequence_plan.parse_utc(text: str) → datetime[source]

An ISO 8601 instant; a naive one is UTC. ValueError when unreadable.

argos.server.sequence_plan.plan_dict_from_body(body: PlanBody) → dict[str, Any][source]

The stored plan (schema 2): the body’s values as typed, frame types canonical.

argos.server.sequence_plan.plan_dict_from_json(data: Any) → dict[str, Any][source]

A plan read from a file (a Qt preset, an export, the draft).

The file must be one the Qt app can read too (plan_from_dict: an unknown step key or frame type is refused), then it is checked as a request body. ValueError with the reason otherwise.

argos.server.sequence_plan.plan_issues(plan: dict[str, Any], *, exposure_range: tuple[float, float], gain_range: tuple[int, int], limits_source: str, filters: list[str], filters_source: str, now: datetime) → list[dict[str, Any]][source]

Every value the Qt editor would clamp or substitute, and what would refuse a run.

argos.server.sequence_plan.preset_name(raw: str) → str[source]

A preset name, validated (no path, no hidden file); a .json suffix is ignored.

argos.server.sequence_plan.qt_preset_text(plan: dict[str, Any]) → str[source]

The file Qt’s Save preset writes (sequence_panel.py:973-985).

argos.server.sequence_plan.qt_ranges(limits: dict[str, Any] | None) → tuple[tuple[float, float], tuple[int, int]][source]

Exposure and gain ranges as set_camera_limits (sequence_panel.py:1016-1041).

Sequences (wave 6a, rows A62-A64): run a plan, the mount interlock, the preflight.

A Qt-free port of the fixed (release 0.5.0) Qt sequence path:

  • AcquisitionEngine.start_sequence / stop_sequence / pause_sequence / resume_sequence_run / _on_seq_frame_saved / _on_seq_autofocus_due / _on_seq_finished / _run_on_complete_action / _sequence_frame_context (argos/core/session/acquisition_engine.py:712-945);

  • SequenceWorker._run / _set_filter / _read_back_filter / _shoot_one / _append_session / _write_observation_metadata / _dither / _await_autofocus (argos/workers/sequence_worker.py:162-503);

  • the readiness line of sequence_panel.py:1125-1141, grown into the preflight of web/lab/PROPOSAL.md §7.

The core does the science unchanged: expand_plan and total_frames (sequencer.py), FITSWriter (folders, names, headers), SessionLog, TargetSet. The run has its own thread; the FITS of a sub is written on it (as the Qt worker does), never on the event loop; each photometry point is measured on the photometry thread (PhotometryService.measure_saved_frame).

State lives under the hub lock, as every service’s; nothing here holds it across device I/O, a thread join or a file write.

argos.server.sequence.CADENCE_WINDOW = 10

Subs whose start-to-start intervals make the observed cadence.

argos.server.sequence.DEFAULT_MIN_ALT_DEG = 30.0

Altitude limit when the site has none (Q-P6).

argos.server.sequence.DITHER_RATE_DEG_S = 0.05

52-57 — dither pulse and settle.

Type:

sequence_worker.py

argos.server.sequence.FILTER_SETTLE_S = 20.0

47 — the longest wait for the wheel to settle.

Type:

sequence_worker.py

argos.server.sequence.FRAME_OVERHEAD_S = 3.0

178 — per-frame overhead of the estimate (planned cadence).

Type:

sequencer.py

argos.server.sequence.GEOMETRY_KEYS = ('photometry.aperture_fwhm_mult', 'photometry.aperture_min_px', 'photometry.annulus_in_px', 'photometry.annulus_out_px')

The four aperture-geometry settings locked during a run (S15).

argos.server.sequence.GEOMETRY_LOCK_REASON = 'The aperture geometry is locked while a sequence runs (one curve, one aperture).'

Why each locked group cannot change during a run (the 409’s words, and the web Settings page’s).

argos.server.sequence.HEADER_BYTES = 17280

FITS header and padding of one sub (6 blocks of 2880 bytes, generous).

argos.server.sequence.MOTION_LOCKED = frozenset({'autofocus', 'pausing', 'running', 'stopping'})

States in which a mount motion would move the field under an exposure (D2).

argos.server.sequence.NOISE_MODEL_KEYS = ('photometry.noise_model', 'photometry.read_noise_e', 'camera.egain_table', 'data_paths.camera_calibration_directory')

the model, the read noise and the observer’s two inputs of the camera’s e-/ADU (the gain table, the photon-transfer folder: S73’s chain) set the SNR the gates read (S35, S56, S58, S69) and the formal errors of every point. The release core’s params.NOISE_MODEL_KEYS (tests/server/test_sequence.py checks they agree).

Type:

The noise model’s settings, locked during a run as the geometry is (S84)

argos.server.sequence.SHUTDOWN_JOIN_S = 15.0

Joining the run thread at shutdown.

argos.server.sequence.SLEW_WAIT_MAX_S = 300.0

Before an exposure the run waits this long at most for a slew to end, then pauses.

argos.server.sequence.START_AF_WAIT_S = 300.0

A scheduled start waits at most this long for an autofocus to release the camera.

argos.server.sequence.START_AHEAD_MAX_S = 86400.0

A start time further ahead is refused (no silent clamp).

argos.server.sequence.STATES = ('idle', 'waiting', 'running', 'pausing', 'paused', 'autofocus', 'stopping')

Every state but idle is an active run (the plan is locked, Q-P9).

class argos.server.sequence.SequenceService(hub: Hub)[source]

Bases: object

The sequence engine: one run at a time, its record, the interlock.

calibration_plan(darks: int | None = None, biases: int | None = None)[source]

POST /api/sequence/calibration-plan: the draft takes tonight’s darks and biases.

clock: Callable[[], datetime]

a scripted one).

Type:

The clock of DATE-OBS / DATE-AVG and the run id (tests

close() → None[source]

Server shutdown: stop the run and wait for it (≤ 15 s).

device_lost(device_id: str) → None[source]

The hub is disconnecting a device: a run that needs it ends now.

guard_config(changes: Any) → None[source]

PATCH /api/config during a run: the aperture geometry (S15) and the noise model (S84) are locked; nothing of the PATCH is written.

guard_motion(action: str, pause_run: bool = False) → None[source]

409 run_active for a mount motion during a run; pause_run pauses first.

holds_camera() → bool[source]

Lock held: a run owns the camera (it hands it to a mid-run autofocus).

on_autofocus_end() → None[source]

The hub’s autofocus ended (any outcome): wake a run waiting for it.

on_target_set_saved(tset: Any) → None[source]

An in-run target-set edit is journalled in the run folder (Q-P9).

photometry_wait_s

2 s.

Type:

How long the end waits for the last sub’s photometry (s); shutdown

plan_issues(plan: SequencePlan) → list[dict[str, Any]][source]

The engine’s own checks: what the run relies on (never clamped, S7).

plan_provider: Callable[[], SequencePlan] | None

a callable returning a core SequencePlan.

Type:

Tests without the plan half

preflight(start_at_utc: str | None = None, *, given: bool = False) → dict[str, Any][source]

GET /api/sequence/preflight: worst level first.

run_active() → bool[source]

The plan half’s question (protocol.md “In-process interface”).

snapshots(seq: int) → list[tuple[str, int, dict[str, Any]]][source]

Lock held: the sequence snapshot a new client receives.

start(start_at_utc: str | None = None, *, given: bool = False) → dict[str, Any][source]

POST /api/sequence/start. given: the body had a start_at_utc member.

summary() → dict[str, Any][source]

Lock held: the status record’s sequence member.

target_radec() → tuple[float, float] | None[source]

The running plan’s target (hours, degrees), for the altitude rule; None for a run without Light frames (the preflight’s “Calibration frames only: no altitude needed”: the wrap-up’s darks at dawn raised a false altitude alert).

wrapup() → dict[str, Any][source]

GET /api/sequence/wrapup.

argos.server.sequence.observation_payload(plan: SequencePlan) → dict[str, Any] | None[source]

SequenceWorker._write_observation_metadata (sequence_worker.py:462-480).

argos.server.sequence.parse_utc(text: Any) → datetime[source]

An ISO 8601 time with a zone, as an aware UTC datetime; ValueError else.

argos.server.sequence.wire_plan(plan: SequencePlan) → dict[str, Any][source]

The schema-2 record of a plan (plan_to_dict plus schema).

Visibility, exoplanet lookups and the transit planner (rows A42, A65, A66).

  • Visibility (A65): a target’s altitude over one night at the Settings site. Altitudes are the core’s fast spherical trigonometry (sky_geometry.altitude_at, the function Qt’s visibility plot samples through upcoming_night_altitudes); the night is astronomical dusk to dawn (Q-P6) instead of Qt’s fixed 18:00-06:00, and a night spans midnight (S26). The Sun is the Astronomical Almanac’s low-precision position.

  • Exoplanets (A42): exoplanets.lookup_exoplanet and cached_exoplanet_suggestions with the configured cache file.

  • Transits (A66): predict_next_transit from bjd_tdb(julian_date( now)) at the site and utc_from_bjd_tdb as sequencer_page.py:132-187, make_transit_sequence as _prepare_transit_plan (248-286). The server chooses the transit: daylight and below-limit transits are skipped (Q-P10).

Nothing here uses the network except the explicit exoplanet lookup; a site is required (X2: never latitude/longitude 0/0).

argos.server.planning.MAX_BASELINE_MIN = 240.0

Qt’s Baseline spin box (sequence_panel.py:394).

class argos.server.planning.PlanningService(hub: Hub, clock: Callable[[], datetime] | None = None)[source]

Bases: object

Routes A42, A65 and A66 (the draft itself is PlanService).

lookup: Callable[[...], ExoplanetTarget]

no network).

Type:

Injectable lookups (tests

lookup_record(query: str) → dict[str, Any][source]

GET /api/exoplanets/lookup (ExoplanetLookupWorker).

plan(body: TransitPlanBody) → dict[str, Any][source]

POST /api/transit/plan: _prepare_transit_plan made the draft.

predict(body: TransitBody) → tuple[ExoplanetTarget, TransitWindow, dict[str, Any]][source]

The transit window, chosen as Q-P10 says, and its record.

suggest(query: str, limit: int = 8) → dict[str, Any][source]

GET /api/exoplanets/suggest: offline, from the cache.

argos.server.planning.SEARCH_DAYS = 366.0

How far ahead an observable transit is searched (Q-P10).

argos.server.planning.SUNSET_DEG = -0.833

refraction + semi-diameter).

Type:

Sun altitudes of the twilight limits (degrees; sunset

argos.server.planning.TRANSIT_BATCH = 48

Candidate transits whose BJD_TDB − UTC correction is computed in one astropy call: one scalar call per candidate stalled the event loop (0.4 s for a 366-day search).

argos.server.planning.TRANSIT_CHECK_S = 120.0

Transit observability is checked on this grid (s) plus both ends.

class argos.server.planning.TransitBody(*args: Any, **kwargs: Any)[source]

Bases: _Strict

class argos.server.planning.TransitPlanBody(*args: Any, **kwargs: Any)[source]

Bases: TransitBody

argos.server.planning.crossings(f: Callable[[float], float], t0: float, t1: float, level: float, step: float) → list[tuple[float, bool]][source]

Times where f crosses level in [t0, t1], with rising (to ½ s).

argos.server.planning.current_night_date(now: float, lat: float, lon: float) → date[source]

The night whose dawn has not passed yet (P3: 02:00 belongs to last evening’s).

argos.server.planning.intervals(f: Callable[[float], float], t0: float, t1: float, level: float, step: float, above: bool) → list[tuple[float, float]][source]

Maximal intervals of [t0, t1] where f >= level (above) or f < level.

argos.server.planning.jd_of(t: float) → float[source]

JD (UTC) of a Unix time, as upcoming_night_altitudes converts it.

argos.server.planning.lookup_error(exc: ExoplanetLookupError) → ApiError[source]

The core’s text with a contract code.

argos.server.planning.night_date_for(t: float, lon: float) → date[source]

The evening date of the noon-to-noon night containing t (02:00 → the day before).

argos.server.planning.night_of(day: date, lat: float, lon: float) → dict[str, Any][source]

Twilight instants and the astronomical night of the evening of day.

argos.server.planning.solar_noon(day: date, lon: float) → float[source]

Unix time of the local mean solar noon of day (UTC noon minus longitude/15 h).

argos.server.planning.sun_altitude(t: float, lat: float, lon: float) → float[source]

Sun altitude (degrees, no refraction) at Unix time t.

argos.server.planning.sun_radec(jd: float) → tuple[float, float][source]

Apparent Sun (RA hours, Dec degrees), Astronomical Almanac low precision (≈0.01°).

argos.server.planning.visibility(ra_hours: float, dec_deg: float, lat: float, lon: float, day: date, *, step_min: int = 10, min_alt_deg: float = DEFAULT_MIN_ALT_DEG) → dict[str, Any][source]

Altitude samples, peak and the window above min_alt_deg in the astronomical night.

The night

Attention rules (alerts, never an action on the mount), keep-awake during a run, the end-of-night wrap-up.

Attention for unattended runs (wave 6b; PROPOSAL §7, owner decision D3).

The rules of web/lab/research/functional-spaces.md §4.10, computed by the server so that every client shows the same list and an acknowledgement made on one is seen by all (protocol.md “Night (wave 6b)”).

A port of web/src/lab/workspace/model/rules.ts, whose tests are the oracle (tests/server/test_attention.py replays the lab’s synthetic night). The lab evaluates the whole record list each time (evaluate, rules.ts:65-152); here the same thresholds run per frame with hysteresis:

  • RULES (rules.ts:33-39) → Thresholds, config keys alerts.*;

  • firstRun (rules.ts:42-49), K records in a row → _Streak, which also clears after K records in a row back inside the threshold;

  • silenceLimit (rules.ts:52-56): max(2 × median cadence, median + 60 s), the cadence and the silence measured between saves (a client learns of a frame when it is saved); before two saves 2 × floor + 60 s;

  • the HFD and star-count baselines: the median of the first 20 frames (rules.ts:88-121), here per filter (one curve per filter, S49), carried over the runs of one server session (owner decisions 2026-11-14 and 2026-11-15: a run restarted after trouble is judged from its first sub): the HFD baseline when object and filter match, the star-count baseline when object, filter, exposure and gain match, never after 12 h without a sub of its setup; per run otherwise; a server restart starts fresh;

  • comparisons used below 3, K frames in a row (rules.ts:124-138);

  • every message states the rule and the numbers (rules.ts:7-8).

The service observes the published events through an EventBus tap (the tap only queues them) and evaluates them on its own thread, plus a 1 s timer for the timed rules (no new frame, altitude, disk): evaluation never runs on the event loop.

argos.server.attention.ALTITUDE_CLEAR_MARGIN_DEG = 0.5

Hysteresis of the timed rules.

class argos.server.attention.AttentionService(hub: Hub, *, tick_s: float = 1.0)[source]

Bases: object

The attention list of the server (rules, items, acknowledgement).

clock: Callable[[], datetime]

a scripted one).

Type:

The wall clock (tests

flush(timeout: float = 2.0) → bool[source]

Wait until every event queued so far is evaluated (wrap-up, tests).

run_summary(run_id: str | None) → dict[str, Any][source]

The run’s items and photometry outcomes, for its wrap-up.

snapshots(seq: int) → list[tuple[str, int, dict[str, Any]]][source]

Hub lock held: the attention snapshot a new client receives.

tick() → None[source]

Every second (the worker): no new frame; every 60 s: altitude and disk.

timings: deque[float]

Evaluation time of the last events (s), for the “never blocks” check.

class argos.server.attention.Baseline(metric: str, value: float, frames: int, run_id: str | None, run_t: float | None, object: str, filter: str, exposure: float | None, gain: int | None)[source]

Bases: object

One baseline of a filter (metric: the HFD’s or the star count’s) and the run whose first subs made it.

origin(carried: bool) → str[source]

Words for the texts: “the first 20 frames” or “… of the run of 04:07 UTC”.

record(carried: bool) → dict[str, Any][source]

Its origin in the snapshot’s baselines (hfd_from, stars_from).

values(carried: bool) → dict[str, Any][source]

The origin in an item’s values (protocol.md: number|string|null).

class argos.server.attention.BaselineStore[source]

Bases: object

The server session’s finished baselines, carried over its runs.

The HFD baseline by hfd_baseline_key(), the star-count one by baseline_key(). A baseline is stored by the run that made it when no other is held for its key (a carried one is never replaced by a later run’s), and dropped once no sub of its setup came for CARRY_MAX_IDLE_S (sub DATE-OBS). In the server process only: a restart starts fresh.

baselines(metric: str) → dict[tuple, Baseline][source]

The held baselines of a metric by key (tests, replays).

get(metric: str, key: tuple | None, t: float) → Baseline | None[source]

The baseline carried for key at sub time t, or None.

seen(metric: str, key: tuple | None, t: float) → None[source]

A sub of that setup at t: its baseline stays carried 12 h more.

argos.server.attention.CADENCE_KEEP = 200

Start-to-start intervals kept for the cadence of the “no new frame” rule.

argos.server.attention.CARRY_MAX_IDLE_S = 43200.0

a baseline not fed a sub of its setup for this long is no longer carried (seeing changes from night to night; a server left running).

Type:

Owner decision 2026-11-15

argos.server.attention.ERROR_REASONS = frozenset({'autofocus_timeout', 'camera_error', 'device_lost', 'refused', 'save_error', 'wheel_error'})

Run outcomes that are a critical “run stopped on error” (protocol.md RunResult).

argos.server.attention.HISTORY_MAX = 200

Items kept in the history.

class argos.server.attention.NightRules(thresholds: Thresholds | None = None, baselines: BaselineStore | None = None)[source]

Bases: object

The frame and timed rules of one run (no items, no I/O).

baselines is the server session’s BaselineStore (shared by the runs, filled here; None: per-run only).

add_measured(comps_used: int | None, n: int | None, t: float | None) → list[Signal][source]

A Light sub measured: comparisons used (rules.ts:124-138); the tracker is fine.

add_skipped(reason: str, n: int | None, t: float | None) → list[Signal][source]

A Light sub without a point (photometry skipped): the tracker rule.

add_sub(sub: Sub) → list[Signal][source]

One saved Light sub: the HFD and star-count rules (rules.ts:88-122).

baselines() → list[dict[str, Any]][source]

The run’s baselines in force, one entry per filter (the snapshot’s baselines).

break_segment() → None[source]

A pause, an autofocus or a new step: the cadence restarts.

cadence(planned: float | None = None) → float[source]

The median cadence; before two subs since the last break, the larger of the planned cadence and the newest sub’s start-to-save time (a Seestar’s download makes a 10 s sub cost 20-45 s, against 13 s planned: RR Lyr 2026-09-25), else NaN.

run_id: str | None

set by the service once known.

Type:

The run (its baselines’ origin)

silence(now: float, running: bool, reference: float | None, planned: float | None = None) → list[Signal][source]

The liveness rule: a frozen run looks exactly like a healthy one between frames.

silence_limit(planned: float | None = None) → float[source]

max(F × cadence, cadence + M) s (rules.ts:52-56), the cadence between saves.

Before two saves since the last break, F × floor + M (floor: cadence()): the first interval also carries the run’s start-up and the next sub’s start-to-save time. max(F × floor, floor + M) there raised a false critical alarm at the start of all 9 of the owner’s runs (the science review’s replay; RR Lyr 2026-09-25: sub 2 saved 112 s after sub 1 started, limit 104.5 s).

sub_cost: float | None

a floor of the cadence before two subs.

Type:

The newest sub’s start-to-save time (s)

argos.server.attention.REOPEN_QUIET_S = 900.0

A non-critical item reopened within this time of its last tone gets no new tone and no new log line (a value flapping across its threshold all night).

argos.server.attention.REOPEN_S = 600.0

A cause that fires again within this time of its clear reopens its item.

argos.server.attention.RULE_NAMES = {'altitude': 'Altitude', 'autofocus_done': 'Autofocus done', 'autofocus_failed': 'Autofocus failed', 'comps_low': 'Comparisons used', 'device_lost': 'Device lost', 'disk': 'Disk space', 'hfd_rise': 'HFD rise', 'no_frame': 'No new frame', 'run_ended': 'Run ended', 'run_error': 'Run stopped', 'run_started': 'Run started', 'star_drop': 'Star count drop', 'tracker_lost': 'Tracker lost'}

The rules in words (the lab’s rule strings, rules.ts).

argos.server.attention.RUN_ITEMS_MAX = 500

Items of one run kept for its wrap-up, and the runs kept.

argos.server.attention.SLOW_PERIOD_S = 60.0

Period of the slow timed rules (altitude, disk).

class argos.server.attention.Signal(cause: str, rule: str, on: bool, title: str = '', short: str = '', detail: str = '', values: dict[str, ~typing.Any]=<factory>, since: float | None = None, frame: int | None = None, why: str = '')[source]

Bases: object

A rule’s verdict for one cause: on (fire or keep) or off (clear).

class argos.server.attention.Sub(n: int, t: float, hfd: float | None, stars: int | None, filter: str = '', saved: float | None = None, object: str = '', exposure: float | None = None, gain: int | None = None)[source]

Bases: object

One saved Light sub of the run (the lab’s FrameRecord, night.ts:29-47).

saved: float | None = None

t.

Type:

When the file was saved (unix s)

Type:

what a client sees arrive. None

argos.server.attention.TRACKER_LOST_REASONS = ('field_lost', 'lock_lost')

Photometry skip reasons that mean “the stars are not where the solution puts them”.

class argos.server.attention.Thresholds(consecutive: int = 3, baseline: int = 20, hfd_factor: float = 1.5, star_factor: float = 0.7, comps_min: int = 3, no_frame_factor: float = 2.0, no_frame_margin_s: float = 60.0, altitude_warn_min: float = 15.0, disk_minutes: float = 30.0)[source]

Bases: object

RULES of rules.ts:33-39 plus the timed rules; config keys alerts.*.

argos.server.attention.WATCHED = frozenset({'devices', 'frame_saved', 'photometry', 'photometry_point', 'sequence'})

Event kinds the service watches.

argos.server.attention.baseline_key(sub: Sub) → tuple[str, str, float, int] | None[source]

What must match for the star-count baseline to be carried: object, filter, exposure and gain (2 217 stars at 20 s gain 80 against 3 455 at 60 s gain 100 on 2026-09-07). None (never carried, never stored) when one is unknown or the object unnamed. Exposures compare to the millisecond.

argos.server.attention.hfd_baseline_key(sub: Sub) → tuple[str, str] | None[source]

What must match for the HFD baseline to be carried: object and filter (owner decision 2026-11-15: the HFD of a field does not follow exposure or gain the way the star count does). None: never carried, never stored.

Keep the computer awake while a run is active (wave 6b, PROPOSAL §3.1).

A sleeping computer stops a run: the exposure, the wheel and the save all stop with it. While a sequence is active the server holds an OS sleep assertion with the tools the OS already has (no new dependency):

  • macOS: caffeinate -i -w <server pid>, a PreventUserIdleSystemSleep assertion named “caffeinate command-line tool” in pmset -g assertions. -w ties it to the server process, so it ends even if the server dies.

  • Linux: systemd-inhibit --what=idle:sleep --mode=block around tail --pid=<server pid> -f /dev/null (it ends with the server too).

  • Windows: SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED) through ctypes, on a holder thread (the state belongs to the thread that set it and ends with it).

The display may still sleep (the Watch view adds navigator.wakeLock); closing a laptop lid still sleeps most laptops: out of software reach, the preflight says so.

KeepAwake is driven by want() (non-blocking, safe under the hub lock); a small worker thread starts and stops the assertion, so no process is spawned under a lock. Only the CLI server (manage_process) uses the real OS backends; in-process tests get NullBackend or a fake.

class argos.server.keepawake.Assertion(*args, **kwargs)[source]

Bases: Protocol

class argos.server.keepawake.Backend(*args, **kwargs)[source]

Bases: Protocol

One OS method: available() says whether it can work here and why not.

class argos.server.keepawake.CaffeinateBackend(pid: int | None = None)[source]

Bases: object

macOS: caffeinate -i -w <pid>.

class argos.server.keepawake.KeepAwake(backend: Backend, on_change: Callable[[], None] = lambda : ..., enabled: Callable[[], bool] = lambda : ..., log: Callable[[str, str], None] = lambda level, text: ...)[source]

Bases: object

The run’s sleep assertion: wanted while a run is active, held by a worker.

acquired

Assertions taken and released (tests and the smoke check).

capability() → tuple[bool, str | None, str | None][source]

For the preflight: (works, method, why not).

close() → None[source]

Server shutdown: release now (synchronously) and stop the worker.

recheck() → None[source]

alerts.keep_awake changed: apply it to the run in progress now.

Turned off during a run, the assertion is released; turned on, it is taken (before, both waited for the next run).

settle(timeout: float = 5.0) → bool[source]

Wait until the held state matches the wanted one (tests, shutdown).

want(reason: str | None) → None[source]

Hold (a reason) or release (None); non-blocking, any thread, any lock.

Wave 8: with a method and the setting on, the record says held at once, so the status that announces the run says it too. The helper holds the OS assertion within milliseconds of its start, while the check that it stayed alive takes _ALIVE_CHECK_S; before, the record read off during that check (pmset already listed the assertion). A helper that fails turns it to failed.

class argos.server.keepawake.NullBackend(reason: str = 'keep-awake is off in this process')[source]

Bases: object

No OS call: in-process tests and platforms without a method.

class argos.server.keepawake.SystemdInhibitBackend(pid: int | None = None)[source]

Bases: object

Linux: systemd-inhibit for as long as the server process lives.

argos.server.keepawake.os_backend(platform: str | None = None) → Backend[source]

The real backend for this OS.

The end-of-night wrap-up (wave 6b; PROPOSAL §3.1, owner decision D2).

When a run ends the Run card turns into the next steps (web/lab/research/functional-spaces.md §4.14): what the run produced, the attention items it raised, the tracking state, and the calibration frames matching tonight’s Lights, prefilled with a time estimate from the run’s own per-frame cost (exposure + download + save, measured on its subs), not the exposure alone (functional-spaces finding 1). No calibration frame exists in any of the owner’s 19 session folders (functional-spaces §1.2).

Pure helpers here; argos.server.sequence.SequenceService gathers the inputs and publishes the record (protocol.md “Wrap-up”).

argos.server.wrapup.DEFAULT_DARKS = 20

darks 15-20, biases 20-30).

Type:

The guide’s counts (functional-spaces §4.14

argos.server.wrapup.MIN_OVERHEAD_S = 3.0

178).

Type:

The per-frame overhead of the plan estimate (sequencer.py

argos.server.wrapup.PLAN_MIN_EXPOSURE_S = 0.01

The shortest exposure a plan accepts without camera limits (Qt’s 0.01 s floor).

argos.server.wrapup.calibration(plan: SequencePlan, *, tonight: list[tuple[str, float, int, str]], overhead: float | None, cadence: float | None, min_exposure_s: float | None, dark_slot: bool, darks: int = DEFAULT_DARKS, biases: int = DEFAULT_BIASES) → dict[str, Any][source]

Darks per (exposure, gain) and biases per gain of the Light steps.

argos.server.wrapup.calibration_plan(plan: SequencePlan, calib: dict[str, Any], *, darks: int, biases: int) → dict[str, Any][source]

The draft (PlanBody keys) taking calib’s darks and biases: one step each.

argos.server.wrapup.folder_bytes(path: str | PathLike | None) → int | None[source]

Total size of the files under path (None when it does not exist).

argos.server.wrapup.light_series(plan: SequencePlan) → list[tuple[float, int, str]][source]

(exposure, gain, filter) of the plan’s enabled Light steps, first seen first.

argos.server.wrapup.overhead_s(costs: Iterable[tuple[float, float]]) → float | None[source]

Median of (sub duration − exposure) over the run’s subs, at least 3 s.

A sub’s duration is DATE-OBS to its save (exposure, download, FITS write): what a dark costs too; a cadence or an interval wait is not in it.

argos.server.wrapup.point_counts(live: dict[str, Any]) → dict[str, int][source]

Points of the live curves (the run’s: they restart with it), by role and flags.

Review

Sessions and curves (read by the core’s own reader), the frame inspector, the AAVSO and CSV exports and the batch re-run.

Review: open a recorded session, its curves, a curve CSV, the live run (rows A67-A70).

The session reader is the fixed Qt reader itself, argos/core/session/review.py (0.5.0: S9 check role, S10 one-star CSV identity, S49 file names), loaded from its file by core_review(): its package argos.core.session imports PyQt6, which the server must not (tests/server/test_no_qt.py), while the module itself is Qt-free (it says so). Loading the same file keeps every text and rule identical to Qt without a copy that could drift.

What this module adds around it (protocol.md “Review (wave 7)”):

  • the open as a job with progress and cancel (session_open): load_session( read_temperature=False) then one header per frame (Qt read CCD-TEMP on the UI thread, U9), the curves, the flight recorder and the checks, atomically;

  • the curves as columns, keyed <AUID or name>@<token> like the live store (S49), each point linked to its frame (Qt’s nearest_light_frame) with the frame’s header airmass and the time difference to its header mid-exposure;

  • the S35/S52 “check your old files” flags from the run’s flight recorder, and the X3 site check on the frame headers (a wrong Settings site makes the CSV airmass wrong; the header AIRMASS, from the mount, stays right);

  • the CSV import of AnalyzeScreen._open_lightcurve (analyze_page.py: 726-772) with a 422 instead of a silent return or a KeyError crash;

  • the live run’s curves in the same shape (D3, read-only).

Nothing is ever written into a session or a CSV.

class argos.server.review.CurveSetData(source: dict[str, ~typing.Any], object_name: str | None, root: ~pathlib.Path | None, targets: ~argos.core.catalog.targets.TargetSet | None, curves: list[~argos.server.review.ReviewCurveData], problems: list[str] = <factory>, airmass_source: str = 'csv', revision: str = '', airmass_column: str = 'csv', rules: ~typing.Any = None)[source]

Bases: object

The curves of one source (protocol.md CurveSet) as Python objects.

airmass_column: str = 'csv'

the CSV’s, or each Argos frame’s header AIRMASS (S66; points without one keep the CSV’s, old_file_rules).

Type:

What the airmass column holds

rules: Any = None

The core’s OldFileRules (S66, S67) applied to these curves, or None.

argos.server.review.EXTRA_COLUMNS = ('frame', 'frame_dt_s', 'header_airmass', 'zero_point', 'zp_rms', 'snr', 'flags')

Columns added beside the CSV’s (protocol.md “Curves”).

argos.server.review.FAINT_ENSEMBLE_SNR = 10.0

the ensemble is faint when its comparisons’ median SNR (each comparison’s median over the run, then the median of those) is below this; the zero point is then noisy.

Type:

S71

class argos.server.review.FrameHeader(date_obs: 'str | None' = None, mid: 'datetime | None' = None, jd_mid: 'float | None' = None, airmass: 'float | None' = None, altitude: 'float | None' = None, azimuth: 'float | None' = None, ra_hours: 'float | None' = None, dec_deg: 'float | None' = None, site_lat: 'float | None' = None, site_lon: 'float | None' = None, software: 'str | None' = None, width: 'int | None' = None, height: 'int | None' = None, bayer: 'str | None' = None, ccd_temp: 'float | None' = None, pointing: 'Any' = None)[source]

Bases: object

pointing: Any = None

The core’s FramePointing of this header (S66), None before the merge.

argos.server.review.LOW_SNR = 3.0

The release’s rule for S35 / S52 points (notes/release_0_5_0.md, “Check your old files”): a target’s SNR below this, or its zero point this far from the run’s median.

argos.server.review.MIN_ANCHORS = 3

a sub on which fewer than this many comparison or check stars reached SNR ANCHOR_SNR unsaturated was measured through a lock nothing verified (“treat that sub’s rows as suspect”; conservative, display only).

Type:

The release’s S56 rule for old files

argos.server.review.NO_FRAME_S = 60.0

A point farther than this from every logged light frame has no frame (s).

argos.server.review.POINT_COLUMNS = ('jd_utc', 'bjd_tdb', 'mag', 'mag_err', 'formal_mag_err', 'sigma_syst', 'airmass', 'fwhm', 'sky_adu', 'comps_used', 'relative_flux', 'relative_flux_err', 'relative_comps_used', 'saturated', 'suspect')

The CSV columns, LcPoint’s fields (lightcurve.py:16-32).

class argos.server.review.RecorderFrame(jd: 'float', number: 'int', stars: 'list[dict[str, Any]]'=<factory>, ensemble: 'list[dict[str, Any]]'=<factory>, flags: 'list[str]' = <factory>)[source]

Bases: object

class argos.server.review.ReviewCurveData(key: str, identity: str, lc: LightCurve, role_source: str, filter: str, filter_source: str | None, csv: Path | None = None, problem: str | None = None, mags: dict[str, float]=<factory>, frame: list[int | None] = <factory>, frame_dt_s: list[float | None] = <factory>, header_airmass: list[float | None] = <factory>, zero_point: list[float | None] = <factory>, zp_rms: list[float | None] = <factory>, snr: list[float | None] = <factory>, flags: list[list[str]] = <factory>)[source]

Bases: object

One curve of a source: the core object as loaded, and what Review adds.

class argos.server.review.ReviewService(hub: Hub)[source]

Bases: object

Sessions opened for review (cached), scans and imports (rows A67-A70).

curve_set(source: dict[str, Any]) → CurveSetData[source]

The curves of a Source as Python objects (protocol.md “Sources”).

static open_summary(data: SessionData) → dict[str, Any][source]

The session_open job’s result: what identifies the open, not the record.

A job’s result travels in every job event and GET /api/jobs listing (4.7 MB for a 6000-frame session, W7 technical review): the record itself is read with GET /api/review/session from the cache this open filled.

class argos.server.review.SessionData(root: Path, stamp: tuple, record: dict[str, Any], curves: CurveSetData)[source]

Bases: object

One opened session: the record and the curves (protocol.md ReviewSession).

argos.server.review.apply_rules(curves: list[ReviewCurveData], rules: Any) → None[source]

After the core’s rules: the no_detection display flag on the points they flagged.

argos.server.review.comparison_median_snr(frames: list[RecorderFrame]) → float | None[source]

S71: the median over the comparisons of each one’s median SNR in the recorder.

None without a recorded comparison SNR. Saturated records are left out: they never enter the ensemble.

argos.server.review.core_review() → ModuleType[source]

argos/core/session/review.py, loaded without its PyQt6 package __init__.

argos.server.review.core_rules() → ModuleType | None[source]

GUARD (S66, S67): the core reader once it has the old-file rules, else None.

apply_old_file_rules (release/0.5.0: each Argos frame’s header AIRMASS unless its pointing is frozen, the flight recorder’s no-detection points flagged suspect per target, sigma_syst recomputed, the comparisons’ median SNR) reaches this tree with the merge; until then Review flags those points without changing them, as before.

argos.server.review.first_light_site_check(root: Path, frames: list[dict[str, Any]]) → dict[str, Any] | None[source]

X3 on the first light frame’s header only (the session list: one header read).

argos.server.review.header_site_check(headers: list[FrameHeader]) → dict[str, Any][source]

X3 on the files: the header site’s direction against the mount’s, per light frame.

notes/release_0_5_0.md “Site set but wrong (X3)”: the header ALTITUDE / AZIMUTH come from the mount, SITELAT / SITELONG from Settings; the direction of RA / DEC at DATE-OBS computed for that site more than 5° from the mount’s means the site was wrong (the whole direction: altitudes alone can agree).

argos.server.review.identify_file(path: Path, targets: TargetSet) → tuple[list[tuple[str, LightCurve, str, str | None]], list[str]][source]

identify_curve_file (review.py:215-256) with each role’s origin.

Returns (identity, curve, role_source, problem) per curve and the core’s problem lines. role_source: column for a multi-curve export (role and star in its columns), else the one-star file’s prefix (role from the file name), targets (role from the matched star) or default (neither: a target by default, never exportable). Raises OSError / ValueError / KeyError / csv.Error for an unreadable file.

argos.server.review.import_csv(path: Path) → CurveSetData[source]

AnalyzeScreen._open_lightcurve (analyze_page.py:726-772) without the window.

argos.server.review.live_curve_set(hub: Hub) → CurveSetData[source]

The live store as a CurveSet: copies, so a later point never changes them.

argos.server.review.nearest_light_index(light: list[tuple[int, Any]], jd_utc: float) → int | None[source]

ReviewedSession.nearest_light_frame (review.py:88-99), as a frame index.

argos.server.review.open_session(root: Path, ctx: JobContext | None = None) → SessionData[source]

Read a whole session (session_open); ApiError / JobCancelled only.

argos.server.review.read_frame_header(path: Path) → FrameHeader | None[source]

The primary header fields Review uses, or None for an unreadable file.

argos.server.review.read_recorder(path: Path) → list[RecorderFrame][source]

The frame records of a flight recorder with their stars and ensembles.

Records of one frame: its star records (written while measuring), then the frame record, then its ensemble records (acquisition_engine.py:2141- 2172). The frame number restarts with a new series, so stars attach to the next frame record of their number and ensembles to the last one.

argos.server.review.recorder_counts(root: Path) → dict[str, int][source]

The session list’s cheap readiness lines from the run’s flight recorder.

Frames the open’s rules flag for the target (A69): flagged (target SNR below 3 or a zero point more than 1 mag off) and unverified (S56: fewer than 3 anchors at SNR 10, and not already flagged), so R0’s Issues agree with R1’s badge.

argos.server.review.rules_record(rules: Any) → dict[str, Any] | None[source]

The core’s OldFileRules on the wire (protocol.md CurveSet), or None.

argos.server.review.target_set_of_curve(csv_path: Path) → TargetSet | None[source]

_target_set_of_curve (analyze_page.py:786-806), Qt-free.

HTTP routes of Review’s sessions, curves and frames (rows A67-A75, protocol.md “Review (wave 7): sessions, curves, frames”).

add_routes() registers them on the token-protected /api router and gives the hub its two services (hub.review, hub.files) when it has none.

class argos.server.review_routes.MeasureStarBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.review_routes.PathBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

argos.server.review_routes.add_routes(api: APIRouter, hub: Hub) → None[source]

Register rows A67-A75 on api (the /api router).

Review’s frame inspector on files (rows A71-A75): pixels, header, measure, solve, catalogue.

Qt-free ports of the Frame Viewer (argos/ui/analysis_window.py) over the unchanged core and the wave 4 server ports, for any FITS file the observer may browse; nothing is published on /ws/frames (the live image stays) and no file is written.

  • A71 FileService.frame_bytes(): load_fits_frame (the v1 Open FITS display conversions) encoded in the /ws/frames layout (frames.py).

  • A72 FileService.header(): read_fits_header_text and read_fits_meta (analysis_window.py:68-133).

  • A73 FileService.measure(): measure_star_at (metrics.py:225-276) on the array of read_fits_2d (analysis_window.py:54-65), the Frame Viewer’s click (_on_star_clicked / _remeasure_selection, analysis_window.py:874-899) through FrameMeasurer (identical numbers, the green plane and sky computed once per file).

  • A74 FileService.start_solve(): _on_solve / _on_solved (analysis_window.py:460-505) with build_solve_settings(live=False), wcs_from_result, overlay_for; ASTAP through field_solve.solve_green (killed on cancel).

  • A75 FileService.start_catalogue(): _fetch_field_catalogues (analysis_window.py:588-629) with field_catalog.run_request and the Observe projection project_field.

class argos.server.files.FileService(hub: Hub)[source]

Bases: object

Frame-inspector tools on files (rows A71-A75); thread-safe.

catalog_api: Any

The catalogue query functions (argos.core.catalog; tests replace them).

class argos.server.files.FileSolution(stamp: 'tuple[int, int] | None', wcs: 'Any', green_shape: 'tuple[int, int]', record: 'dict[str, Any]')[source]

Bases: object

argos.server.files.META_KEYS = ('OBJECT', 'DATE-OBS', 'EXPTIME', 'EXPOSURE', 'IMAGETYP', 'FILTER', 'GAIN', 'INSTRUME', 'OBSERVER', 'SITENAME', 'CRPIX1', 'CRPIX2', 'CRVAL1', 'CRVAL2', 'CD1_1', 'CD2_2', 'CCD-TEMP', 'HFD', 'FWHM', 'NSTARS', 'SKYLEVEL', 'PEAKADU', 'ECCENT', 'EGAIN', 'RDNOISE', 'AIRMASS', 'MOONSEP', 'FRAME', 'FRAMENO', 'IMGNUM', 'NFRAMES', 'SEQUENCE', 'ORIGIN')

Keywords of read_fits_meta (analysis_window.py:68-123), in its order.

argos.server.files.header_text(header) → str[source]

The header one card per line, END last (Qt showed str(header): the same cards run together on one line).

argos.server.files.read_fits_2d(path: Path) → ndarray | None[source]

read_fits_2d (analysis_window.py:54-65): float32, NaN zeroed, a cube averaged.

The first image HDU, chosen from the headers and its size checked before the pixels are read (touching .data loads them: a 17 000 px frame cost 400 MB before it was refused, W7 technical review), as fits_source.load_fits_frame.

argos.server.files.read_fits_meta(header) → dict[str, str][source]

read_fits_meta (analysis_window.py:68-123) on a read header.

argos.server.files.read_primary_header(path: Path)[source]

The primary header, or FitsReadError.

argos.server.files.to_counts(arr: ndarray) → tuple[ndarray, bool][source]

A calibrated float frame in [0, 1] (Siril, PixInsight) scaled by 65535.

As the display (fits_source._to_uint16) and the Frame Viewer (S65) do, so a measurement reads counts (an unscaled one gave SNR 0, peak 0) and ASTAP sees a visible plane. Returns the array and whether it was scaled.

AAVSO and CSV exports (rows A77-A79 of web/spec/README.md §4.3).

The files are written by the fixed core writers themselves, never by a re-implementation: write_aavso and write_curves_csv (argos/core/photometry/lightcurve.py), on the very LightCurve objects the Review plot shows (hub.review.curve_set(source), rows A68-A70), driven as Qt’s Review drives them: Analyze Open curve CSV (analyze_page.py:737-783) hands the curves, observer.obscode, photometry.default_band and the target set to the Photometry window, whose Export AAVSO (photometry_window.py:362-418) and Export measurements (:345-360) call the writers.

The guards are Qt 0.5.0’s (S10 unidentified curves, S11 observer code and flagged points, S53 one filter per report) plus S60 (no undated row) and S61 (one filter per CSV), with the preview the dialog shows (Q-R2, Q-R3).

class argos.server.exports.AavsoArgs(obscode: 'str', band: 'str', chart: 'str | None')[source]

Bases: object

argos.server.exports.EXCLUDED_KEYS = ('saturated', 'no_detection', 'suspect', 'nonfinite', 'undated')

The left-out counts of a report, in write_aavso’s order.

class argos.server.exports.ExportService(hub: Hub)[source]

Bases: object

POST /api/export/aavso/preview, /api/export/aavso, /api/export/csv.

export_aavso(body: dict[str, Any]) → dict[str, Any][source]

POST /api/export/aavso (A78): refusals at once (409), then the export job.

export_csv(body: dict[str, Any]) → dict[str, Any][source]

POST /api/export/csv (A79): write_curves_csv over the selected curves.

preview(body: dict[str, Any]) → dict[str, Any][source]

POST /api/export/aavso/preview (A77): the same call, into a scratch file.

argos.server.exports.MIN_AAVSO_JD = 2400000.0

a point dated before this is undated (a pre-0.5.0 batch re-run wrote JD 0 for a frame without DATE-OBS, S13). The fixed core skips such points itself (AavsoExportSummary.undated_excluded); before S60 reaches this tree the server leaves them out before calling the writer, which then writes the same file.

Type:

GUARD (S60)

class argos.server.exports.Selection(data: ~typing.Any, filter: str | None, filters: list[str], curves: list[~typing.Any] = <factory>, check: ~typing.Any = None, refusal: dict[str, ~typing.Any] | None = None)[source]

Bases: object

What one export reads from a curve set.

argos.server.exports.band_note(band: str, token: str | None) → str | None[source]

S11: a warning when FILT does not fit the frames’ filter (the export is allowed).

argos.server.exports.obscode_is_set(code: str) → bool[source]

Q-R2 / S11: empty or Qt’s XXX placeholder is no observer code.

argos.server.exports.plural(n: int, word: str, many: str | None = None) → str[source]

"1 point", "2 points": the W7 strings say the count once, in words.

argos.server.exports.protected_reason(path: Path, sources: list[Path]) → str | None[source]

Why path must not be overwritten by an export, or None.

The export’s own source files, and inside an Argos session (a folder holding session.json) its data folders, re-run folders and record files.

argos.server.exports.recorder_flagged(curve, codes: tuple[str, ...] = _RECORDER_FLAGS) → list[int][source]

Indices of curve’s points that would be rows but the flight recorder flags.

Once the core applies S67 (the merge), a no-detection frame’s points are suspect and left out, so none remains here; the S56 few_anchors points stay written, with the preview’s warning pointing to a re-run (S58).

argos.server.exports.select_for_aavso(data, body: dict[str, Any]) → Selection[source]

The target curves and the check curve one AAVSO report covers, or a refusal.

argos.server.exports.select_for_csv(data, body: dict[str, Any]) → Selection[source]

The curves of one CSV export (every curve with points), or a refusal.

argos.server.exports.undated(point) → bool[source]

S60: a point without a usable date (JD 0 from a pre-0.5.0 batch re-run).

argos.server.exports.write_report(path: Path, sel: Selection, args: AavsoArgs)[source]

write_aavso exactly as Qt’s Export AAVSO calls it: the curves, then the check.

HTTP routes of Review’s exports and re-run (rows A76-A79, protocol.md “Review (wave 7): exports and re-run”).

add_routes() registers them on the token-protected /api router and gives the hub its two services (hub.exports, hub.rerun) when it has none.

class argos.server.export_routes.AavsoBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.export_routes.AavsoExportBody(*args: Any, **kwargs: Any)[source]

Bases: AavsoBody

class argos.server.export_routes.CsvExportBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.export_routes.RerunBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

class argos.server.export_routes.SourceBody(*args: Any, **kwargs: Any)[source]

Bases: _Body

argos.server.export_routes.add_routes(api: APIRouter, hub: Hub) → None[source]

Register rows A76-A79 on api (the /api router).

Re-run photometry over a session’s saved frames (row A76 of web/spec/README.md §4.3).

A Qt-free port of the fixed PhotometryBatchWorker (argos/workers/photometry_batch_worker.py, release 0.5.0 with S12, S13, S41, S43, S49, S58, S62 and S63), whose QThread cannot be imported here (tests/server/test_no_qt.py). BatchRun is the worker’s run line for line: the signals become callbacks, the cancel flag the job’s event, and the S43/S58 re-solves go through the cancellable ASTAP runner (argos.server.field_solve.solve_green(), which kills ASTAP on a cancel; Qt’s solve_array could not be interrupted). The measurement is the unchanged core: measure_frame, ApertureTracker, TrackedWCS, anchors_seen, select_tracking_anchors, estimate_systematic_floor, airmass_at, bjd_tdb, LightCurve.to_csv.

What the web adds around it (D2, Q-R1): the reference is a plate solve of a session frame (or the live solution), the frames are the session’s, and the output is always a new folder inside the session, never overwritten.

class argos.server.rerun.BatchRequest(fits_paths: list[~pathlib.Path], wcs: object, target_set: ~argos.core.catalog.targets.TargetSet, params: ~argos.core.photometry.params.PhotometryParams, out_dir: ~pathlib.Path, object_name: str = 'untitled', site: tuple[float | None, float | None, float] = (None, None, 0.0), diagnostics: bool = True, egain_table: dict = <factory>, solver: ~collections.abc.Callable[[~numpy.ndarray], object] | None = None, proper_motions: ~collections.abc.Callable[[~argos.core.catalog.targets.TargetSet], list] | None = None)[source]

Bases: object

BatchRequest: inputs for one re-run.

proper_motions: Callable[[TargetSet], list] | None = None

Gaia DR3 sources around the set, called once when a VSX/VSP star has no proper motion (GUARD: a core without TargetSet.backfill_proper_motions never calls it).

Type:

S77 (release BatchRequest.proper_motions)

class argos.server.rerun.BatchResult(curves: dict[str, ~argos.core.photometry.lightcurve.LightCurve]=<factory>, frames_done: int = 0, error: str = '', rotation_deg: float = 0.0, shift_px: float = 0.0, frames_skipped: int = 0, cancelled: bool = False, out_dir: Path | None = None, frames_resolved: int = 0, frames_unanchored: int = 0, frames_unverified: int = 0, check_rms: dict[str, tuple[float, int]]=<factory>, series_fwhm: float | None = None, frames_header_airmass: int = 0, frames_site_wrong: int = 0, frames_rotation_solved: int = 0, stars_off_centre: int = 0, frames_no_target_point: int = 0, frames_rotation_unsolved: int = 0, frames_no_detection: int = 0)[source]

Bases: object

BatchResult.

check_rms: dict[str, tuple[float, int]]

the check stars’ RMS per curve key.

Type:

Not in Qt’s record (logged there)

frames_header_airmass: int = 0

frames whose airmass is their FITS header AIRMASS (the mount’s), and frames whose header shows the Settings site more than 5° wrong (X3, a warning).

Type:

S66

frames_no_detection: int = 0

frames with no detection (a target below SNR 3, or its zero point more than 1 mag from its median over the run): their points flagged suspect.

Type:

S67

frames_no_target_point: int = 0

frames whose target got no point (every comparison off-centre).

Type:

S69 (b)

frames_rotation_solved: int = 0

frames re-solved because the field turned more than 2° since the solution.

Type:

S69 (a)

frames_rotation_unsolved: int = 0

the apertures followed the tracker.

Type:

S69 (a)

Type:

re-solves for rotation that failed

stars_off_centre: int = 0

comparison/check measurements more than 1 px from their aperture centre, left out of their frame’s ensemble (their rows suspect).

Type:

S69 (b)

class argos.server.rerun.BatchRun(request: BatchRequest, *, cancel: Event | None = None, progress: Callable[[int, int, str], None] | None = None)[source]

Bases: object

PhotometryBatchWorker.run without Qt: call run() on a worker thread.

progress(done, total, name) replaces the progress signal (name: the frame just handled); cancel is checked at every frame boundary.

class argos.server.rerun.FrameSelection(paths: list[Path], calibration: int = 0, other_object: int = 0, outside_lights: int = 0, duplicates: int = 0)[source]

Bases: object

The frames a re-run measures, and what it left out.

outside_lights: int = 0

FITS of a session folder outside its lights/ (another program’s), links to a frame already listed.

Type:

S63

class argos.server.rerun.RerunService(hub: Hub)[source]

Bases: object

POST /api/review/rerun (A76) and its plan.

plan(body: dict[str, Any]) → dict[str, Any][source]

POST /api/review/rerun/plan: what a start now would do; never writes.

start(body: dict[str, Any]) → dict[str, Any][source]

POST /api/review/rerun (A76): refusals at once, then the rerun job.

argos.server.rerun.SIMBAD_PREFIXES = ('v*', '*', '**', 'name', 'cl*', 'em*', 'v*?', '*?', '**?')

SIMBAD’s identifier prefixes (“V* XX Cyg”).

Type:

S82 (release _SIMBAD_PREFIXES)

argos.server.rerun.call_with_cancel(lookup, tset, cancel)[source]

S77 (release call_with_cancel): lookup(tset), passing cancel (a callable, true to stop) when the lookup takes it (GUARD: the merged core’s gaia_sources_for_set).

argos.server.rerun.discover_light_frames(folder: Path, object_name: str | None = None) → FrameSelection[source]

discover_light_frames (0.5.0 with S62, S63): the light frames of the object.

.fit/.fits/.fts files (any case) in the folder itself, or in its subfolders when it has none (a session root holds lights/). Frames whose IMAGETYP names a calibration type are left out, and (S62) frames whose OBJECT names another object than object_name; a frame without either card is kept. In the subfolder search an Argos session folder’s frames are its lights/ only, and a link to a frame already listed is that frame (S63: Siril’s process/ holds links to the lights and registered copies). Ordered by DATE-OBS, undated frames last, by name.

argos.server.rerun.object_key(name: str | None) → str[source]

An object name compared without case, spaces or underscores (S62), nor a SIMBAD identifier prefix (S82, release _object_key: an OBJECT of “V* XX Cyg” is XX Cyg).

argos.server.rerun.rerun_output_dir(frames_folder: Path, now: datetime) → Path[source]

rerun_output_dir: <session>/photometry_rerun_<UTC>, never an existing folder.

The session root is the folder holding session.json (frames_folder or its parent), else frames_folder itself. A folder of that second that exists already gets -2, -3… (the web can start two re-runs of two sessions in one second; Qt ran one at a time).

Desktop

What only the desktop app uses: shutdown, reveal in the file manager, the end of the shell’s stdin.

The desktop app’s server half (wave 8): shutdown (A7), reveal (A12), the shell’s stdin.

  • busy_items() says what a quit would stop (P39: the Qt app stopped a sequence silently, acquisition_engine.py:1621-1622).

  • ShutdownService runs POST /api/app/shutdown: refused with what while something is busy unless forced, then Hub.shutdown with one shutdown event per stage (port of Shell.closeEvent, shell.py:611-625), then the process exits within a bounded budget.

  • Revealer shows a file in the OS file manager, only for a server the desktop shell started (--desktop).

  • watch_stdin_eof() (--exit-on-stdin-eof): when the shell’s pipe closes, however the shell ended, the server takes its SIGTERM path.

protocol.md “Desktop app (wave 8)” is the contract.

argos.server.desktop.OVERRUN_EXIT_STATUS = 70

Exit status of a server that overran SHUTDOWN_BUDGET_S.

class argos.server.desktop.Revealer(hub: Hub, settings: Settings)[source]

Bases: object

POST /api/fs/reveal (row A12): desktop app only, allowed roots only.

run: Callable[[list[str]], tuple[int | None, str]]

The command runner and the platform (tests replace them).

argos.server.desktop.Runner

(exit status or None while it still runs, stderr text).

Type:

Runs one command

alias of Callable[[list[str]], tuple[int | None, str]]

argos.server.desktop.SHUTDOWN_BUDGET_S = 60.0

a CLI server still in its stages after this ends its process at once (protocol.md “Shutdown (A7)”).

Type:

The whole shutdown’s bound

argos.server.desktop.STAGES: tuple[tuple[str, str], ...] = (('sequence', 'Stopping the sequence'), ('services', 'Stopping background tasks'), ('devices', 'Closing the equipment connections'), ('files', 'Finishing file writes'), ('exit', 'Stopping the ARGOS server'))

(id, label) in the order Hub.shutdown runs them; exit is last.

class argos.server.desktop.ShutdownService(hub: Hub)[source]

Bases: object

POST /api/app/shutdown (row A7): refusal, stages, the exit.

request_exit is set by the CLI (uvicorn’s should_exit); without it (in-process tests) the stages run and the process stays. A CLI server still in its stages after SHUTDOWN_BUDGET_S ends at once: hard_exit is os._exit only when the CLI sets it, so an in-process server (tests) only logs the overrun.

property closing: bool

A shutdown was accepted (other changing requests are refused).

request(force: bool = False) → dict[str, Any][source]

Start the shutdown, or 409 busy with what; idempotent once started.

wait(timeout: float | None = None) → bool[source]

Until every stage ran (tests).

argos.server.desktop.WRITE_JOBS = frozenset({'export', 'rerun', 'support_bundle'})

a quit would cut what they write.

Type:

Jobs that write files

argos.server.desktop.busy_items(hub: Hub) → list[dict[str, Any]][source]

What a quit would stop now, in the order of protocol.md’s table.

argos.server.desktop.reveal_commands(path: Path, platform: str | None = None) → list[tuple[str, list[str]]][source]

(method, argv) to try in order for path on platform.

argos.server.desktop.run_command(argv: list[str], timeout_s: float = _REVEAL_WAIT_S) → tuple[int | None, str][source]

Start argv, wait up to timeout_s for its answer; a slow one is reaped later.

argos.server.desktop.watch_stdin_eof(fd: int = 0, *, ready: Callable[[], bool] = _signal_handlers_installed, kill: Callable[[int, int], None] = os.kill, poll_s: float = 0.05) → Thread[source]

Read fd until end of file, then SIGTERM this process (the graceful path).

The signal waits until ready (uvicorn’s handlers installed), so an end of file during start-up still takes the graceful path.