Test Bench

The CamCom test bench is a protocol-agnostic engineering environment for testing and validating cameras. It consists of three components:

camcomServer — an HTTP-based server that loads any adapter and provides a REST API for camera control.
camcomGui — a PyQt6 GUI that connects to the server for interactive control.
Web Dashboard — a lightweight HTML5 page for browser-based monitoring.

camcomServer

The server (testbench/app/) is the central component. It loads an adapter from a YAML config, starts an HTTP server, and manages the acquisition pipeline.

Command-Line Options

Option	Description
`-c, --config ARG`	Configuration YAML file (required).
`-l, --log-level ARG`	Log level: `ERROR`, `WARNING`, `INFO`, `DEBUG`, `TRACE`.
`--list-loggers`	List available loggers and exit.
`-v, --verbose`	Print log messages to stdout.
`-p, --log-property-file ARG`	Log property file.

Example:

camcomServer -c config/camcom/example_sim.yaml -l DEBUG -v

HTTP API

The server exposes a REST API. All responses are JSON unless noted otherwise.

Connection and Status

Method	Endpoint	Description
GET	`/status`	Server state, camera info, connection status, max FPS.
POST	`/connect`	Connect to the camera.
POST	`/disconnect`	Disconnect from the camera.
GET	`/config`	Full server configuration as JSON.
GET	`/config/file`	Server configuration as YAML text.

Acquisition Control

Method	Endpoint	Description
POST	`/acquisition/start[?frames=N]`	Start acquisition. Omit `frames` for continuous, or specify a count for finite mode.
POST	`/acquisition/stop`	Stop acquisition.
GET	`/acquisition/state`	Current acquisition state (mode, remaining frames, measured FPS).

Frame Display

Method	Endpoint	Description
GET	`/image`	Latest frame as JSON with base64-encoded image data, frame ID, and timestamp.
WebSocket	`/frames`	Real-time frame streaming (when streaming is enabled in config).

Parameters

Method	Endpoint	Description
GET	`/parameters/scan`	All available parameters with values and metadata.
GET	`/parameters/{name}`	Read a single parameter.
POST	`/parameters/{name}`	Write a parameter value (JSON body: `{value: ...}`).
GET	`/parameters/metadata/{name}`	Parameter metadata (min, max, unit, etc.).

Recording

Method	Endpoint	Description
GET	`/recording/status`	Recording state: active, frames done, frames target, etc.
POST	`/recording/start`	Start FITS recording.
POST	`/recording/stop`	Stop recording, finalize FITS file(s).
GET	`/recording/files`	List of recorded file paths.

Telemetry and Statistics

Method	Endpoint	Description
GET	`/telemetry/status`	Current telemetry samples for all monitored parameters.
GET	`/telemetry/history/{name}`	Time-series history for a parameter.
GET	`/statistics/acquisition`	Acquisition statistics (FPS, latency, drops).
GET	`/statistics/publishing`	Publishing statistics (FPS, encode time, bytes).

Server Threading Model

The server runs multiple threads:

Thread	Responsibility
HTTP Thread	Handles REST API requests (managed by httplib).
Capture Thread	Polls `adapter->ReceiveFrame()`, pushes frames into the frame queue. Active only during acquisition.
Publisher Thread	Consumes frames from the queue, encodes JPEG for the HTTP cache, and pushes to WebSocket clients.
Recording Thread	Writes frames to FITS files. Active only during recording.
Telemetry Thread	Periodically samples parameter values from the camera.

Statistics Tracking

The server maintains sliding-window statistics:

Metric	Description
Inter-frame interval	Time between consecutive frames (ms).
Processing latency	Time from frame reception to queue insertion (ms).
Publish interval	Time between consecutive published frames (ms).
Encode time	JPEG encoding duration (ms).
Frames total	Total frames received since acquisition start.
Frames dropped (capture)	Frames dropped because the capture queue was full.
Frames dropped (recording)	Frames dropped because the recording queue was full.
Frames published	Total frames published to HTTP/WebSocket clients.

FITS Recording

The server can record frames to FITS files in three formats:

Format	Description
`fits`	One FITS file per frame (e.g., `frame_0000.fits`).
`fits:cube`	Single FITS file with a 3D data cube. All frames are written at close. Optionally includes a timestamp table with per-frame ISO8601, MJD, and UNIX timestamps.
`fits:mef`	Multi-Extension FITS. One image extension per frame. Written at close.

Recording supports FITS compression algorithms: none, rice, gzip, hcompress, plio.

Stop conditions can be set via configuration: frame count, duration (seconds), or file size (MB). A trigger mode controls when recording starts: immediate, delay (seconds), or absolute (ISO8601 timestamp).

camcomGui

The GUI (testbench/gui/) is a PyQt6 application that connects to camcomServer via its HTTP API.

../_images/gui_main.jpeg — camcomGui main window showing live image display and control tabs.

Command-Line Options

Option	Description
`-c, --config ARG`	Configuration YAML file (local mode).
`-u, --uri ARG`	Server URI for remote mode (e.g., `http://host:8080`).
`-l, --log-level ARG`	Log level: `ERROR`, `WARNING`, `INFO`, `DEBUG`, `TRACE`.
`--list-loggers`	List available loggers and exit.
`-v, --verbose`	Print log messages to stdout.

One of -c or -u must be given:

-c (local mode): reads config from YAML, can start/stop the server process.
-u (remote mode): connects to a running server, downloads config from it.

Example:

# Local mode: GUI manages the server
camcomGui -c config/camcom/example_sim.yaml -l INFO -v

# Remote mode: connect to existing server
camcomGui -u http://myhost:8080 -l INFO -v

Operating Modes

Local mode (-c): The GUI can start, stop, and restart the server process automatically. If gui.auto_restart is enabled, the GUI will restart the server if it crashes.

Remote mode (-u): The GUI connects to an already-running server. It cannot manage the server lifecycle but has full control over camera operations.

GUI Tabs

The GUI organizes functionality into tabs:

Set Values Tab

../_images/gui_setvalues.jpeg — Set Values tab showing primary parameters and camera controls.

The Set Values tab provides read/write access to camera parameters:

Primary parameters (defined in gui.primary_parameters) are shown first, in the configured order.
Secondary parameters (auto-discovered via Scan()) appear after a separator, sorted alphabetically.
Parameter controls are rendered based on metadata:
- Numeric parameters: spinboxes with min/max limits and step size.
- Enumeration parameters: comboboxes with allowed values.
- Boolean parameters: checkboxes.
- Read-only parameters: labels (no editing).
Tooltips show the parameter unit, description, and constraints.

Telemetry Tab

../_images/gui_telemetry.jpeg — Telemetry tab showing time-series parameter samples.

The Telemetry tab shows live parameter values sampled at the configured interval (telemetry.sampling_period):

Selectable parameter list with checkboxes.
Time-series display of sampled values.
Export to CSV/JSON.

Recording Tab

../_images/gui_recording.jpeg — Recording tab with FITS format and stop condition controls.

The Recording tab controls FITS file recording:

Start/stop recording buttons.
Output directory selection.
Format selection (fits, fits:cube, fits:mef).
Compression (none, rice, gzip, hcompress, plio).
Stop conditions: frame count, duration, size limit.
Trigger mode: immediate, delay, absolute time.
List of recorded files.

Statistics Tab

../_images/gui_statistics.jpeg — Statistics tab showing acquisition performance metrics.

The Statistics tab displays real-time acquisition performance:

Frame rate (measured FPS).
Inter-frame interval (mean, stddev, min, max).
Processing latency.
Frame drop counts (capture and recording).
Publishing statistics (FPS, encode time, bytes).

Configuration Tab

The Configuration tab displays the current server configuration and allows exporting it as YAML.

Image Viewer

The image viewer supports:

Live frame display during acquisition.
Two streaming modes:
- WebSocket: real-time push (preferred, lower latency).
- HTTP polling: periodic GET to /image (fallback).
Colormap selection for visualization.
Zoom and pan.

The streaming mode is negotiated automatically based on the server’s streaming.protocol setting.

Preferences

GUI preferences are saved to ~/.camcom/gui/preferences.json:

Window geometry (position and size).
Show/hide log panel.
Export directory and format.
Confirmation dialogs.

Web Dashboard

The web dashboard (testbench/web/index.html) is a lightweight HTML5 page served directly by the server. It provides:

Status bar: connection state, server state (Idle/Acquiring/Recording), camera name.
Controls: Start/Stop acquisition, Refresh image.
Live image: auto-refreshing frame display during acquisition.

Access the dashboard by opening the server URL in a browser (e.g., http://localhost:8080/).

The dashboard is useful for quick checks without launching the full GUI.