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 0lets the OS pick one (the Tauri sidecar reads the actual port from theARGOS_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:
objectRuntime 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.Nonekeeps 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);Noneskips the pre-check.network_interval_s – Period of the Seestar reachability probe;
0turns 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 –
IsMovingpoll period during autofocus (autofocus_worker.py:45: 0.3 s).desktop – Started by the desktop shell (
--desktop, wave 8): AppInfodesktopandPOST /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:
objectKnobs 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.
- 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).
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:
_BodyWave 6b: who acknowledged (the client’s label).
- class argos.server.app.CalibrationPlanBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyWave 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:
_BodyA23: v1’s
{exposure_s, gain}stays valid; both now default to the settings.
- class argos.server.app.CaptureSettingsBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyA22: one commit; the camera’s own limits are checked by the hub (never clamped).
- class argos.server.app.DeviceConnectBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyAPI 2: one device or all of them; the address defaults to the config’s.
- class argos.server.app.FieldSolveBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyPOST /api/field/solve: no option today (strict: unknown fields refused).
- 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:
_BodyWave 6a: Park / Unpark with “Pause the run and slew”.
- class argos.server.app.RevealBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyPOST /api/fs/reveal(wave 8, A12).
- class argos.server.app.SequenceStartBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyWave 6a (A62): absent = the draft’s start time; null = now.
- class argos.server.app.ShutdownBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyPOST /api/app/shutdown(wave 8, A7).
- class argos.server.app.SiteSearchBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyA82: 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:
_BodyA19: both default to the config (
stellarium.host,stellarium.port).
- class argos.server.app.SupportBundleBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_BodyA5: where to write the ZIP (
null= keep it for a download) and what goes in.
- 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/eventsframe: strict JSON, as REST answers.JSON.parserejectsNaN; one bad float must never make the browser drop a snapshot, so non-finite numbers go out asnull(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 butGET /api/healthrequires — asAuthorization: Bearerover HTTP, as?token=on WebSockets, because browsers cannot set WebSocket headers;an origin allow-list: CORS for HTTP, and an explicit
Origincheck on WebSockets, which CORS does not cover;a
Hostallow-list (loopback names only, when the server is bound to loopback) and a refusal of any HTTP request whoseOriginis 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. ItsHost(andOrigin) 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:
objectConstant-time comparison against the launch 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
Hostheader, 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.origin_allowed(origin: str | None) bool[source]¶
True when origin may talk to the server.
A missing
Originheader 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:
ExceptionAn 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-Authenticatefor a 401).
- details¶
fieldsfor a config commit,ownerfor 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:
objectAnswer 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- exposure_s: float = 2.0¶
the frame being exposed (
current) while one is, else the settings.- Type:
v1
- 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
- class argos.server.state.SensorInfo(width: 'int', height: 'int', bitpix: 'int' = 16, bayer: 'str | None' = None)[source]¶
Bases:
object
- argos.server.state.utc_iso(when: datetime | None = None) str[source]¶
ISO 8601 UTC with millisecond precision and a
Zsuffix.
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 (
connectingbeforeconnected,exposingbeforeidle…). PastEVENT_BACKLOGpending messages it is compacted: only the newest snapshot of each kind survives (status,camera,mount,devices,network,activity,config, andjob:<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:
objectFan-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).
- publish(kind: str, seq: int | None, payload: dict[str, Any]) None[source]¶
Queue one JSON event (a snapshot kind with its seq, or
log).
- 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
statussnapshot, 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
seqit 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:
objectOne
/ws/eventsclient’s pending messages (loop thread only).- dropped¶
Messages discarded by compaction (diagnostics).
- class argos.server.events.FrameSubscriber[source]¶
Bases:
objectOne
/ws/framesclient: a single latest-frame-wins slot (loop thread only).- 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
loglines are dropped first, then the oldest of the wave 3 and 5 streams; each stream carries its ownseqso 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/framesbinary 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’spath/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/meanover every sample of pixels.pixels must be uint16 (any shape; colour channels are pooled).
madis 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:
POSTon the domain route starts it and answers202 {"job_id"}; a second job of the same kind on the same resource is409 busywithowner= the running job’s id;progress is published as
{"type": "job", "job": {...}}events, at most everyMIN_PUBLISH_INTERVAL_Sper 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 raisingJobCancelled(JobContext.check()) and the job endscancelled;finished jobs are kept
KEEP_Sseconds forGET /api/jobs/{id};GET /api/jobslists the active ones and the lastKEEP_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:
ExceptionRaised inside a job function to end it as
cancelled.
- class argos.server.jobs.JobContext(manager: JobManager, job: _Job)[source]¶
Bases:
objectWhat a job function receives: progress reporting and the cancel flag.
- check() None[source]¶
Raise
JobCancelledif 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:
objectStarts, tracks, publishes and cancels jobs; thread-safe.
- 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).
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
levelfilter ofGET /api/logs.
- argos.server.logbook.LOG_HISTORY = 200¶
Lines replayed to a
/ws/eventsclient right after its firststatus.
- argos.server.logbook.LOG_RING = 5000¶
Lines kept for
GET /api/logs.
- class argos.server.logbook.LogBook(capacity: int = LOG_RING)[source]¶
Bases:
objectThread-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
logevent payload.
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:
FilterKeep the bearer token out of logs (uvicorn logs WebSocket URLs with
?token=).
- argos.server.runtime.add_file_log(directory: Path, formatter: Formatter) Path | None[source]¶
Rotating
argos.login directory, asconfigure_local_logging.support_bundle.configure_local_loggingcannot 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_pathsand_apply_local_data_paths(configuration_page.py:1040-1084): same targets, sameexpanduser; nothing is created or read here.
- argos.server.runtime.apply_log_level(level: Any) None[source]¶
ui.log_levelfor 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).
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; aftermount_lost_afterconsecutive 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:
objectOwns 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): logseqnumbers start again at 1 in a new process, so a client that sees another id knows its lines come from a restarted server.
- 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 withsave.
- 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/eventssocket opened with?client=closed: stop its jog.
- client_message(client: str | None, message: Any) None[source]¶
A text message from a
/ws/eventsclient; onlyjog_stopis 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
connectingwithinfo: "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_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/eventsclient gets right afterstatus.
- 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/eventsclient.
- 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 injog.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_activewhile a sequence is active (the plan half’s lock, Q-P9).
- resolve_link(mode: str, host: str | None, port: int | None) Link[source]¶
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
cmdlog 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 ofapply_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, theshutdownevents ofPOST /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.
- 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.
- start_site_search(query: str) dict[str, Any][source]¶
POST /api/site/search(row A82): a cancellablesite_searchjob.
- 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): asupport_bundlejob (not cancellable).
- status_event() tuple[int, dict[str, Any]][source]¶
The current
statusevent 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 ofstart_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_failedand 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 ofstop_stellarium(device_session.py:800-806).
- stop_autofocus() dict[str, Any][source]¶
POST /api/autofocus/stop: cancel and return to the start (S23).
- 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 ofPUT /api/camera/settingslimited to these two fields.
- class argos.server.hub.Link(mode: Literal['simulator', 'alpaca'], host: str | None = None, port: int | None = None)[source]¶
Bases:
objectWhere devices are connected: the simulator, or one Alpaca server.
- argos.server.hub.QUEUED = 'queued'¶
infoof 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:
ProtocolA filter wheel or a focuser, as the device table describes it.
- class argos.server.devices.base.CameraDevice(*args, **kwargs)[source]¶
Bases:
Protocol- 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
ExposureCancelledonce cancel is set. on_start is called right beforeStartExposure(the frame’sDATE-OBS, asexposure_worker.py:160), on_readout whenImageReadyturns true, before the download (the end of the exposure). light is the ASCOMLightflag: 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:
ProtocolOptional camera features (
AlpacaCamera,SimCamera).
- 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:
objectThe driver’s ranges, read at connect (
camera.py:70-133).
- argos.server.devices.base.ConnectReport¶
(level, message)lines a device reports right after it connected; the hub logs them, and keeps thewarning/errorones as the device’swarnings. Adapters expose them as an optionalconnect_report().
- exception argos.server.devices.base.DeviceError[source]¶
Bases:
ExceptionA device refused a command or stopped answering.
- exception argos.server.devices.base.ExposureCancelled[source]¶
Bases:
ExceptionThe exposure was aborted through its cancel event.
- class argos.server.devices.base.FilterWheelDevice(*args, **kwargs)[source]¶
Bases:
ProtocolA filter wheel (
argos.core.alpaca.filterwheel.FilterWheel).
- class argos.server.devices.base.FocuserDevice(*args, **kwargs)[source]¶
Bases:
ProtocolA focuser (
argos.core.alpaca.focuser.Focuser).
- class argos.server.devices.base.MountExtras(*args, **kwargs)[source]¶
Bases:
ProtocolOptional mount features (wave 3, rows A29-A31).
- exception argos.server.devices.base.MountParked[source]¶
Bases:
DeviceErrorThe 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:
objectOne 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:
objectImplements
CameraDevice.
- class argos.server.devices.alpaca.AlpacaFilterWheel(host: str, port: int)[source]¶
Bases:
objectImplements
FilterWheelDevice(device_session.py:430-448; moves:85-122, 681-701).
- class argos.server.devices.alpaca.AlpacaFocuser(host: str, port: int)[source]¶
Bases:
objectImplements
FocuserDevice(device_session.py:460-488; moves:705-739).
- class argos.server.devices.alpaca.AlpacaMount(host: str, port: int)[source]¶
Bases:
objectImplements
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), orNonewhen it does not expose one; read once here, at connect time, on the connecting thread (the site check compares it, wave 2).
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:
objectImplements
CameraDevice.- drift(index: int) tuple[float, float][source]¶
Pointing offset (px) of frame index: slow periodic wander + jitter.
- 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, likeTelescope.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) —
MoveAxismoves the primary axis (RA, positive east) and the secondary axis (Dec, positive north) at up toMAX_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:
objectImplements
MountDevice.- alignment = 'eq_gem'¶
a German equatorial model.
- Type:
ASCOM AlignmentMode (wave 3)
- 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).
- 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_sper slot) and reads position −1 meanwhile, asFilterWheel.get_positiondoes on a Seestar (filterwheel.py:88-98);the focuser moves at
SimOptions.focuser_speed_steps_s, reportsIsMoving, stops where it is onHaltand clamps a move to0…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:
objectImplements
FilterWheelDevice.
- 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:
objectImplements
FocuserDevice.
- class argos.server.devices.sim_aux.SimOptics(best_focus: int = 5_300, defocus_scale: float = DEFOCUS_SCALE_STEPS)[source]¶
Bases:
objectWhat 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.
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:
ReplayCamerareturns, exposure after exposure, the pixels of the folder’s FITS files in file-name order (raw 16-bit, the Open FITS rule ofload_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.ReplayMountis the simulated mount, started unparked and tracking, whose readings carry the pointing of the file being exposed (RA/DECof an ARGOS frame, elseOBJCTRA/OBJCTDEC, andALTITUDE/AZIMUTHwhen 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:
objectImplements
CameraDeviceover 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:
SimMountThe 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:
objectThe folder, its order and the file being exposed (shared by camera and mount).
- 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
RAis in hours (fits_writer); other software writes degrees, so for them only the sexagesimalOBJCTRA/OBJCTDECare 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:
objectThe network operations of one search; tests replace them with fakes.
- argos.server.discovery.NAME_TIMEOUT_S = 1.0¶
Timeout of the
ServerNameread 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]¶
ServerNamefrom the Alpaca management API, orNone.
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 asnetwork_monitor.py:80-82) is probed with one TCP connect everyCHECK_INTERVAL_S, and at once after the address changes;seestarisNonewhile 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()withinternet=Truedoes it on demand, with the Qt targets and timeout;internetstaysNoneuntil 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:
objectPeriodic Seestar probe plus the on-demand internet check; thread-safe.
- Parameters:
address – Returns the configured
(host, port); host""= none.publish – Called with the
networksnapshot 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.
- 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.overridesthatapply_overrideshonours.
- 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
Profilerecord; overrides lists what was applied (active profile).
- argos.server.profiles.summary(profile: TelescopeProfile) dict[str, Any][source]¶
The
profilefield 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
startwaits for the listening socket (or the bind error).
- argos.server.stellarium.STOP_WAIT_S = 3.0¶
How long
stopwaits 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:
objectOne 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).
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_metafirst, 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:
objectThread-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.
- 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
OSErrororValueErrorwhen 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:
ValueErrorA 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.
- 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.mdappendix A that are deliberately not exposed, with the reason (ConfigSnapshot.omitted). WithMETAthis 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
InvalidValuewith 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) onfind_astap/find_astap_db/_database_args(platesolve.py:119-144, 305-319), with the database choice ofastrometry_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/*.csvof 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,66andexoplanets.py:37,91(SHA-256 hex.jsoninsimbad/andnasa/).- 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
- 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:
ExceptionNo usable answer from the network (job error
lookup_failed).
- exception argos.server.settings_helpers.PlaceNotFound[source]¶
Bases:
ExceptionThe 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()andangle_between_directions()areargos.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()isargos.core.config.observing_site(config.py:277-297, X2) behind a getter adapter (the store passesget);SiteCheckfollowsDeviceSession._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:
objectThe site check of the connected mount; thread-safe.
The hub calls
mount_connected(),mount_disconnected(),on_reading()(every successful poll),site_changed()andcheck_now(). announce is called (no argument, no lock of this object held) after every change: the hub readsrecord()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.
- 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), orNone(X2).argos.core.config.observing_siteon 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:
objectThe 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_pathschange applies at once.- resolve(raw: str | PathLike[str], *, what: str = 'path') tuple[Path, Path][source]¶
(resolved path, its root);400relative,403outside the roots.
- 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.
- 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(seeprotocol.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:
objectCached summaries of the sessions under one root; thread-safe.
- 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 masktoken=(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 asMount 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:
ExceptionThe 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:
objectEvery text that enters the ZIP goes through
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).
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:
FrameSettingsis 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()andfits_exposure_mid()are_raw_aduandfits_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:
objectWhat 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:
objectOne frame’s own settings, snapshotted when its exposure starts (S2).
- argos.server.capture.LogFn¶
(level, message)sink of the save task (the hub’s log, topic camera).
- class argos.server.capture.Pointing(ra_hours: float, dec_deg: float, alt_deg: float | None, az_deg: float | None)[source]¶
Bases:
objectThe mount reading a saved frame records (X1:
Nonewhen 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:
objectEverything the save thread needs; collected when the frame arrives.
- class argos.server.capture.SaveRequest(frame_type: str, live: bool, accepted_utc: str, exposure_s: float | None = None, gain: int | None = None)[source]¶
Bases:
objectA pending Take shot (
_capture_pendingof the Qt engine).
- 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_midofacquisition_engine.py:DATE-AVG, elseDATE-OBS+EXPTIME/2 (EXPOSUREaccepted); a frame of Argos before 0.5.0 always byDATE-OBS+EXPTIME/2 (S39); never guessed.
- argos.server.capture.frame_context(job: SaveJob, filter_name: str, readings: dict[str, Any]) FrameContext[source]¶
The
FrameContextof_save_fits_async(acquisition_engine.py:1811-1873).
- argos.server.capture.image_type(frame_type: str) str[source]¶
FITS
IMAGETYPof 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 (idlewith the refusal asmessage), orerror“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.filterfollow 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:
objectThe 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).
- 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), orNone.
- 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
- 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
MaxStepand never clamped silently (400); a step is clamped to0…MaxStepand the clamp is reported; moves are refused while autofocus owns the focuser, Halt stays accepted;polling (absent in Qt, 05 P4): position and
IsMovingevery 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:
objectThe 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).
- move(position: int) dict[str, Any][source]¶
Go to (
POST /api/focuser/move): refused outside0…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
targetis the last move sent, whoever sent it (the commanded target drawn by the Focuser card).
- 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:
coarse sweep of
num_stepspositions across ±``half_range`` (autofocus_worker.py:117-131);the degenerate-sweep guard: fewer than three valid samples, a flat curve or an edge minimum restore the start and end
rejected(:133-147);four fine samples around the raw minimum, the parabola fitted on them and the coarse minimum (
:149-167);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.exposesets 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/haltduring 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:
objectOne sweep: the thread body and its stop / halt controls.
- 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_sis stopped by the server; so are the axes of a client whose event socket closes or reports a blur ({"type": "jog_stop"});MoveAxisruns 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:
objectPer-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 itsMoveAxis) orignoredwithwhy(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).
- 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.
- 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) anddetect_stars(mean FWHM, eccentricity) ofargos.core.imaging.metrics, the measurements ofPreviewProcessor(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:
objectThe conditions rows of this server process (
seqincreasing).
- 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
- class argos.server.conditions.MetricsWorker(on_result: Callable[[MetricsJob, dict[str, Any]], None])[source]¶
Bases:
objectLatest-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
FrameMetricsrecord 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
OBJECTand its folder, and the catalogue target the Mount card’s Slew uses. A Qt-free port ofImagingPage.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_suggestionsandresolve_nearby_objectsofargos.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:
objectThe 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).
- set_locked(reason: str | None) None[source]¶
Wave 6a: a sequence owns the observation while it runs (
Noneunlocks).
- 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).
- 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
ResolvedObjectas the API’sResolved.
- 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:
ExceptionThe 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:
objectA 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
GAINandEGAIN
- 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_aduandfits_exposure_mid(:103-151): one 2-D image of integer values 0…65535 whatever the stored type, elseFitsReadErrorwith the reason; the epoch isDATE-AVG, elseDATE-OBS+EXPTIME/2, elseNone.
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_solvejob; automatic: a plain thread), running ASTAP throughfield_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:
objectOwns 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).
- 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).
- 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.
- 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_savedusesself._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.
- 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 (releaseAcquisitionEngine._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/eventsclient receives.
- 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.
- 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:
objectThe newest frame the field works on.
- 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.
- 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:
objectThe 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()issolve_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 — withsubprocess.Popeninstead ofsubprocess.runso 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 fromwcs_from_resultand the grid fromoverlay_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:
ExceptionThe 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 (
FrameWcsof protocol.md).A green 0-based pixel
gis frame pixel2g + 0.5; FITS pixels are 1-based, socrpix_frame = 2·(crpix_green − 1) + 0.5 + 1and 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’sGrid(frame px).
- argos.server.field_solve.header_hint(header: Any) tuple[float, float] | None[source]¶
(ra_hours, dec_deg)fromOBJCTRA/OBJCTDEC(sexagesimal), else None.An opened file was taken elsewhere: the mount’s pointing is no hint for it.
RA/DECare 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
SolveCancelledwhen 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
mirroredis for a FITS display (y up). In px, east isCD⁻¹·(1, 0)and northCD⁻¹·(0, 1); an unmirrored view (north up, east left, y down) hasnorth × 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()areCatalogWorker(catalog_worker.py:32-172);build_request()is the request half ofmaybe_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 withb_minus_vandneighbours_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:
objectA 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:
objectOutcome of a
CatalogRequest(catalog_worker.py:57-79).
- 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:
objectWhat 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:
objectFieldLayerscontent 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 − Vof a comparison star,Noneunless 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
CatalogRequestofmaybe_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 pxgx/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_limitwithin 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_MAGof 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 mostNEIGHBOUR_DELTA_MAGfainter (G ≤ m + 3,m= the counterpart’s G, else the VSP V) counts.Nonewhen the count cannot be stated: no Gaia sources, no magnitude, or a held list not complete tom + 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):
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-07040723Z(0.7° of field rotation per sub);baselines from the reference: each anchor’s signal baseline (core’s
MIN_SIGNAL_FRACTIONtest) is measured on the solved frame, where the anchor is known to sit, never on the first tracked frame;a kept pose: a rebuilt constellation (a role change) starts from the previous transform, not from the identity;
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;
health on the wire:
ok,degradedorlost;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:
ApertureTrackerCore’s tracker with reference baselines, a kept pose and consistent anchors.
- 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:
objectmeasure_star_atfor many positions of one raw frame (green px).
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>.jsonbyTargetSet.save— the Qt file, byte for byte (_target_path/target_set/_save_target_set,acquisition_engine.py:1242-1264);set_role/removeareset_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_comparisonsand the pilot quality gate (_pilot_comparison_quality), 1348-1491;geometryisphotometry_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:
objectThe target set of the current object (
targetsevent).- 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’stargets.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’stargets.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 withfrom_calibration; GUARD: a core withoutlivekeeps the 0.4.x order, table → driver → reference). Atgain, 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.
- 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.
- 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
pendingdict (imaging_page.py:804-978), withra_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
TargetStaron the wire (protocol.md “Target set”). S77: its proper motion (None without one; GUARD: a coreTargetStarbefore 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 coremeasure_framewith the apertures placed by core’sApertureTracker(_wcs_for_frame/_build_live_tracker, 1542-1582: an owner decision, the wave 4FieldTrackerkeeps 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 flaggedsuspectandno_detectionand left out of the curve’ssigma_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:
objectOne 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,AIRMASSandSITEELEV(frame_scintillation_inputs); None: a camera frame.- Type:
S74
- 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:
objectThe 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_savedcloses 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).
- 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).
- snapshots(seq: int) list[tuple[str, int, dict[str, Any]]][source]¶
Hub lock held: what a new
/ws/eventsclient 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:
objectThe live flight recorder (
argos/core/session/diagnostics.py, P11).A line-for-line port: the core module sits in the
argos.core.sessionpackage, whose__init__imports the QtDeviceSession(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.
- 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 framewcswas 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_tdblets astropy fetchfinals2000A.alland 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;clearfor 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>.jsonand 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 pointsuspectandno_detection, out ofsigma_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
LcPointon the wire (every field oflightcurve.py:38-62, unrounded).Plus the star’s ensemble zero point and its rms on that frame (
DiffResult, the flight recorder’sensemblerecord): 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
trackingmodule when it has S69’s centring check and rotation rule (centring_offsets,off_centre,rotation_resolve_due,TrackedWCS.rotation_deg;measure_frameandmeasure_targetstakeexclude) and the neighbour rule of the S69 review (neighbour_distance;select_tracking_anchorsandcentring_offsetstakeneighbours,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/_diagnosticsfile-name rule (1531-1540, 897).
- argos.server.photometry.set_neighbours(tset) dict[source]¶
S69 (GUARD:
s69_core()):neighbours=the set’s stars, targets included, forselect_tracking_anchorsandcentring_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_csvwritten 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 levelerrorrefuse a run (PlanService.plan_for_run()).The draft persists (P13, Q-P3) in
sequence_draft.jsonbesideconfig.json, written atomically, and keeps its planningmetadatafor 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.PlanBody(*args: Any, **kwargs: Any)[source]¶
Bases:
_StrictA plan as
plan_to_dictwrites it, plusschemaandstart_at_utc.
- class argos.server.sequence_plan.PlanService(hub: Hub, clock: Callable[[], datetime] | None = None)[source]¶
Bases:
objectThe 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;
400naming the first error (Fix step N: …).
- 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).
- 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_utcschedules 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:
_StrictOne
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.jsonof a run, asSequenceWorker._write_observation_metadata(sequence_worker.py:462-480);Nonewhen the plan has no metadata.
- argos.server.sequence_plan.parse_utc(text: str) datetime[source]¶
An ISO 8601 instant; a naive one is UTC.
ValueErrorwhen 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.ValueErrorwith 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
.jsonsuffix 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 ofweb/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
idleis an active run (the plan is locked, Q-P9).
- class argos.server.sequence.SequenceService(hub: Hub)[source]¶
Bases:
objectThe 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
- 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/configduring 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_activefor a mount motion during a run;pause_runpauses first.
- 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.
- snapshots(seq: int) list[tuple[str, int, dict[str, Any]]][source]¶
Lock held: the
sequencesnapshot 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 astart_at_utcmember.
- 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;
ValueErrorelse.
- argos.server.sequence.wire_plan(plan: SequencePlan) dict[str, Any][source]¶
The schema-2 record of a plan (
plan_to_dictplusschema).
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 throughupcoming_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_exoplanetandcached_exoplanet_suggestionswith the configured cache file.Transits (A66):
predict_next_transitfrombjd_tdb(julian_date( now))at the site andutc_from_bjd_tdbassequencer_page.py:132-187,make_transit_sequenceas_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:
objectRoutes 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_planmade the draft.
- predict(body: TransitBody) tuple[ExoplanetTarget, TransitWindow, dict[str, Any]][source]¶
The transit window, chosen as Q-P10 says, and its record.
- 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.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
fcrosses level in[t0, t1], withrising(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]wheref >= level(above) orf < level.
- argos.server.planning.jd_of(t: float) float[source]¶
JD (UTC) of a Unix time, as
upcoming_night_altitudesconverts 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.
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 keysalerts.*;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:
objectThe attention list of the server (rules, items, acknowledgement).
- 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.
- 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:
objectOne 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”.
- class argos.server.attention.BaselineStore[source]¶
Bases:
objectThe server session’s finished baselines, carried over its runs.
The HFD baseline by
hfd_baseline_key(), the star-count one bybaseline_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 forCARRY_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).
- 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:
objectThe frame and timed rules of one run (no items, no I/O).
baselinesis the server session’sBaselineStore(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).
- 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.
- 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).
- 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
rulestrings, 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:
objectA 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:
objectOne saved Light sub of the run (the lab’s
FrameRecord, night.ts:29-47).
- 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:
objectRULESof rules.ts:33-39 plus the timed rules; config keysalerts.*.
- 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>, aPreventUserIdleSystemSleepassertion named “caffeinate command-line tool” inpmset -g assertions.-wties it to the server process, so it ends even if the server dies.Linux:
systemd-inhibit --what=idle:sleep --mode=blockaroundtail --pid=<server pid> -f /dev/null(it ends with the server too).Windows:
SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED)throughctypes, 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.Backend(*args, **kwargs)[source]¶
Bases:
ProtocolOne OS method:
available()says whether it can work here and why not.
- class argos.server.keepawake.CaffeinateBackend(pid: int | None = None)[source]¶
Bases:
objectmacOS:
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:
objectThe 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).
- recheck() None[source]¶
alerts.keep_awakechanged: 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
heldat once, so thestatusthat 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 readoffduring that check (pmsetalready listed the assertion). A helper that fails turns it tofailed.
- class argos.server.keepawake.NullBackend(reason: str = 'keep-awake is off in this process')[source]¶
Bases:
objectNo OS call: in-process tests and platforms without a method.
- class argos.server.keepawake.SystemdInhibitBackend(pid: int | None = None)[source]¶
Bases:
objectLinux:
systemd-inhibitfor 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 (
PlanBodykeys) 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 (
Nonewhen 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.
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 readCCD-TEMPon 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’snearest_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 a422instead of a silent return or aKeyErrorcrash;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:
objectThe curves of one source (
protocol.mdCurveSet) as Python objects.
- 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
- 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_SNRunsaturated 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:
objectOne curve of a source: the core object as loaded, and what Review adds.
- class argos.server.review.ReviewService(hub: Hub)[source]¶
Bases:
objectSessions opened for review (cached), scans and imports (rows A67-A70).
- curve_set(source: dict[str, Any]) CurveSetData[source]¶
The curves of a
Sourceas Python objects (protocol.md“Sources”).
- static open_summary(data: SessionData) dict[str, Any][source]¶
The
session_openjob’s result: what identifies the open, not the record.A job’s result travels in every
jobevent andGET /api/jobslisting (4.7 MB for a 6000-frame session, W7 technical review): the record itself is read withGET /api/review/sessionfrom the cache this open filled.
- class argos.server.review.SessionData(root: Path, stamp: tuple, record: dict[str, Any], curves: CurveSetData)[source]¶
Bases:
objectOne opened session: the record and the curves (
protocol.mdReviewSession).
- argos.server.review.apply_rules(curves: list[ReviewCurveData], rules: Any) None[source]¶
After the core’s rules: the
no_detectiondisplay 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_systrecomputed, 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 headerALTITUDE/AZIMUTHcome from the mount,SITELAT/SITELONGfrom Settings; the direction ofRA/DECatDATE-OBScomputed 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:columnfor a multi-curve export (role and star in its columns), else the one-star file’sprefix(role from the file name),targets(role from the matched star) ordefault(neither: a target by default, never exportable). RaisesOSError/ValueError/KeyError/csv.Errorfor 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/JobCancelledonly.
- argos.server.review.read_frame_header(path: Path) FrameHeader | None[source]¶
The primary header fields Review uses, or
Nonefor an unreadable file.
- argos.server.review.read_recorder(path: Path) list[RecorderFrame][source]¶
The
framerecords of a flight recorder with their stars and ensembles.Records of one frame: its
starrecords (written while measuring), then theframerecord, then itsensemblerecords (acquisition_engine.py:2141- 2172). The frame number restarts with a new series, so stars attach to the nextframerecord 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) andunverified(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
OldFileRuleson the wire (protocol.mdCurveSet), orNone.
- 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.
- argos.server.review_routes.add_routes(api: APIRouter, hub: Hub) None[source]¶
Register rows A67-A75 on api (the
/apirouter).
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/frameslayout (frames.py).A72
FileService.header():read_fits_header_textandread_fits_meta(analysis_window.py:68-133).A73
FileService.measure():measure_star_at(metrics.py:225-276) on the array ofread_fits_2d(analysis_window.py:54-65), the Frame Viewer’s click (_on_star_clicked/_remeasure_selection,analysis_window.py:874-899) throughFrameMeasurer(identical numbers, the green plane and sky computed once per file).A74
FileService.start_solve():_on_solve/_on_solved(analysis_window.py:460-505) withbuild_solve_settings(live=False),wcs_from_result,overlay_for; ASTAP throughfield_solve.solve_green(killed on cancel).A75
FileService.start_catalogue():_fetch_field_catalogues(analysis_window.py:588-629) withfield_catalog.run_requestand the Observe projectionproject_field.
- class argos.server.files.FileService(hub: Hub)[source]¶
Bases:
objectFrame-inspector tools on files (rows A71-A75); thread-safe.
- 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,
ENDlast (Qt showedstr(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
.dataloads them: a 17 000 px frame cost 400 MB before it was refused, W7 technical review), asfits_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.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:
objectPOST /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 theexportjob.
- 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:
objectWhat 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
XXXplaceholder 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
pathmust not be overwritten by an export, orNone.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_anchorspoints 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_aavsoexactly 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.AavsoExportBody(*args: Any, **kwargs: Any)[source]¶
Bases:
AavsoBody
- argos.server.export_routes.add_routes(api: APIRouter, hub: Hub) None[source]¶
Register rows A76-A79 on api (the
/apirouter).
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:
objectBatchRequest: inputs for one re-run.
- 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:
objectBatchResult.- 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)
- class argos.server.rerun.BatchRun(request: BatchRequest, *, cancel: Event | None = None, progress: Callable[[int, int, str], None] | None = None)[source]¶
Bases:
objectPhotometryBatchWorker.runwithout Qt: callrun()on a worker thread.progress(done, total, name)replaces theprogresssignal (name: the frame just handled);cancelis 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:
objectThe frames a re-run measures, and what it left out.
- class argos.server.rerun.RerunService(hub: Hub)[source]¶
Bases:
objectPOST /api/review/rerun(A76) and its plan.
- 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), passingcancel(a callable, true to stop) when the lookup takes it (GUARD: the merged core’sgaia_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/.ftsfiles (any case) in the folder itself, or in its subfolders when it has none (a session root holds lights/). Frames whoseIMAGETYPnames a calibration type are left out, and (S62) frames whoseOBJECTnames another object thanobject_name; a frame without either card is kept. In the subfolder search an Argos session folder’s frames are itslights/only, and a link to a frame already listed is that frame (S63: Siril’sprocess/holds links to the lights and registered copies). Ordered byDATE-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_folderor its parent), elseframes_folderitself. 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).ShutdownServicerunsPOST /api/app/shutdown: refused withwhatwhile something is busy unless forced, thenHub.shutdownwith oneshutdownevent per stage (port ofShell.closeEvent,shell.py:611-625), then the process exits within a bounded budget.Revealershows 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:
objectPOST /api/fs/reveal(row A12): desktop app only, allowed roots only.
- argos.server.desktop.Runner¶
(exit status or None while it still runs, stderr text).- Type:
Runs one command
- 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 orderHub.shutdownruns them;exitis last.
- class argos.server.desktop.ShutdownService(hub: Hub)[source]¶
Bases:
objectPOST /api/app/shutdown(row A7): refusal, stages, the exit.request_exitis set by the CLI (uvicorn’sshould_exit); without it (in-process tests) the stages run and the process stays. A CLI server still in its stages afterSHUTDOWN_BUDGET_Sends at once:hard_exitisos._exitonly when the CLI sets it, so an in-process server (tests) only logs the overrun.
- 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.