> For the complete documentation index, see [llms.txt](https://mapir.gitbook.io/chloros/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md).

# Chloros CLI Reference

**Version:** 1.3.0 **Generated:** 2026-07-29 19:19 · **Revised:** 2026-11-06 **Audience:** Optimised for LLM consumption; human-readable. **Scope:** Every user-facing subcommand of `chloros-cli`, with options and copy-pasteable examples.

This document is the complete reference for the `chloros-cli` command-line tool that ships with MAPIR Chloros. It is intentionally exhaustive so that an LLM (or human) can compose any supported workflow from the listings below without inspecting the source code.

If you only need the highlights, jump to:

* [Five-Minute Quickstart](#five-minute-quickstart)
* [LATTICE Camera First-Connect Workflow](#lattice-camera-first-connect-workflow)
* [DAQ Sensor First-Connect Workflow](#daq-sensor-first-connect-workflow)
* [Smart-AE / Smart-Capture](#smart-ae--smart-capture)
* [Capture Modes, Recorders & Offline Reprocess](#capture-modes-recorders--offline-reprocess)

> **Driving Chloros from an AI assistant?** Claude Desktop, Claude Code, Cursor and other MCP clients can run processing, LATTICE cameras and arrays, and DAQ light sensors through `chloros-mcp`, the MCP server that installs with the Python SDK (and with the Linux .deb, in `/usr/bin`): `claude mcp add chloros -- chloros-mcp`. Setup, options and tools are in the SDK reference's [MCP Server (AI Assistants)](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/sdk-reference.md#mcp-server-ai-assistants). An assistant with a shell can also run every command on this page directly.

> **Changed in 1.3.0** (what an existing 1.2.0 script or workflow notices).
>
> **Changes a 1.2.0 script may need to handle:**
>
> * **`--preset` applies.** `lattice capture`, `continuous`, `calibrate`, `multi-capture`, `multi-stream`, `align-calibrate`, `align-apply` and `align-stream` dropped it in 1.2.0 and ran on the camera's own settings. It now sets the preset's format, exposure, gain and frame rate: `--preset high_speed` captures 8-bit at 5 ms, 6 dB, 60 fps. `lattice cam-connect --preset` keeps the preset's format too (1.2.0 set the camera to 12-bit after applying the preset). See [Common Options](#common-options-shared-by-most-subcommands).
> * **A Bayer pixel format on an M3M (mono) camera is its depth.** The presets name Bayer formats, which a mono sensor cannot take: in 1.2.0 the camera refused the format and kept the one it had, so `--preset high_speed` was not 8-bit there. It is now the Mono format of the same depth: `high_speed` and `--pixel-format BayerRG8` give `Mono8`, `high_quality`, `triggered` and `BayerRG12` give `Mono12`. In a mixed M3C + M3M array each camera takes the shared format in its own family, and `network-analysis` / `analyze-array --pixel-format` project each camera at that depth. The same the other way round: an M3C asked for a Mono format takes the Bayer format of that depth, so an array whose master is an M3M no longer reopens its M3C cameras on Mono. See [Mono (M3M) Single-Band Cameras](#mono-m3m-single-band-cameras).
> * **`lattice array-capture` exports are aligned by default, as the app's are.** Every member's `debayered`, `display`, `radiance`, `reflectance` and index files are warped into the master camera's frame and cropped to the members' overlap (smaller than the sensor by the cameras' offsets, `XMP-mapir:AlignmentJSON` `"applied": true`), so a CLI capture is the same files as the Chloros app's capture of the same scene; `raw` stays native. Before, a capture without `--aligned` saved every file at the native size, unwarped. `--no-aligned` keeps that. The same default applies to `--smart`, `--continuous` and `--interval`, and to the SDK and `chloros-mcp`. See [`array-capture` modes](#array-capture-modes).
> * **`lattice array-capture --compression` defaults to `none`.** Files are written uncompressed (about 6.3 MB per full-resolution frame) for the fastest sustained rate; 1.2.0 wrote `deflate` (about 4.1 MB). Pass `--compression deflate` for the smaller files. Both are lossless.
> * **PNG and JPEG take only the `display` / `preview` and index products.** A `--format png` or `jpg` capture with a level an 8-bit file cannot hold is refused before anything is captured (HTTP 400, exit `1`), and so is the default `--processing all` with `--format png`/`jpg`. See [Capture Export Levels](#capture-export-levels-the-all-default).
> * **`lattice dls` needs `--mac`.** There is no default MAC any more (it was one unit's address); `daq pool-discover --only ble` finds a sensor's. **`lattice dls --camera SERIAL`** is new.
> * **More failures exit `1`.** `process` when a run's exports could not be verified or it lost an image, though the other products are written; a capture command with any file it could not write (the other files still save); `lattice continuous` and `multi-stream` on a full drive; `array-burst` / `array-record` when the recorder reports an error; `array-build-video` when a requested product was skipped or not built as requested; `project burst` / `stream` when a capture fails partway; `project sensor log` when the recording holds no reading; `lattice exposure --set`, `gain --set` and `configure --set` with a value the camera refuses. `lattice network-analysis --json` exits as the summary does (`1` for `needs_force_slip`). The other way round: `daq pool-disconnect` of a sensor that is no longer in the pool exits `0`. See [Exit Codes](#exit-codes).
> * **A slow `lattice array-connect` never fails with the array connected.** It waits up to 600 s (180 s in 1.2.0; `project connect` 90 s), printing the backend's step as it goes, and a connect that is not done by then is undone by the backend — every camera put back as it was found — so an `Error:` (exit `1`) means no array is connected. In 1.2.0 a connect right after the cameras powered on could outlast the wait and connect the array after the command had failed. Ctrl+C now cancels the connect. See [Persistent Connections](#persistent-connections-smart-prep-gui-equivalent-flow).
> * **`lattice array-connect` keeps the full sensor.** With no `--width` / `--height` / `--binning`, every camera is set to the full sensor and the frame rate falls to what this computer and network deliver; the connect output lists faster options (binning or a smaller ROI) with their projected rates. 1.2.0 shrank or binned the frames to keep the rate up. See [`array-connect` Options](#array-connect-options).
> * **A slow network no longer refuses an array.** Each camera is paced to its share of the wire and the frame rate falls with it. Where the cameras cannot be paced that slowly, the array runs in serial emit (`slip-emit-and-capture`): every frame arrives, but the cameras are not exposed together. `--force-tier sim-capture-sim-emit` insists on simultaneous exposure. See [Array fps & burst model](#array-fps--burst-model).
> * **`lattice network-analysis` / `analyze-array` project what connect applies**: with no `--pixel-format`, the formats connect sets (Mono12 / BayerRG12, was BayerRG8), and the [packed 12-bit](#packed-12-bit-transport---packed) decision. The same command can therefore quote a different frame rate than in 1.2.0.
> * **Relative paths land where you run the command.** `-o` and the other paths the backend opens (`--input`, `--burst-dir`, `--profile`, `--save`, `--mask`), a recipe step's `output`, and the default `output/` of `lattice index --live` are resolved against the folder you run `chloros-cli` from. In 1.2.0 the backend resolved them in its own install folder, which on an installed build failed with "Access is denied". See [Conventions](#conventions).
> * **`lattice index` runs on the backend in every form**, like the other `lattice` commands, so start the backend first. The offline index (`--input`) is computed by the backend, which reads the TIFF and writes the products beside it or at `-o`, and `--list-presets` / `--list-gradients` print the backend's tables. On Windows these now work: before, the Windows CLI answered every form of `lattice index`, `--live` included, with `Error: lattice_sdk not available`. On Linux, the offline index used to run inside the CLI with no backend and no login; it now needs both, like every other CLI command. See [Index / Vegetation Maths](#index--vegetation-maths).
> * **New files beside the products.** Every radiance, reflectance and index product in which the band unmix clamped a pixel gets a mask in a `clamp_masks/` folder beside the product's folder, and captures print a `clamp mask:` line. See [Unmix clamp mask](#unmix-clamp-mask-which-pixels-a-band-was-clamped-on).
> * **Camera orientation.** A single-camera capture saves `raw` and `debayered` as the sensor read them and records the camera's flip / rotation in XMP; `process` applies it to the products it makes. Array member files stay native unless you pass the new `--orient` (`array-capture`, `array-burst`, `project capture` / `burst` / `stream`). See [Camera orientation](#what-a-captures-folder-looks-like).
> * **An export level name that is not one is refused.** `lattice capture --processing` and every `--levels` list take `raw`, `debayered`, `radiance`, `reflectance` or `display` (or an alias such as `preview`; `--processing` also `all`). Any other name is refused before the camera is touched (HTTP 400 `UNKNOWN_LEVEL`, exit `1`); 1.2.0 saved `raw` for it and exited `0`.
> * **`daq pool-set-cap` needs `--cap-id`.** Without it the command exits `2`; 1.2.0 removed the cap correction, leaving a bare sensor. `--cap-id none` asks for the bare sensor.
> * **`lattice resolution --binning-mode` is gone.** Binning is always Average; the flag is still accepted, prints a warning and does nothing. See [Sensor Tuning](#sensor-tuning).
> * **`process --debayer texture-aware` is refused for LATTICE captures.** For a folder holding LATTICE captures, `process` exits `1` after the import, naming how many there are, before processing anything. LATTICE captures always get the standard demosaic, so 1.2.0 accepted the option and ignored it; the Chloros app does not offer it for them either. See [`chloros-cli process`](#chloros-cli-process).
> * **Cameras go back the way they were found — unless `--keep-settings`.** `lattice array-disconnect`, every transient command (`multi-capture` with no array, `multi-stream`, `multi-test`, `align-calibrate`, `align-apply`, `align-stream`, `index --live`) and `lattice continuous` put each camera back as they found it: its trigger and sync-line wiring, its PTP, and every camera setting the session changed (exposure and gain, the AE target, limits and damping, white balance, black level, pixel format, binning and ROI, flips, frame rate). `--keep-settings` instead saves each camera's settings into the camera's own memory, so it powers up with them; `--clear-settings` resets that memory to the factory settings. Either way the cameras are left free-running. A project sets its cameras from its own saved settings when it connects them. See [Camera memory](#camera-memory----keep-settings----clear-settings).
> * **Every mode saves a project the same way.** Any change to a camera, an array or a light sensor connected under a project — from the app, the CLI, the SDK or the MCP server — is saved into that project's `cameras.json` / `sensors.json`, and opening the project in any mode sets the devices from it. Before, only the app saved the project, and its next save wrote over anything else. See [One project record, every mode](#one-project-record-every-mode).
> * **Files made from several cameras name every one.** A multiband stack (`align-apply`, `align-stream`, `index --live --save-multiband`), a live index made from several cameras' bands, and an array capture's `composite/` image carry each source camera's serial, model and calibration pack as lists (`XMP-mapir:SourceCameraSerials`, `SourceCameraModels`, `SourceCalBundleSha256s`, …), and EXIF `SerialNumber` lists the serials, comma-joined. They used to carry no camera at all, or the first camera's serial alone. See [Files made from several cameras](#files-made-from-several-cameras).
> * **Only a `raw` file carries the camera's calibration tags.** The MicaSense-compatible set (`BlackLevel`, `RadiometricCalibration`, the per-channel `Band{R,G,B}RadiometricCalibration`, the `MicaSenseVignetting*` sets) and the `CalibrationJSON` payload describe the sensor's raw values, so they ride on the `raw` capture file only. Every other file — a capture's `debayered`, `display`, `radiance`, `reflectance` and index files, `lattice continuous` and `multi-stream` frames, and every `process` product — carries the camera's identity (`XMP-mapir:CameraSerial`, `CameraModel`, `FilterType`, `LensModel`, `CalBundleSha256`, ...) and, on a capture, the frame's own record (`XMP-mapir:FrameJSON`: exposure, gain, temperature, pixel format, capture time). In 1.2.0 they carried the raw set too, which a tool applying it (Pix4D, Metashape) applied to pixels that are not raw values. `process` finds such a file's calibration by its serial and `CalBundleSha256`.
>
> **Other changes:**
>
> * **An array's automatic frame rate settles on what the array delivers.** A rate that loses more than 1 % of its triggers steps down, judged over several long looks rather than one, and a rate it stepped down from is retried now and then. A rate you set yourself is left alone.
> * **Auto exposure is steadier.** It holds at constant light, settles within seconds of a change, ignores small highlights, and brings back a camera that stops responding in bright sun. See [How auto exposure behaves](#how-auto-exposure-behaves).
> * **`process` counts only your images and recordings.** Re-running on a folder that holds a project's `camera_cal/` no longer counts those calibration files ("Found 96 images" on a 90-image set), and a project that already took them in drops them.
> * **`lattice multi-test` passes from the cameras' power-on state.** It turns the cameras' PTP on for the run, waits for their clocks to lock and settle before its first trigger — every camera locked for 120 s, about 2 minutes from power-on (`--ptp-settle SECONDS` sets it), since a clock just locked is off by up to \~200 us for about 2 minutes — and puts each camera's PTP back as it found it. A camera still locked from an earlier test is not waited for again. It used to leave PTP off on a single-switch network where no DAQ-E answered, and read each camera's free-running clock as a PTP clock that would not lock (`PTP is not locked`, every run). See [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions).
> * **A `.daq` recording says whether its cap was chosen or assumed.** DAQ-U, DAQ-M and DAQ-E ship with no cap, and Chloros cannot see whether one is fitted, so a sensor connected without a cap named gets `sunshine_cosine` by default, an *assumption*. Every Chloros recording (schema 1.30) now stores `cap_id_source` beside `cap_id`: `operator` when you named a cap (`none` included), `auto_default` when it was the default. Processing a recording whose cap was assumed, with the project's DAQ cap left at Auto, prints a `[daq-dls] WARNING` naming the file: a bare DAQ-U under the sunshine correction reads about 30x high. **Name the cap you fitted** when you connect, or set the project's DAQ cap, and the warning goes away.
> * **No more pip console windows on Windows.** On a PC with Python installed, the backend and each of its image workers ran `pip` once at start-up, and each opened a console window. They no longer do.
> * **Live `.daq` recordings survive a power cut.** A recording is written with a journal and a full disk sync on every commit, behind the sensor, so a slow disk delays the file and never the readings. A recording stopped mid-commit (power cut, kill) can leave `<name>.daq-journal` beside it: **copy the two together.** Chloros rolls the journal back the first time it reads the file, so the recording opens with everything committed before the stop (about the last 3 s are lost); in 1.2.0 a power cut at the wrong moment could leave the whole file unreadable ("database disk image is malformed").
> * **A recording on a busy disk no longer stalls the sensor.** `daq pool-record` queues readings and writes them on a thread of their own; a reading that could not be written is counted (`daq pool-list` shows `N write error(s)` with the last error) instead of freezing the sensor (one write took 8.4 s next to four cameras saving TIFFs).
> * **`lattice multi-capture` without an array no longer loses the frames it saved when a trigger times out.** A camera's trigger that times out (`SC_ERR_TIMEOUT -1011`, seen with four cameras on one 1 GbE switch) ends the run at that frame group: the groups already saved are listed with `Saved:`, then the error, exit `1`. In 1.2.0 it was an HTTP 500 with no list, though the files were on disk.
> * **Software-triggered cameras no longer drop every other trigger.** A camera in software trigger mode now queues a trigger that arrives during its readout (or Chloros waits for it to be ready), as cable-synced cameras already did.
> * **`daq pool-discover` names a DAQ-E-S `DAQ-E-S`** in its `MODEL` column (and `--json`'s `model`). It said `DAQ-E` for every Ethernet sensor; one that does not answer the identity check within about 2 s is still listed, as `DAQ-E`.
> * **Improved LATTICE index products** (NDVI and other indices) from `process`, in every processing mode.
> * **OCN cameras: improved radiance, reflectance and index products in sunlight.** A fleet correction is applied after the band unmix; RGN cameras are unchanged, and OCN values differ from 1.2.0's. It applies to an OCN capture made with an earlier version too, when it is processed on a computer that holds the calibration the capture was taken with (Chloros keeps a camera's calibration once the camera has been connected).
> * **`lattice continuous` records the raw frame.** A `tiff` run wrote demosaiced 3-plane frames, which `process` cannot start from. Its frames are now the `raw` file an array capture writes: one mosaic plane at the sensor's own values, uncompressed, with the calibration packet. A script that read three planes from these files reads one.
> * **Every capture saves the DAQ reading it used, as the GUI does.** `lattice capture`, `lattice continuous` (one `.daq` per frame), `array-capture` and `multi-capture` with a connected array (and the SDK) write the `.daq` and its `.match.json` whenever a DAQ is bound or pooled, a raw-only capture included; in 1.2.0 a raw or debayered capture saved one only with `--force-daq`. `--no-daq` turns it off, `--daq-tolerance-ms MS` sets the match tolerance for that capture, and the new `daq pool-bind` binds a camera or an array to a DAQ from the CLI. A `.daq` a capture saves is matched in `process` only to the cameras it names. A capture now waits for the DAQ's next reading so it can blend the readings either side of the exposure. See [The DAQ reading a capture saves](#the-daq-reading-a-capture-saves) and [A DAQ Reading Far From the Exposure](#a-daq-reading-far-from-the-exposure).
> * **`process --indices NAME`** adds the index to the project for each camera's bands, a new project included. In 1.2.0 a name the project did not list yet was ignored with `Unknown index name(s) ignored`.
> * **`process` next to a live array:** it no longer restarts a backend that holds cameras or DAQs, and waits up to 15 s for a run that is winding down. **Ctrl+C** stops the run in the backend, not just the CLI. See [`process` Notes](#notes).
> * **A project folder too deep for Windows' 260-character path limit** is refused up front with the longest folder that fits, instead of a run that writes nothing. The Windows installer now offers "Enable Windows long paths" and a Microsoft Defender exclusion for the backend, both checked by default. See [Windows (.exe)](#windows-exe).
> * **`lattice array-capture --continuous`** runs the backend's own continuous capture: a progress line every 2 s, a summary instead of a per-file listing, and a non-zero exit on any unwritten file or a full drive. See [`array-capture` modes](#array-capture-modes).
> * **The first `array-capture` after `array-connect`** waits up to 20 s for the array's first frame group instead of failing with HTTP 503 "Array still warming up".
> * **Array exposure under an ROI:** a small ROI no longer caps an array member's exposure at the sensor's free-run period (4.9 ms at 768 × 304). See [Exposure on an array member](#exposure-on-an-array-member).
> * **Auto exposure no longer lowers an array's automatic frame rate.** A cable-synced array runs at the rate its network and the cameras' readout allow; auto exposure fills the period that rate gives, then raises gain. A manual exposure longer than the period (`lattice exposure --set`, `configure --set`) slows the trigger to fit it instead of being refused, and the rate comes back when the member returns to auto. See [Exposure on an array member](#exposure-on-an-array-member).
> * **Arrays deliver fewer incomplete frame groups**, and fewer capture 503s ("No fresh synced frame group"): each slave camera's trigger input is now deglitched.
> * **Packed 12-bit transport** (`--packed`, default `auto`) raises full-sensor array frame rates by about a third. `array-connect --packet-size` is now applied (1.2.0 accepted it and ignored it). See [Packed 12-bit transport](#packed-12-bit-transport---packed).
> * **An array whose cameras power-cycle recovers by itself.** After a switch power cycle `array-connect`'s array re-opens the cameras when they answer and streams again with PTP back on; in 1.2.0 it stopped for good and needed a new `array-connect`. `array-status` reports `ptp_enabled: False` (and `ptp_off:`) while a camera reads PTP off, where it used to report the setting the array was connected with. See [Persistent Connections](#persistent-connections-smart-prep-gui-equivalent-flow).
> * **`lattice array-record` records with no GUI open.** With the GUI's combined view closed, the backend renders the view itself: the array's NDVI, or the index you pass with the new `--expr`. A recording that writes no frame now fails (`no-frames: …`, exit `1`). Before, it recorded only while the GUI's combined view was open, and a recording that wrote nothing still exited `0`. See [`array-record`](#array-record--combined-index-videogif-monitoring-grade).
> * **A camera Chloros already holds is not opened a second time.** A command that would open it itself answers HTTP 409 `CAMERA_HELD` instead, naming what holds it and the command that releases it. That includes a camera another command is using right now (a `multi-test` or `multi-capture` opening its cameras, a `lattice capture`): the second command is refused until the first finishes. Opening it again could stop the holder's stream or crash the backend. See [Persistent Connections](#persistent-connections-smart-prep-gui-equivalent-flow).
> * **Transient multi-camera commands deliver every camera or fail.** `lattice multi-capture` with no array connected, `multi-stream`, `multi-test`, `align-calibrate`, `align-apply`, `align-stream` and `index --live` exit `1` naming a camera that delivered no frame. The streams skip a frame group missing a camera and stop after three in a row; `multi-test` prints a row per trigger, `(no frame)` where a camera missed it; `align-stream` also exits `1` on a job error. Each run then puts every camera back as it found it: its trigger and sync-line wiring, its PTP (`PtpEnable`) and every camera setting the run changed — exposure and gain, AE target, limits and damping, white balance, black level, pixel format, binning and ROI, flips, frame rate — unless `--keep-settings` / `--clear-settings` (see [Camera memory](#camera-memory----keep-settings----clear-settings)). Before, these commands kept whatever frames came and exited `0` (`align-stream` printed a job error as `Note:`), and left every camera in `TriggerMode` `On`. They also set each camera's exposure from the scene before keeping a frame (a few seconds at most), on the target a connected array starts each camera at: 40 multispectral, 60 RGB (`--brightness N` sets it), and keep it for the run; so does a single `lattice capture` of a camera Chloros does not hold. Before, each camera's first frame was taken at the camera's own exposure limit, about 100 ms, whatever the light, and was often clipped. See [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions).
> * **Transient multi-camera commands share the network the way `array-connect` does, and open only `--serials`.** Each camera is paced to its share of the host link, so four cameras run on a 1 Gbps link; before, the four asked for 125 MB/s between them, all of 1 GbE, and every frame lost packets. An array the network cannot carry is refused before any camera streams. `--serials` now chooses the cameras, the first firing the trigger; before, every command opened every camera on the network whatever `--serials` said. A failure that is GVSP packet loss now says so instead of pointing at the M8 sync cable. See [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions).
> * **`lattice array-disconnect` leaves the cameras free-running, as found.** `TriggerMode` `Off`, and everything else as the connect found it — the trigger and sync-line settings (`TriggerSource`, `TriggerActivation`, `TriggerOverlap`, `TriggerDelay`, `LineMode` / `LineSource`), PTP, and the camera settings the session changed — so a single-camera command on a former member gets frames at once, and the master is no longer left on `TriggerSource` `Software`. `--keep-settings` saves the session's settings into each camera's memory, `--clear-settings` resets that memory (see [Camera memory](#camera-memory----keep-settings----clear-settings)). `lattice continuous` also sets a camera it finds armed to free-run for the run (and puts it back after), and a run with no frame exits `1`.
> * **`lattice configure --get` / `lattice exposure`** print a `note:` with the camera's real exposure or gain while its auto mode runs. A refused `lattice exposure --set` / `configure --set` says the range the camera accepts and puts the auto mode back instead of leaving auto exposure off. See [Sensor Tuning](#sensor-tuning).
> * **New camera controls:** `lattice highlights` (pull bright white surfaces down in the RGB display render) and `lattice exposure --brightness-auto`. **`lattice multi-detect`** finds the cabled cameras in one probe round and defaults the master to the RGB camera.
> * **New DAQ commands:** `daq pool-bind`; `pool-enable-ptp`; and for a DAQ-E's own settings `pool-info`, `pool-set-network`, `pool-set-auto-stream`, `pool-reboot` and `pool-update-firmware`. See [DAQ-E Device Settings](#daq-e-device-settings).
> * **A DAQ-E that stops delivering is reconnected by the backend.** When a pooled DAQ-E's stream goes silent (a power cycle of the switch that powers it, a dropped camera link), the backend reconnects it with the settings it had, retrying at growing intervals while it is gone. A recording on it carries on in the same `.daq` with the gap marked in the file, and `pool-record --stop` lists each gap. In 1.2.0 the sensor stayed silent until `pool-disconnect` + `pool-connect`, which also ended the recording. See [A DAQ-E That Stops Delivering](#a-daq-e-that-stops-delivering).
> * **`time-sync status`** reports whether the PTP grandmaster's packets reach the network (`health`), with a `WARNING:` on stderr when they do not. See [`time-sync`](#chloros-cli-time-sync).
> * **Linux .deb:** it raises the kernel's socket receive buffers that camera streams need (at the kernel default, arrays lost frames and frame rate), adds a backend service that runs as your user, and `lattice network` checks the buffers. The CLI never stops a backend that a service runs, and an upgrade starts the enabled backend services again. See [Running the backend as a service](#running-the-backend-as-a-service-headless) and [Linux hosts — socket receive buffers](#linux-hosts--socket-receive-buffers).
> * **`lattice array-capture` says when it could not align:** each reason a capture was saved unaligned (no alignment profile, members at different resolutions, an array not cable-synced, a frame the profile cannot be mapped onto) prints as an `Alignment:` line. **`chloros-cli daq help`** is `daq --help` (it exited `2`), and on Linux the help lists the direct-hardware `daq` commands that build includes.
> * **Jetson:** the package is `chloros_1.3.0_arm64_jp6.deb`, for JetPack 6, and its GPU processing runs on the Orin with JetPack's CUDA PyTorch. See [Linux arm64 — Jetson](#linux-arm64--jetson-jetpack-6).

***

## Conventions

* All commands are prefixed `chloros-cli`. On Windows the binary is `chloros-cli.exe`; on Linux/Jetson it is `chloros-cli`.
* Optional arguments are shown as `--flag`. Required positional arguments are shown without brackets.
* Where a default is given, omitting the flag uses that value.
* The CLI is a thin HTTP client over the Chloros backend (the server on `127.0.0.1:5000` that the desktop app also uses). **Which commands start it:**
  * The core commands — `process`, `login`, `logout`, `status`, `export-status`, `time-sync` and `selftest` — use a running backend, or start one when none is running and stop it again when they finish.
  * **The `lattice`, `project` and `daq` commands never start one.** They need a backend that is already running: the Windows desktop app's, the Linux [backend service](#running-the-backend-as-a-service-headless), or one you start yourself (see [Start the Backend](#start-the-backend)). Without one they print `Error: Chloros backend not reachable at http://127.0.0.1:5000`, with the command that starts it, and exit `1`.
* `CHLOROS_BACKEND_URL=<url>` points the **`lattice`**, **`project`**, and **`daq pool-*`** command families at another backend (`lattice network-analysis` takes `--backend-url` instead). The core commands deliberately pin `http://127.0.0.1:<port>` and ignore it (the IPv4 literal avoids Windows' `localhost`→`::1` \~2 s-per-request penalty). See [Environment Variables](#environment-variables).
* **Relative paths are resolved against the folder you run `chloros-cli` from.** The backend is the process that opens output and input folders, so before sending a path the CLI makes it absolute: `-o` / `--output` (including its default, `output`), `--input`, `--burst-dir`, `--profile`, `--save` and `--mask`, a [recipe](#recipe-dsl) step's `output` (default `output`), and the default `output` folder of `lattice index --live`. `-o captures/` therefore writes to `<current folder>/captures/`, and the printed paths are absolute. `~` is expanded. Against a remote backend (`CHLOROS_BACKEND_URL` naming another machine) paths are sent as typed and resolve on that machine.
* A Chloros+ account login is required for all SDK/CLI calls (run `chloros-cli login` once per machine; cached in `~/.chloros/`).
* Examples use Linux paths; on Windows replace `/home/user/...` with `C:/Users/.../...`. A DAQ-U's serial port is `COM3`-style on Windows and `/dev/ttyUSB0` / `/dev/ttyACM0` on Linux.
* Synopses write mutually exclusive flags as `{--a | --b}` and optional ones in `[...]`.

***

## Top-Level Synopsis

```
chloros-cli [global options] COMMAND [command options]
```

### Global Options

| Flag                 | Description                                                                                                                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--backend-exe PATH` | Override the auto-detected backend executable.                                                                                                                                                                                                      |
| `--port N`           | Backend HTTP port (default: `5000`). Used by the core commands only (`process`, `login`, `logout`, `status`, `export-status`, `time-sync`, `selftest`); `lattice`, `project` and `daq` use `CHLOROS_BACKEND_URL` (default `http://127.0.0.1:5000`). |
| `-v, --verbose`      | Enable verbose output.                                                                                                                                                                                                                              |
| `--restart`          | Force-restart the backend (kills any running `backend_server.py`). A backend run by a systemd service (Linux .deb) is never stopped: the command prints `sudo systemctl restart <unit>` instead and exits `1`.                                      |
| `--version`          | Print version (`Chloros CLI 1.3.0`).                                                                                                                                                                                                                |
| `--help`             | Show top-level help.                                                                                                                                                                                                                                |

### Commands Index

| Command                                                                                                                                                  | Purpose                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`process`](#chloros-cli-process)                                                                                                                        | Process a folder of Survey3 or LATTICE captures end-to-end. |
| [`login`](#chloros-cli-login)                                                                                                                            | Authenticate this machine with a Chloros+ account.          |
| [`logout`](#chloros-cli-logout)                                                                                                                          | Clear cached credentials.                                   |
| [`status`](#chloros-cli-status)                                                                                                                          | Show current license / authentication status.               |
| [`export-status`](#chloros-cli-export-status)                                                                                                            | Live Thread-4 export progress during a `process` run.       |
| [`language`](#chloros-cli-language)                                                                                                                      | Set or list CLI display language (38 supported).            |
| [`set-project-folder`](#project-folder-commands) / [`get-project-folder`](#project-folder-commands) / [`reset-project-folder`](#project-folder-commands) | Default project folder (shared with the GUI).               |
| [`update`](#chloros-cli-update)                                                                                                                          | Check for and install Chloros updates (Linux/Jetson).       |
| [`selftest`](#chloros-cli-selftest)                                                                                                                      | System diagnostics + smoke tests.                           |
| [`time-sync`](#chloros-cli-time-sync)                                                                                                                    | PTP grandmaster status / control.                           |
| [`lattice`](#chloros-cli-lattice)                                                                                                                        | LATTICE camera control & capture (45+ subcommands).         |
| [`daq`](#chloros-cli-daq)                                                                                                                                | DAQ spectral-sensor control (DAQ-U / DAQ-M / DAQ-E).        |
| [`project`](#chloros-cli-project)                                                                                                                        | Open and drive a saved Chloros project (cameras + DAQs).    |

***

## Installation

`chloros-cli` ships inside the Chloros desktop installer on every supported platform — there is no separate CLI download. Installing the platform package adds `chloros-cli` to your `PATH` alongside the desktop app and the backend binary it drives.

Latest downloads: [`https://mapir.gitbook.io/chloros/download`](https://mapir.gitbook.io/chloros/download)

> The installer also ships convenience launcher scripts (`Chloros_CLI.bat` / `Chloros_CLI.ps1`, `Launch_CLI.*`, `chloros-cli.sh`) that open a ready-to-use CLI shell.

### Windows (.exe)

1. Download the Windows installer from the download page.
2. Run `Chloros Installer 1.3.0.exe` and follow the wizard. Default install path is `C:\Program Files\Chloros\` (the CLI lands in `C:\Program Files\Chloros\cli\`, which the installer adds to PATH).
3. Open a new terminal (`cmd.exe`, PowerShell, or Windows Terminal) so the updated `PATH` is picked up.

```powershell
chloros-cli --version
```

The installer automatically adds `chloros-cli.exe` to your system `PATH` and bundles the LATTICE camera drivers. The backend is `C:\Program Files\Chloros\backend\chloros-backend.exe` (the `backend` folder of your install folder), which is not on `PATH`.

**System settings.** The installer's *Select Additional Tasks* page has two options under **System settings**, both **checked by default**:

| Option (as worded in the installer)                                                                        | What it does                                                                                                                                                                                                                                                                                                                                                                                                   | Silent-install opt-out             |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **Enable Windows long paths** (lets project folders sit deeper than 260 characters; recommended)           | Sets Windows' machine-wide `LongPathsEnabled` to 1. Windows ships with it off, and then no path may pass 260 characters; Chloros products sit up to about 130 characters below the project folder, so a deeper project folder is refused (see [Troubleshooting](#troubleshooting-pointers)). Takes effect for programs started after the install. Left on at uninstall, because other programs may rely on it. | `/MERGETASKS="!longpaths"`         |
| **Exclude the Chloros backend from Microsoft Defender scanning** (much faster camera capture; recommended) | Adds a Defender **process** exclusion for `chloros-backend.exe` in the install folder, so real-time protection does not scan each file the backend writes, wherever it writes it. No other program is excluded; the exclusion is removed at uninstall. Where Defender is absent or locked by policy the step fails quietly and the install carries on.                                                         | `/MERGETASKS="!defenderexclusion"` |

**Why the Defender option matters:** at high capture rates, real-time scanning of the capture files costs about 30 % of the capture rate (measured on a 9-camera continuous capture: 77.7 captures/s excluded, 52.7 scanned). `lattice array-capture --continuous` prints a note when it measures Defender using a CPU core or more on the capture; re-run the installer with the option checked.

A silent install (`/SILENT` or `/VERYSILENT`) applies both unless opted out, e.g. `"Chloros Installer 1.3.0.exe" /VERYSILENT /MERGETASKS="!defenderexclusion"`.

**Windows Firewall.** The installer always adds two inbound rules for `chloros-backend.exe`, on every network profile, and the uninstaller removes them: `Chloros Backend (UDP-In)`, for camera streams, PTP, mDNS and the DAQ-E data stream, and `Chloros Backend (TCP-In)`, limited to the local subnet, for a DAQ-E firmware update, in which the sensor connects back to this computer to collect the image (see [DAQ-E Device Settings](#daq-e-device-settings)). The backend's HTTP API stays bound to `127.0.0.1`.

### Linux amd64 (.deb)

For Ubuntu 22.04 LTS or newer / Debian-based x86\_64 workstations.

> **Ubuntu 20.04 is not supported.** The package's dependency list is derived from what the backend actually links against, and that includes `libc6 (>= 2.35)`; focal ships glibc 2.31. `apt` refuses the install rather than letting it fail at runtime. The list also names `libgl1`, which the bundled OpenCV loads and a minimal server image may lack; `apt install` brings it.

```bash
sudo apt install ./chloros_1.3.0_amd64.deb
chloros-cli --version
```

The .deb installs:

* `chloros-cli` to `/usr/bin/chloros-cli`, and `chloros-backend` (starts the backend) to `/usr/bin/chloros-backend`
* The compiled backend and CLI, unpacked, in `/usr/lib/chloros/backend/` and `/usr/lib/chloros/cli/`
* The LATTICE camera drivers
* Denoiser models, calibration bundles, and update-channel config
* The Python SDK for the system `python3` (`import chloros_sdk`). `apt install` also brings its requirements, `python3-numpy` and `python3-requests` (recommended, not required: the programs above are self-contained; `dpkg -i` skips them, and the install output names what is missing). In a virtualenv: `pip install /usr/lib/chloros/sdk/chloros_sdk-*.whl`
* `/etc/sysctl.d/60-chloros-gige.conf`, which raises the kernel's socket receive buffers for camera streams to 32 MB, and applies them at once (a value already set higher is left alone). Removing the package removes the file. See [Linux hosts — socket receive buffers](#linux-hosts--socket-receive-buffers).
* Two optional systemd services for the backend, neither enabled (next section)

#### Running the backend as a service (headless)

Without a service, the backend (and with it the PTP grandmaster) runs only while something has started it: `chloros-backend` in a terminal, an SDK script, or a core `chloros-cli` command for the length of its run. For an always-on backend on a headless machine, enable the service **as your user**:

```bash
sudo systemctl enable --now chloros-backend@$USER.service    # $USER expands to your user name
systemctl status chloros-backend@$USER.service
```

`chloros-backend@<user>.service` runs the backend as that user. The captures it writes are theirs, its detailed log is in their `~/.cache/chloros/logs`, and it uses their `chloros-cli login` (`~/.chloros`), so sign in once as that user first. PTP needs no root. Like every installed backend, it listens on `127.0.0.1:5000` only.

`chloros-backend.service` runs the backend as **root**. It is still installed so that a machine that enabled it keeps running, but everything a root backend writes belongs to root, so a user cannot delete their own captures. To switch to your user:

```bash
sudo systemctl disable --now chloros-backend.service
sudo systemctl enable --now chloros-backend@$USER.service
```

The root service's detailed log is in `/var/log/chloros`, readable by members of the `adm` group (the service sets `CHLOROS_LOG_DIR`; see [Environment Variables](#environment-variables)). Installing the package prints the `enable` command with your user name filled in, and the switch as well when the root service is enabled.

**Enable one backend unit.** Only one backend runs at a time. A second enabled unit (`chloros-backend.service` beside `chloros-backend@<user>.service`, or two users' `@` units) refuses to start and stays `failed` with exit status 98; systemd does not restart it. Its `systemctl status` says why: `Another instance is already running. Exiting.`, then what holds the backend (port 5000, or the lock file and the user it belongs to), then `systemd will not restart <unit> (exit status 98)`. After a reboot, either unit may be the one that runs. To switch, disable the one you do not use, as above.

**The CLI never stops a service's backend.** `chloros-cli` uses it as it is, as the GUI and the SDK do: `process` runs on it, loading its own project in place of the last one. Where the CLI would otherwise restart the backend (`--restart`, or a `process` whose import found nothing), it names the unit, prints `sudo systemctl restart <unit>` and exits `1`, because a backend stopped that way would stay down. `GET /api/status` names the unit as `service` (`null` for a backend no service runs).

**Upgrade and removal.** Upgrading the package stops every backend service, then starts again each one that is enabled, the `@<user>` units first (one started by hand but never enabled stays stopped, as after a reboot). With more than one enabled, only one runs and the others stay failed as above; the upgrade prints `Chloros: N backend units are enabled: …` and `Keep one enabled: sudo systemctl disable --now <unit>`. Removing it stops and disables them. Purging it also deletes `/var/log/chloros`.

### Linux arm64 — Jetson (JetPack 6)

```bash
sudo apt install ./chloros_1.3.0_arm64_jp6.deb
chloros-cli --version
```

Same layout as the amd64 .deb, receive buffers and [backend services](#running-the-backend-as-a-service-headless) included, for Jetson Orin / Orin NX / Orin Nano on **JetPack 6** (L4T R36). Its PyTorch is JetPack 6's CUDA build for Orin, so GPU processing, the texture-aware debayer included, runs on the Jetson's GPU. The package does not carry CUDA itself: it uses the CUDA and cuDNN libraries JetPack 6 installs (`sudo apt install nvidia-jetpack` on an image that lacks them). Where no CUDA GPU is usable, processing runs on the CPU and texture-aware uses the standard debayer (see [`process`](#chloros-cli-process)).

### Authenticate Once Per Machine

Every platform requires a one-time Chloros+ login before SDK/CLI calls work:

```bash
chloros-cli login user@example.com 'YourPassword'
```

Credentials are cached in `~/.chloros/user_session.json`.

### Start the Backend

The `lattice`, `project` and `daq` commands talk to a backend that is already running; they never start one (see [Conventions](#conventions)). Keep one running while you use them:

| Platform       | How                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Windows        | Open the Chloros desktop app (its backend serves the CLI as well), or run `"C:\Program Files\Chloros\backend\chloros-backend.exe"` in a terminal of its own (the `backend` folder of your install folder) and leave it open. |
| Linux / Jetson | Run `chloros-backend` in a terminal of its own, or keep one always running with the [backend service](#running-the-backend-as-a-service-headless).                                                                           |

Only one backend runs at a time; every client (the GUI, the CLI, SDK scripts) shares it. The core commands (`process`, `login`, `status`, …) use it too, and start one when none is running.

**A backend keeps running between commands**, so the next one does not pay its startup again. It stops when you sign out (`chloros-cli logout`, unless the Chloros app is open or a run or an offline build is in progress), when you run `chloros-cli backend stop`, or by itself after 30 minutes with nothing using it: no command, script or app, no run or offline build, no connected camera or light sensor. `backend stop` refuses while a run or an offline build is in progress, naming it; `--force` stops it now and that run or build is lost (a burst is kept, and `array-build-video` builds it again). Set `CHLOROS_BACKEND_IDLE_MIN` before the backend starts to change the 30 minutes (`0`: never); the [backend service](#running-the-backend-as-a-service-headless) never stops on its own. `chloros-cli backend status` shows whether one is running, what is using it and any offline build running. `process` opens its project in the running backend, unless the Chloros app is open with a project it opened: then it refuses, and you process from the app or close that project first. A project an earlier `process` or an SDK script left open is simply replaced.

### Verify the Install

```bash
chloros-cli --version           # prints "Chloros CLI 1.3.0"
chloros-cli selftest            # 7-step diagnostic (backend, GPU, models, CUDA)
chloros-cli status              # shows license tier + logged-in user
```

`selftest` exits `0` only when all seven checks pass. The last one needs a CUDA GPU (an NVIDIA GPU, or a Jetson Orin's) and the denoiser models, so on a computer without one it lists `Failed: CUDA + Denoiser` and exits `1`; everything except the GPU-only texture-aware debayer still works there.

> **Chloros+ subscription required.** The CLI requires an active Chloros+ plan. **Copper** is the entry Chloros+ tier — every paid Chloros+ tier has CLI/SDK access; only the free **Iron** tier does not. (Plan-id map: `0`=Iron/free, `1`=Copper, `2`=Bronze, `3`=Silver, `4`=Gold.) Upgrade at [`https://cloud.mapir.camera/pricing`](https://cloud.mapir.camera/pricing).
>
> This floor is enforced by the backend, not just by the CLI: an SDK/CLI-flagged request without a paid plan is rejected with `403 PLAN_UPGRADE_REQUIRED`, whether it comes from `chloros-cli`, the Python SDK, or a hand-rolled HTTP client. A logged-out caller gets `401 AUTH_REQUIRED` instead. Access works offline for the plan's grace period (30 days monthly, to expiry for yearly) and stops when that lapses; `chloros-cli status` keeps working so the reason is visible (it is the one SDK/CLI route exempt from the tier gate — `GET /api/license-status`).

***

## Five-Minute Quickstart

```bash
# 1. Sign in once on this machine
chloros-cli login user@example.com 'YourPassword'

# 2. Survey3 / LATTICE folder → finished radiance + NDVI in one call
chloros-cli process "/home/user/captures/flight_001" \
  --vignette --reflectance --indices NDVI GNDVI OSAVI

# 3. The lattice / daq commands need a running backend: on Windows open the
#    Chloros desktop app; on Linux start one (or see "Start the Backend")
chloros-backend &

# 4. Take a single LATTICE photo with the first camera found
chloros-cli lattice capture -o output/

# 5. Connect a 4-cam LATTICE array with the GUI's smart-prep flow
chloros-cli lattice array-connect \
  --serials 213800234,214000533,214701288,214701292

# 6. Read a spectrum from a connected DAQ-U (Windows: --port COM3)
chloros-cli daq pool-connect --port /dev/ttyUSB0
chloros-cli daq pool-latest --sensor-id CB-7C-A8-2E-5F   # id from 'daq pool-list'
```

`process` (step 2) starts a backend for its own run when none is running and stops it when it finishes, so start one for step 4 onward. See [Start the Backend](#start-the-backend).

***

## `chloros-cli process`

Process a folder of images through the full Chloros pipeline (target detection → calibration → vignette → reflectance → index export).

### Synopsis

```
chloros-cli process INPUT [OPTIONS]
```

### Positional Arguments

| Argument | Description                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------- |
| `INPUT`  | Path to input folder containing `.raw + .jpg` (Survey3), `.tif/.tiff` (LATTICE), or `.dng` files. |

### Common Options

| Flag                                                 | Default                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-o, --output PATH`                                  | a new folder named by `-n` in the default project folder | The project folder. The project is named after it, and a folder that already holds a `project.json` gets a `_1` / `_2` sibling instead of being overwritten. The default project folder is the one `set-project-folder` (or the GUI) chose, else `Documents/MAPIR/Chloros Projects`.                                                                                                                                                                                                                                                                                                                                                                      |
| `-n, --project-name NAME`                            | auto (timestamp)                                         | Project name, used only **without** `-o` (with `-o` the project takes the folder's name).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--debayer {standard,texture-aware}`                 | `standard`                                               | `texture-aware` uses a Chloros+ neural debayer for Survey3 imagery; slower but higher quality. It is for Survey3 only: LATTICE captures always use the standard demosaic, so for a folder holding LATTICE captures `process` refuses `texture-aware` after the import, with an error naming how many there are, and exits `1` before processing anything (the Chloros app does not offer Texture Aware for them either). It needs a CUDA GPU (an NVIDIA GPU on Windows / Linux x64, the Orin's GPU on a Jetson): without one the run uses `standard`, and the backend logs one `[DEBAYER] … needs a CUDA GPU …` line saying why (shown with `--verbose`). |
| `--vignette / --no-vignette`                         | `--vignette`                                             | Vignette correction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--reflectance / --no-reflectance`                   | `--reflectance`                                          | Reflectance calibration (uses panel target if found, NIST per-serial cal for LATTICE). For LATTICE multispectral this doubles as the reflectance **product** toggle — see [Per-Product Export Toggles](#per-product-export-toggles-lattice-multispectral).                                                                                                                                                                                                                                                                                                                                                                                                |
| `--ppk`                                              | off                                                      | Apply PPK GNSS corrections from sidecar files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--exposure-pin-1 CAMERA_MODEL`                      | none                                                     | The camera model wired to exposure pin 1, for PPK time synchronization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--exposure-pin-2 CAMERA_MODEL`                      | none                                                     | The camera model wired to exposure pin 2, for PPK time synchronization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--recal-interval SECONDS`                           | `0`                                                      | Minimum recalibration interval, in seconds (the project's *Minimum recalibration interval*).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--timezone-offset HOURS`                            | `0`                                                      | The light sensor's timezone offset from UTC, in hours (the project's *Light sensor timezone offset*).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--format FORMAT`                                    | `TIFF (16-bit)`                                          | One of `TIFF (16-bit)`, `TIFF (32-bit, Percent)`, `TIFF (8-bit)`, `PNG (8-bit)`, `JPG (8-bit)`. Chloros never raises an image's bit depth: on all-8-bit images a deeper format is written as `TIFF (8-bit)` and the run says so once. In a project mixing 8-bit and 12/16-bit captures, each capture exports at its own depth or lower. Radiance is always 32-bit float.                                                                                                                                                                                                                                                                                  |
| `--indices NAME [NAME ...]`                          | none                                                     | Vegetation indices by preset name (`NDVI`, `GNDVI`, `OSAVI`, `SAVI`, `EVI`, `GCI`, …), case-insensitive. Each is added to the project for its camera's bands, a new project included. A name that is not a preset, or that the camera's bands cannot make (`NDRE` needs RE and NIR, which no single camera provides), is named in a warning and gets no index image.                                                                                                                                                                                                                                                                                      |
| `--input-level {auto,raw,debayered,processed}`       | `auto`                                                   | Force the pipeline entry point for LATTICE TIFFs (Survey3 .raw is unaffected). Also the escape hatch that lets a capture with **no raw** be processed at all — see [What a captures folder looks like](#what-a-captures-folder-looks-like).                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--debayered / --no-debayered`                       | on                                                       | Emit the linear debayered product (`Debayered_Images`). See [Per-Product Export Toggles](#per-product-export-toggles-lattice-multispectral).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--preview / --no-preview`                           | on                                                       | Emit the display preview (`Preview_Images`): RGB = white balance (DAQ-illuminant when available, else gray-world) + gamma; multispec = false-colour stretch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--radiance / --no-radiance`                         | on                                                       | Emit float32 radiance (`Radiance_Images`, W/m²/sr/nm).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--reflectance-source {daq,target,auto}`             | `auto`                                                   | Reference for the LATTICE reflectance product: `auto` = QA-passing in-frame target is the absolute reference (a target with a QA flag competes with the DAQ on measured score), DAQ-downwelling (ρ = π·L/E) fallback; `target` = strict (no DAQ substitution); `daq` = DAQ-authoritative. See [Per-Product Export Toggles](#per-product-export-toggles-lattice-multispectral).                                                                                                                                                                                                                                                                            |
| `--target-reflectance-dir DIR`                       | none                                                     | Directory of per-unit **measured** target reflectance scans (`<serial>.csv`); falls back to the nominal T3/T4P spectra on a miss.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--array-alignment / --no-array-alignment`           | on                                                       | LATTICE arrays: apply the module-to-module alignment stamped in each capture's `Chloros:Alignment*` XMP to every processed product (debayered / preview / radiance / reflectance / index). No-op for images without the tags.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--array-alignment-crop / --no-array-alignment-crop` | crop                                                     | Crop aligned exports to the array's common-overlap region so all modules share one footprint; `--no-…` keeps the full sensor canvas (black fill outside the source).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--array-alignment-interp {bilinear,nearest,cubic}`  | `bilinear`                                               | Resampling for the alignment warp. `nearest` preserves exact source DNs (no inter-pixel mixing of radiometric values).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Target-Detection Options

| Flag                        | Description                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `--min-target-size PIXELS`  | Minimum calibration-target size in pixels for the detector.                                     |
| `--target-clustering 0-100` | Target clustering percentage (default `60`).                                                    |
| `--target / --targets`      | Search for calibration targets only in a `target` or `targets` subfolder of the input (faster). |

### Examples

```bash
# Simplest: defaults are good for most surveys
chloros-cli process "/home/user/images/survey_001"

# Multi-index with explicit format
chloros-cli process "/home/user/images/survey_001" \
  --vignette \
  --reflectance \
  --format "TIFF (32-bit, Percent)" \
  --indices NDVI GNDVI OSAVI

# Texture-aware debayer for highest quality (Chloros+ only)
chloros-cli process "/home/user/images/survey_001" \
  --debayer texture-aware \
  --indices NDVI

# Process LATTICE captures explicitly (auto-detects from EXIF normally)
chloros-cli process "/home/user/captures/lattice_flight" \
  --input-level processed

# LATTICE multispectral → float32 radiance only (no DAQ downwelling needed)
chloros-cli process "/home/user/captures/lattice_flight" \
  --no-debayered --no-preview --no-reflectance

# LATTICE reflectance anchored to an in-frame target (strict, no DAQ fallback),
# with per-unit measured target scans looked up by serial
chloros-cli process "/home/user/captures/lattice_flight" \
  --reflectance-source target --target-reflectance-dir "/home/user/target_scans"

# LATTICE array capture: keep native geometry (ignore stamped alignment)
chloros-cli process "/home/user/captures/array_flight" \
  --no-array-alignment

# Aligned, uncropped, value-preserving resampling
chloros-cli process "/home/user/captures/array_flight" \
  --no-array-alignment-crop --array-alignment-interp nearest

# Save to a project folder of your choice (the project is named after it)
chloros-cli process "C:/input" -o "C:/projects/Field_A_2026-05-26"

# Name the project and let it go to the default project folder
chloros-cli process "C:/input" -n "Field_A_2026-05-26"
```

### Per-Product Export Toggles (LATTICE multispectral)

LATTICE processing fans out into **every applicable product in one pass**. The four per-type toggles — `--debayered`, `--preview`, `--radiance`, `--reflectance` — are all **ON by default**; use the `--no-<type>` form to drop one. RGB master cams only ever emit debayered + preview (no per-band radiance/reflectance), so `--radiance`/`--reflectance` are no-ops for them. The toggles are ignored for Survey3 `.raw` (which follows the standard reflectance/target path). *(The old `--radiometric-output {reflectance,radiance,sensor-response}` flag was **removed** and replaced by these toggles; there is no `sensor-response` level anymore.)*

| Product         | Output                                                                                                                                                                                                                          | DAQ downwelling needed?                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `--debayered`   | Linear demosaic (`Debayered_Images`): the same file a capture saves at its `debayered` level — the calibration pack's dark offset (DSNU) off the raw, then OpenCV's edge-aware demosaic; no linearity LUT, flat field or unmix. | No.                                                                  |
| `--preview`     | Display preview (`Preview_Images`): RGB = WB + gamma; multispec = false-colour stretch.                                                                                                                                         | No.                                                                  |
| `--radiance`    | float32 W/m²/sr/nm from the full radiometric chain (`Radiance_Images`).                                                                                                                                                         | No.                                                                  |
| `--reflectance` | uint16 reflectance ρ (`32768` = 1.0), Pix4D-ready.                                                                                                                                                                              | **Yes**, unless a QA-passing in-frame target anchors it (see below). |

`--reflectance-source` picks the reflectance reference: **`auto`** (default) makes a QA-passing in-frame target the **absolute reference** — the target-anchored empirical-line chains are cross-scored on held-out panels and the measured winner applied, band by band: a band the DAQ cannot calibrate, or whose DAQ-slope fit fails, takes the target's own line (`ReflectanceElBandMethods` says which) — a target that passes QA with a flag (a panel dropped, a band out of order) also competes with the DAQ divide on that measured score, and a frame it loses to is stamped `ReflectanceChain=daq` — falling back to the DAQ downwelling divide (ρ = π·L/E) when no target is present or QA fails; **`target`** is strict (no DAQ substitution); **`daq`** opts out to the DAQ-authoritative behaviour. Target geometry (ArUco / fixed-ROI / strip) comes from the project target config; `--target-reflectance-dir DIR` holds per-unit **measured** scans (`<serial>.csv`) looked up by the target unit's serial/QR, with the nominal T3/T4P spectra as the fallback.

The DAQ reflectance path resolves the **timestamp-matched downwelling** automatically from a recorded **`.daq`** (DAQ-U/M/E) **or a DAQ-M native `.csv`** found alongside the imagery. If a per-camera or DAQ calibration bundle isn't cached locally, the pipeline **auto-fetches it from AWS** on first use (requires internet once; cached under `~/.chloros/`).

**Whose reading is it.** A `.daq` a capture saves is the reading of the camera(s) it describes — named in a `<file>.daq.cameras.json` sidecar beside it (`lattice capture`, `multi-capture`, `array-capture` and the GUI alike; a raw burst names each member's reading in its manifest) — and `process` matches it **only to images from those cameras**. A standalone camera with no reading of its own therefore no longer borrows another camera's DAQ; bind a DAQ to it, or record one. A DAQ's own recording (`daq pool-record`, or a recording started in the GUI), or any `.daq` without that sidecar (older captures included), still serves every camera.

#### Reading reflectance pixels (Pix4D / Metashape / your own scripts)

Reflectance is stored as integer DN, and **the DN that means ρ = 1.0 depends on the source camera**:

| Source              | ρ = 1.0 is                  | How to tell                                             |
| ------------------- | --------------------------- | ------------------------------------------------------- |
| LATTICE (M3C / M3M) | `32768` (headroom to ρ 2.0) | XMP `Chloros:PixelScale=32768` is stamped on the file.  |
| Survey3             | `65535` (clipped at ρ 1.0)  | No `Chloros:*` XMP tags — that absence *is* the signal. |

**Read `Chloros:PixelScale` and divide by it** rather than assuming a constant. The tag is defined in the uint16 domain, so it stays `32768` across output formats that rescale — `TIFF (16-bit)`, `TIFF (8-bit)`, `PNG (8-bit)`, `JPG (8-bit)` and `TIFF (32-bit, Percent)` are all self-describing (normalise the stored dtype back to uint16 first: ×257 from 8-bit, ×65535 from float).

> **Files from older builds can carry no scale.** An 8-bit reflectance TIFF is rescaled and stamped `Chloros:PixelScale` like the others. Builds before 1.3.0 *clipped* it to 0..255 instead, so every value above ρ≈0.008 flattened to 255, and they omitted both `Chloros:PixelScale` and the `MicaSense:RadiometricCalibration` tuple. **If the tag is absent on a LATTICE reflectance file, do not assume a scale — reprocess it** rather than dividing pixels that were never divisible.

#### Reading index pixels (NDVI and the other vegetation indices)

**An integer index raster is a per-image contrast stretch, not a −1…1 map.** `TIFF (16-bit)`, `TIFF (8-bit)`, `PNG (8-bit)` and `JPG (8-bit)` index products — including the 8-bit TIFF an 8-bit capture is written as — store

```
DN = (value − IndexMin) / (IndexMax − IndexMin) × full_scale
```

where `IndexMin` / `IndexMax` are **that frame's own lowest and highest finite index values**. DN 0 is not −1, and full scale is not +1.

Chloros stamps both endpoints so the mapping stays invertible:

| Tag                    | Meaning                                |
| ---------------------- | -------------------------------------- |
| `Chloros:IndexScaling` | `linear_minmax` — the convention below |
| `Chloros:IndexMin`     | the index value stored as DN 0         |
| `Chloros:IndexMax`     | the index value stored as full scale   |

Read them and invert, normalising the stored DN to 0…1 by the stored dtype's max first so that one expression covers every integer format:

```python
import json, subprocess
import numpy as np, tifffile

tags = json.loads(subprocess.run(
    ["exiftool", "-j", "-XMP:all", path],
    capture_output=True, text=True).stdout)[0]

# float(): exiftool hands back a negative real as a quoted string, so
# IndexMin arrives as str on most real NDVI data while IndexMax is a number.
lo, hi = float(tags["IndexMin"]), float(tags["IndexMax"])

raw = tifffile.imread(path)                    # uint16 for TIFF (16-bit)
ndvi = lo + raw.astype(np.float64) / np.iinfo(raw.dtype).max * (hi - lo)
```

Reading needs no `-config pix4d.config` — exiftool reads these XMP properties unaided. The config is only required to *write* them.

> **`IndexMin == IndexMax`** means every pixel of that frame held the same index value. The raster is filled mid-scale and there is nothing to divide by — take the endpoint.

> **No `Chloros:Index*` tags means no stated mapping.** A LUT export is a colourised render whose pixels are gradient colours keyed to your LUT threshold window, and a frame with no finite index pixel has no range to state. Do not assume a mapping in either case — the same rule as a missing `PixelScale`.

**Because the stretch is per-image, two frames of one flight are not comparable as DN** — each carries its own endpoints, so the same NDVI lands on different DN in different images. For quantitative work across a flight (zonal statistics, fixed thresholds, time series), export **`TIFF (32-bit, Percent)`**: index rasters are written there as float32 **index values themselves**, with no rescale and no tags needed. Despite the format's name, index products are not ×100 — that scaling applies only to integer-dtype reflectance.

#### Unmix clamp mask (which pixels a band was clamped on)

The 3×3 spectral unmix can drive a band negative — where the light barely contains that band, or where the scene falls outside what the camera's unmix matrix describes. That is not a real value, so the export pins it to 0 — and the live view shows the same 0. A band can be clamped on a few pixels or on nearly all of them; the mask records either. `Chloros:Band{R,G,B}UnmixClampFraction` says how much of a frame that happened to; the clamp mask says **which pixels**:

* **`clamp_masks/<product folder>/<product name>_clampmask.tif`** — in a `clamp_masks/` folder **beside** the product's folder, never inside it (`radiance/x_radiance.tif` → `clamp_masks/radiance/x_radiance_clampmask.tif`; a `process` export's `tiff16/Reflectance_Calibrated_Images/x.tif` → `tiff16/clamp_masks/Reflectance_Calibrated_Images/x_clampmask.tif`) — for every radiance, reflectance and index product in which at least one pixel clamped: captures and `process` exports alike (and the per-frame TIFFs of `array-build-video --save-tiffs`). Single-band `uint8`, on the product's own pixel grid (orientation, ROI, binning and array alignment included). Each mask names its product's camera (`Make` / `Model` / serial), capture time and lens tags, and lists the bands its bits stand for (`XMP-Camera:BandName`, bit 0 first); its `ImageDescription` and `Software` mark it as a clamp mask, and it carries no calibration.
* **Bits**: bit 0 = the band in the product's R channel (`Chloros:BandRName`), bit 1 = G (`BandGName`), bit 2 = B (`BandBName`). A set bit means that pixel's value in that band was clamped to 0 — treat it, and any index built from it, as low-confidence.
* **`Chloros:UnmixClampMask`** is stamped on every product that ran the unmix: the mask's path relative to the product's own folder (`../clamp_masks/<product folder>/<product name>_clampmask.tif`, always `/`-separated — join it to the image's folder to open the mask), or `none` when no pixel clamped. No tag means the product never ran the unmix (RGB or mono cameras, raw/debayered levels).
* `lattice capture` / `array-capture` print the mask's path under the saved file (`clamp mask: …`), and the capture results list it as the frame's `clamp_mask`.
* `lattice index --live --save-multiband` writes one mask per source camera for the multiband stack — see [`lattice index` — multiband stack masks](#lattice-index--multiband-stack-masks). A video has no mask: `array-build-video` reports each frame's clamp fractions instead (see [`array-build-video`](#array-build-video--offline-reprocess-a-saved-burst)).

Because no product folder holds a mask, at any depth, a product folder (`radiance/`, `reflectance/`, a `process` export's `*_Images/` folder) can be handed to Pix4D, Metashape or other photogrammetry software as it is — subfolders included — and it takes in images only. Hand it the product folder, not the folder above it (that one also holds `clamp_masks/` and every other export type). Chloros' own import skips the masks. Reading a mask: `(mask & 1) != 0` is "the R-channel band was clamped here", `& 2` G, `& 4` B.

#### EXIF carried through to the export

`process` copies the source capture's **GPS block and its ExifIFD** onto every product, so an export carries `FocalLength`, `FNumber`, `ExposureTime`, `ISO`, `DateTimeOriginal` and `CameraSerialNumber` alongside the georeferencing.

**`FocalLength` is not optional for photogrammetry.** Pix4D solves ground sample distance from focal length plus altitude; with the tag absent it falls back to a wildly wrong scale. On one 49-capture orange-grove flight the missing tag turned a 411 m × 160 m site into a reconstructed 47.8 km × 13 km one — a 455 MP ortho of mostly nodata, which then read as a tiling problem and a BigTIFF problem before anyone checked the GSD. If your ortho comes out at an implausible scale, run `exiftool -FocalLength` over the exported product first.

The copy is deliberately **not** `-all:all`: IFD0's structural tags break LATTICE output when copied, and `ExifImageWidth` / `ExifImageHeight` are excluded because they describe the *source* capture — an export that was ever resized would otherwise carry dimensions contradicting its own raster. XMP is written directly rather than copied, because ExifTool discards same-invocation XMP tags when the XMP block is copied (which would drop the MAPIR calibration tags).

### Where the outputs land

Products are written **under the project folder, grouped by camera and then by file format**:

```
<project>/
└── LATT-M3M-L41-F550/                  # one folder per camera model+lens+filter
    ├── tiff16/
    │   ├── Reflectance_Calibrated_Images/
    │   ├── Debayered_Images/
    │   ├── Preview_Images/
    │   └── <INDEX>_Index_Images/        # e.g. NDVI_Index_Images
    └── tiff32/
        └── Radiance_Images/             # float32 radiance always lands here
```

The camera folder is `LATT-<sensor>-<lens>-F<filter>` for LATTICE (matching the capture's EXIF `Model`) and `<model>_<filter>` for Survey3 — two cameras sharing a sensor and filter but differing in lens keep separate trees, because vignette, field of view and distortion differ. The format folder follows `--format`: `tiff16`, `tiff8`, `png8`, `jpg8`, or `tiff32` for `TIFF (32-bit, Percent)`.

> **Every exported product keeps the SOURCE file's name.** A radiance export of `capture_…_raw.tif` is still called `capture_…_raw.tif` — it just lives in `tiff32/Radiance_Images/`. **The folder identifies the product, not the filename**, so globbing for `*radiance*.tif` finds nothing; match on the directory instead.

### Light-sensor recordings — calibrated `.daq` + `.csv`

`process` also handles the `.daq` recordings in your input folder, and it does **not** need any imagery to do it: a DAQ-U / DAQ-M / DAQ-E flown on its own is a complete capture, and a folder holding only `.daq` files is a valid input.

A DAQ can be recorded **without** its calibration — that is what the public [`chloros_scripts`](https://github.com/mapircamera/chloros_scripts) recorders (`record_daq.py`) do by default: they write raw sensor counts and stamp the file so Chloros fetches that sensor's factory calibration **by serial** (local cache first, then MAPIR Cloud) and applies it. `process` writes the result back out:

```
<project>/
└── Light Sensor/
    ├── <name>_calibrated.daq        # reprocessable archive, declares its bundle
    └── <name>_calibrated.csv        # W/m^2/nm per reading + photometric columns
```

The `.csv` carries one row per reading: UTC timestamp, integration time, total power, photopic/scotopic lux, PPFD (and its blue/green/red split), peak wavelength, then the full spectrum on the sensor's own wavelength grid. The `.daq` re-imports without being calibrated a second time.

`<name>` is the recording's own file name. Two recordings in different folders can share one — per-capture readings (`<capture>/daq/daq_data_<sensor id>_<ts>.daq`) saved in the same millisecond by two cameras — and each still gets its own products: the first keeps `<name>`, the next adds the folders that set it apart **after** the name (`<name>__<capture>_daq_calibrated.daq`), so the recording's date and time still lead.

On success the run reports `Light-sensor products written: N (calibrated .daq + .csv)`. The parenthetical describes what was actually written, so it reads `(RAW COUNTS — this sensor has no calibration bundle)` for a bundle-less sensor and `(N calibrated, M raw counts)` for a folder holding both. The backend's own `[DAQ-EXPORT]` and `[RUN-SUMMARY]` headlines derive their wording the same way — none of the three can call a raw export calibrated.

A DAQ-U / DAQ-M / DAQ-E recording whose calibration bundle cannot be fetched — you are offline, or that sensor has no calibration on file — is **skipped with a reason** on a `[DAQ-EXPORT]` line, never written out as a "calibrated" file holding raw counts. Connect to the internet and re-run. The reason is the one the reader actually established for that file (unreadable schema, no bundle, a write error), and the run summary lists **distinct** reasons — twenty files skipped for one cause read as one cause, not twenty repetitions of it. The CLI names each skipped recording at the end of the run, with its reason:

```
⚠ Light-sensor recording not exported: <file>.daq: no calibration bundle available for …
```

A folder of recordings that exports **none** of them fails: see [A run that writes no images fails](#a-run-that-writes-no-images-fails).

A recording whose name ends in `_calibrated` or `_raw` (`field_raw.daq`) is **not imported**: those are the names `process` gives its own products, and a product read back as a recording would be counted twice. The CLI says so and names the file — `Not imported as a light-sensor recording: field_raw.daq … Rename the file to import it.` — instead of reporting an empty folder. Rename such a recording before processing it.

#### DAQ-A recordings export as raw counts

The **DAQ-A** family predates the per-serial bundle system and has no calibration bundle to fetch — it is calibrated in the field against a reflectance target instead, which is why it never needed one. Refusing those recordings left them with no way to get their numbers out at all, so they export under a **different name**:

```
<project>/
└── Light Sensor/
    ├── <name>_raw.daq        # NOT _calibrated
    └── <name>_raw.csv        # raw spectral sensor counts, NOT irradiance
```

A different filename rather than a flag inside the file, because the claim has to survive being emailed on as a bare name. The `.csv` header states `raw spectral sensor counts (NOT irradiance)` and warns that the values are comparable **within** the file — which is exactly what target-based calibration uses them for — and not across sensors. The power-dependent photometric columns (total power, photopic and scotopic lux, PPFD) are written **NULL** rather than integrated from counts, and the run summary says `RAW COUNTS` so "exported" in a log cannot be read as irradiance.

Legacy **v1.01 / v1.02** recordings (a DAQ-A-SD writes these) carry no per-reading epoch, only the file's write time. The image↔downwelling matcher still refuses them — matching a frame against a write time would be wrong invisibly — but the exporter reads them, and the CSV prints `clock=daq_created_on` so the product states which clock it is on.

### Notes

* `process` automatically detects whether your folder is Survey3, LATTICE, or mixed.
* Progress streams over Server-Sent Events; the CLI shows live per-thread progress (Detecting, Analyzing, Processing, Exporting).
* For Linux/Jetson, the CLI checks swap and may warn before processing large folders. Texture-aware debayer also auto-applies a GPU frequency cap on low-power Jetsons (Nano, Orin Nano).
* On success the run reports how many image products it wrote (`Image products written: N`, with `(plus M clamp masks)` when the unmix clamped any pixel).
* **`process` shares a running backend safely.** It restarts an already-running backend automatically only when that backend is idle with a previous project loaded and holds no cameras, arrays or DAQs. A backend that holds any of them (the GUI streaming an array, an SDK script, a DAQ recording) is used as it is, never restarted, so `process` can run next to a live array. If the backend reports a run in progress, `process` waits up to 15 s for it to finish (a run that has just completed takes about a second to clear), then refuses with `Backend is mid-run (processing). Wait for it to finish, or pass --restart to force a fresh backend (this kills the in-flight run).` The global `--restart` flag still forces a fresh backend, and ends any camera, array or DAQ session on it. A backend a Linux systemd service runs is never restarted: `process` uses it, and `--restart` prints `sudo systemctl restart <unit>` instead (see [Running the backend as a service](#running-the-backend-as-a-service-headless)). Nor is the Chloros app's own backend: with the app open, `process` uses it, loading its project in place of the app's (a backend started in its place would lock the open app out of it).
* **A run in flight keeps its project.** While a processing run is in progress — started by the app, `process`, an SDK script or `chloros-mcp` — the backend refuses to create, open, import into, add or remove files of, move, delete or change the processing settings of a project, with HTTP 409 `PROCESSING_IN_PROGRESS` and `A processing run is in progress on project '<name>', so ... now is refused`; a `process` that gets it exits `1`. Display settings (thumbnail size) still save. The processing mode and the project's target-reflectance settings are refused the same way (a run keeps the mode it started in). A capture saved into the project mid-run (from the app, the CLI, the SDK or `chloros-mcp`) is saved as usual, but joins the project's file list only when the run ends; its reply says so (`project_add`), and so does a light-sensor recording stopped into the project. Before, a second client could switch the open project mid-run, and the running run exported into the other project.
* **Ctrl+C stops the run in the backend, not just the CLI.** The CLI asks the backend to stop processing, prints `Waiting for the backend to stop (Ctrl+C again to stop waiting)...`, and waits up to 120 s for `Processing stopped.`, so `chloros-cli process … && next` does not start `next` on a backend still busy with the run. A second Ctrl+C ends the wait. `process` then exits `130`, as any interrupted command does.

#### A run that writes no images fails

If you asked for products and the run wrote **none** — only `project.json` and `calibration_data.json` — `process` treats that as a failure: it prints `Processing finished but wrote no image products.` and **exits non-zero**, so a script can detect it. The message names the project folder and the usual causes:

* the input folder wasn't recognised as a capture (check the layout and `--input-level`), or
* every requested product was skipped as inapplicable for those cameras (e.g. asking for radiance/reflectance from RGB-only cameras).

Re-run with `--verbose` and check the backend log for `[LATTICE-EXPORT]` / `[EXPORT-CHECK]` lines, which explain per-camera skips that don't otherwise reach the CLI's output.

A deliberate metadata-only run — every product toggle off and no `--indices` — is still a **success**, because an empty image output is the correct result there.

#### A run whose exports could not be verified fails

After a run, `process` checks the exported files' tags with ExifTool. If ExifTool could not run, it prints `Export verification FAILED: ExifTool could not run, so the tags of N of M exported file(s) were not checked (see the [EXIFTOOL] lines in the backend log)` and `The products are written and stay in place; re-run to verify them.`, does not print `Processing complete!`, and **exits non-zero**. The products are kept.

#### Which captures a run takes

Captures finished before `process` is run are included. Captures saved during the run are not; `process` warns how many were left out, and running it again includes them.

#### A run that lost an image fails

If an image failed during a run, `process` prints `N image(s) failed and were not exported` with the commonest cause, does not print `Processing complete!`, and **exits non-zero**. The other products are written and stay in place, and the backend log has each failure.

So is a **light-sensor-only run**: a folder of `.daq` recordings has no imagery to export by definition, and the run is judged on the calibrated `.daq` / `.csv` it wrote instead. If it wrote **none** — every recording was skipped — it prints `Processing finished but wrote no light-sensor products.`, names each recording with the reason it was skipped, and **exits non-zero**.

***

## `chloros-cli login`

Authenticate this machine with a Chloros+ cloud account. Credentials are cached securely in `~/.chloros/user_session.json`.

```
chloros-cli login EMAIL PASSWORD
```

### Examples

```bash
chloros-cli login user@example.com 'YourPassword'

# Passwords containing $ should use SINGLE quotes
chloros-cli login user@example.com 'my$ecret$pass'
```

> **PowerShell `$$` mangling is auto-corrected.** In double quotes PowerShell expands `$$` (stripping it from, or duplicating parts of, the password). On a 401 the CLI automatically retries with `$$` re-appended, then with a de-duplicated half of the password; if a retry succeeds it logs you in and prints the correct single-quote syntax to use next time.

> **Headless/scripted use: no cached session means a login prompt.** A core command (`process`, `status`, `export-status`, `time-sync`, …) run without a cached session asks for `Email:` / `Password:` on stdin before proceeding. With stdin closed (cron, a systemd unit) it fails at once with `login cancelled`; with stdin an open terminal or pipe it waits for input. Run `chloros-cli login EMAIL PASSWORD` once per machine before scheduling headless work.

***

## `chloros-cli logout`

Clears the cached session and forces a fresh login on the next call.

Signing out while a processing run is in progress does not stop it: the run finishes in the processing mode it started in, and the next run uses standard processing. `logout` says so (`The processing run in progress finishes in <mode> mode; the next run uses standard`), and so does the app when you sign out there.

```bash
chloros-cli logout
```

***

## `chloros-cli status`

Show the current license tier (Iron/Copper/Bronze/Silver/Gold), authenticated user, and device-binding count.

```bash
chloros-cli status
```

***

## `chloros-cli export-status`

Poll the live Thread-4 export progress. Safe to call **during** a `process` run from another shell.

```bash
chloros-cli export-status
```

***

## `chloros-cli language`

Set the CLI's display language (38 supported, including CJK, RTL, and Indic). Falls back gracefully to English on legacy consoles that can't render the script.

```
chloros-cli language [LANG_CODE] [--list]
```

### Examples

```bash
# List all available languages
chloros-cli language --list

# Switch to Spanish
chloros-cli language es

# Show the currently-active language
chloros-cli language
```

***

## Project Folder Commands

These manage the default project folder location (shared with the GUI).

```bash
chloros-cli set-project-folder "/home/user/Chloros Projects"
chloros-cli get-project-folder
chloros-cli reset-project-folder
```

`get-project-folder` prints the folder new projects go to. If the configured folder no longer exists (it was deleted, renamed, or is on a drive that is not connected), the CLI falls back to the default folder, as the GUI does: the default folder is printed on stdout, a warning naming the missing folder goes to stderr, and the exit code is `0`.

***

## `chloros-cli update`

Linux / Jetson only. Checks `version_url` from `/etc/chloros/update.conf` and, when a newer version exists, downloads the matching `.deb` and installs it with `sudo dpkg -i` straight away (no confirmation prompt; `sudo` may ask for your password). On a Jetson only a JetPack 6 system is offered the update. On Windows the command does nothing and reports `up to date`: update with a new installer.

```bash
chloros-cli update            # check + install
chloros-cli update --check    # check only
```

On Linux/Jetson the CLI also runs an **automatic update check on every startup** (non-blocking, never delays the command): it reads `/etc/chloros/update.conf`, caches the result for 1 hour in `~/.chloros/update_cache.json`, and prints `Update available: vX.Y.Z / Run: chloros-cli update` when a newer version exists. Silently skipped on any error and on Windows; `CHLOROS_DISABLE_UPDATE_CHECK=1` turns it off. Because of the 1-hour cache, a release published within the hour can still read as up to date.

***

## `chloros-cli selftest`

Runs a 7-step smoke test: version, port availability, backend startup, `/api/test`, `/api/system-info` (GPU/CUDA/PyTorch), denoiser model presence, CUDA+denoiser readiness. It uses a running backend, or starts one for the test and stops it afterwards. It prints `N/7 checks passed` and the failed checks, and exits `0` only when all seven pass; the CUDA+denoiser check fails on a computer without a CUDA GPU (see [Verify the Install](#verify-the-install)).

```bash
chloros-cli selftest
```

***

## `chloros-cli time-sync`

PTP grandmaster status and control. The Chloros host runs the PTP grandmaster; LATTICE cams and DAQ-E units slave to it for cross-device timestamps (about 1 ms across devices). PTP aligns **timestamps**: the cameras of an array expose together because the M8 hardware trigger fires them (under 100 µs between modules), not because of PTP. `chloros-cli time-sync` with no subcommand runs `status`.

| Subcommand                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                                   | Show grandmaster state, BMCA priorities, clock identity, and whether its packets are reaching the network: `health` is `OK` (`STOPPED` when the grandmaster is not running), or `SENDS_FAILING` / `DEGRADED` / `NO_SOCKETS` / `PEERS_SILENT` with a `health_detail`, and then a `WARNING:` line is printed to stderr (stdout stays JSON). `sync_sent` / `announce_sent` count only messages that left; `*_send_errors` and `last_send_error` count the ones that did not. After a camera link drops and comes back, the grandmaster rebuilds its sockets by itself (`rebinds`, `last_rebind`). |
| `peers`                                    | List slaves seen via Delay\_Req (cameras + DAQ-E sensors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cameras`                                  | Per-camera PTP health (`PtpStatus`, `PtpOffsetFromMaster`, `PtpMeanPathDelay`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `restart`                                  | Restart the grandmaster process.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `set-priority --priority1 N --priority2 N` | Override BMCA priorities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

The grandmaster announces on the camera NICs (any adapter with a `169.254.x.x` address included). With none up it falls back to the adapter of the default route only when that is wired, never Wi-Fi or a virtual adapter (Tailscale, WSL), since no camera or DAQ-E sits behind one. With nothing to announce on it runs with no sockets (`health` `NO_SOCKETS`), and the next camera or DAQ connect rebuilds it on the NIC that is up by then; `time-sync restart` does it at once.

The grandmaster runs in a process of its own, beside the backend (`own_process` / `process_pid` in `time-sync status`), at high priority on Windows (`process_priority`), so a busy backend (a processing run, an export, several commands at once) cannot delay the times it stamps; before, one such delay could move every camera's clock at once. That process ends with the backend; if it cannot be started the grandmaster runs inside the backend as before (`own_process` false, and the backend log says so).

### Examples

```bash
chloros-cli time-sync status
chloros-cli time-sync peers
chloros-cli time-sync cameras
chloros-cli time-sync restart
chloros-cli time-sync set-priority --priority1 1 --priority2 1
```

***

## `chloros-cli lattice`

LATTICE camera control. Every subcommand routes through the Chloros backend; the backend owns the cam pool so subsequent CLI calls reuse the same open handle.

### Common Options (shared by most subcommands)

| Flag                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-d, --device N`                                       | Camera index (default: 0).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `-s, --serial SN`                                      | Specific serial; overrides `--device`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--serials SN1,SN2,…`                                  | Comma-separated serials for multi-cam operation. The [transient multi-camera commands](#multi-camera-transient-sessions) open only these cameras, the first firing the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--all`                                                | Operate on every discovered camera.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--exposure US`                                        | Exposure time in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--gain DB`                                            | Gain in dB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--pixel-format FMT`                                   | e.g. `BayerRG8`, `BayerRG12`; `Mono8`, `Mono12` on an M3M. The name sets its bit depth in the camera's own family: on an M3M a Bayer name sets the Mono format of its depth (`BayerRG8` sets `Mono8`), on an M3C a Mono name the Bayer one (`Mono12` sets `BayerRG12`).                                                                                                                                                                                                                                                                                                                                                                               |
| `--width N` / `--height N`                             | Image dimensions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--preset {default,high_quality,high_speed,triggered}` | Apply a settings preset: its pixel format, exposure, gain and frame rate (`high_speed`: `BayerRG8`, 5 ms, 6 dB, 60 fps; `high_quality`: `BayerRG12`, 20 ms, 0 dB; `lattice presets` lists them). On an M3M the format is the Mono one of the same depth: `high_speed` captures `Mono8`, `high_quality` and `triggered` `Mono12`. A flag given with it (`--exposure`, `--gain`, `--pixel-format`) wins over the preset, and a setting the preset does not name keeps the camera's own. All free-run except `triggered`, which arms the camera for a hardware edge on Line 2 — with nothing driving that line it will wait forever rather than capture. |
| `-o, --output DIR`                                     | Output directory (default: `output`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--packet-size {auto,jumbo,standard,N}`                | GVSP packet size. `auto` runs ICMP+GVSP probes; `jumbo` = 9000; `standard` = 1500.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### LATTICE Camera First-Connect Workflow

```bash
# 0. A backend must be running: the Chloros desktop app (Windows),
#    `chloros-backend`, or the Linux service (see "Start the Backend")

# 1. Discover cameras on the network
chloros-cli lattice info

# 2. Single-cam smoke test: capture one frame.
#    By default this saves EVERY export type applicable to the cam
#    (raw, debayered, radiance, reflectance, preview). Pass e.g.
#    `--processing debayered` to save just one.
chloros-cli lattice capture -o output/

# 3. Connect a synchronized array (RECOMMENDED ENTRY POINT for arrays).
#    This is the same "smart-prep" flow the Chloros GUI uses:
#      - Network capability probe (ICMP DF ping + GVSP probe)
#      - Tier auto-pick (sim-emit / ftd-stagger / slip)
#      - Full sensor (no binning, no ROI); the frame rate falls to
#        what the host and wire deliver, and the faster options are
#        printed
#      - PTP enabled by default
#      - Per-cam pixel format auto-pick
#      - AE seeding from the cam's saved state
#      - GPIO trigger config on Line2
chloros-cli lattice array-connect \
  --serials 213800234,214000533,214701288,214701292

# 4. Capture one synced frame group from the live array.
#    Defaults to --processing all (one file per export type per cam);
#    pass a single level to narrow it, e.g. --processing reflectance.
chloros-cli lattice array-capture --processing reflectance -o output/

# 5. Live-preview one cam in your browser
chloros-cli lattice viewer --serial 213800234

# 6. Tear down when done
chloros-cli lattice array-disconnect
```

### Subcommand Reference

#### Discovery & Information

| Subcommand                                                                                                                                                                                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lattice info`                                                                                                                                                                                          | List connected cameras (vendor, model, serial, IP, MAC).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lattice probe [--pixel-format FMT] [--json] [--no-discover]`                                                                                                                                           | Analyse host system for optimal camera configuration. `--no-discover` skips camera discovery (faster, NIC-only analysis).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `lattice network [--fix] [--estimate] [--cameras N] [--pixel-format FMT]`                                                                                                                               | Check/fix NIC settings (on Linux, also the kernel's socket receive buffers — see [Linux hosts](#linux-hosts--socket-receive-buffers)); estimate bandwidth/FPS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `lattice network-analysis --master SN [--slaves SN1,SN2,…] [--width N] [--height N] [--pixel-format FMT] [--binning {1,2,4}] [--force-tier TIER] [--packed {auto,on,off}] [--backend-url URL] [--json]` | Stable-schema backend network-capability + array recommendation (returns `status` ∈ `ok` / `auto_shrunk` / `auto_capped_fps` / `needs_force_slip` / `error`). `--width` / `--height` default to the full sensor, `2048` × `1536`. It exits `0` for `ok`, `auto_capped_fps` and `auto_shrunk`, and `1` for `needs_force_slip` and `error`, with or without `--json`. It reaches the backend at `--backend-url` (default `http://127.0.0.1:5000`), not `CHLOROS_BACKEND_URL`. `auto_capped_fps` keeps the requested resolution but caps the target fps — read `recommended.recommended_target_fps` and pass it as the connect target; treat it as success, not an error. `auto_shrunk` appears only when the requested frame cannot be delivered at any frame rate; connect never shrinks frames on its own.                                                                                                                                                                       |
| `lattice analyze-array [--models M1,M2,…] [--binning {1,2,4}] [--n-active N] [--width N] [--height N] [--pixel-format FMT] [--force-tier TIER] [--packed {auto,on,off}] [--json]`                       | What-if analysis without opening cameras (`--width` / `--height` default `2048` × `1536`). Both this and `network-analysis` project what connect will stream: with no `--pixel-format`, the per-camera formats connect applies (Mono12 / BayerRG12), and with `--packed auto` (default) the [packed 12-bit](#packed-12-bit-transport---packed) decision connect would make on this computer — so the fps quoted is the rate the array runs at. Both print the packing decision. **`--n-active` is the total number of cameras on the wire, not just this array's** — raise it when standalone cameras stream concurrently, or the wire budget is computed against a demand that under-counts them (default: `len(--models)`). Always prints the aggregate `Wire budget:` (MB/s demanded vs collision-safe ceiling) and `Max cameras:` lines, and flags `** OVER-SUBSCRIBED **` when the array over-subscribes the wire — see [Array fps & burst model](#array-fps--burst-model). |
| `lattice gpu`                                                                                                                                                                                           | Show GPU status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `lattice firmware [--update] [--force] [-y\|--yes]`                                                                                                                                                     | Check or update camera firmware. Local `.fwa` selection is pinned: the file in `firmware/<MODEL_PREFIX>/` matching the build's `MIN_FIRMWARE_VERSION` is flashed when present (highest version only as a fallback), so a newer vendor image staged on disk is inert until that pin is bumped — deliberately newer releases reach units via the signed AWS manifest, which is preferred when newer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `lattice presets [--apply NAME]`                                                                                                                                                                        | List or apply camera presets. `--apply` sets what the preset names (its pixel format, exposure, gain, frame rate, trigger) and prints those settings as the camera reads them after: on an M3M, the Mono format of the preset's depth; the frame rate it runs at, which can be lower than the preset asks (`high_speed` asks 60 fps; a full-frame camera on a 1 Gbps link runs about 35). Every other setting its open wrote goes back as found. `--apply default` resets the camera to its factory defaults: its factory settings with free-running auto exposure on Line2, the link throughput limit and defect correction off, an RGB camera's calibrated white balance kept (unity on any other). Nothing is saved to the camera's memory, so at its next power-up it starts from its own memory as before. As a capture's or connect's `--preset`, `default` is no preset.                                                                                                  |
| `lattice status`                                                                                                                                                                                        | Live camera status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

#### Capture

| Subcommand                                                                                                                                           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lattice capture [--format tiff\|tif\|png\|jpg\|jpeg] [--jpeg-quality N] [--processing LEVEL] [--levels L1,L2,…] [--no-daq] [--daq-tolerance-ms MS]` | Single frame. **Saves every export type by default** (`--processing all`); see [Capture Export Levels](#capture-export-levels-the-all-default). `--processing` takes `all`, `raw`, `debayered`, `radiance`, `reflectance` or `display` (`preview` is accepted for `display`); any other name is refused before the camera is touched (exit `1`). `--levels` saves an explicit subset (overrides `--processing`). A camera Chloros does not hold is opened for the capture, and its exposure is set from the scene first (a few seconds at most), as the [transient commands](#multi-camera-transient-sessions) do; when the capture ends, however it ends, that camera is put back as it was found (format, exposure, colour pipeline, every setting the capture changed — the list under [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions)). The DAQ reading the capture used is saved as a `.daq` sidecar, a raw-only grab included; `--no-daq` / `--daq-tolerance-ms` adjust it ([The DAQ reading a capture saves](#the-daq-reading-a-capture-saves)). `--force-daq` is still accepted. `--jpeg-quality` = JPEG quality 1–100 (default 95). **Files saved into the open project join it.** As in the app, a capture whose files land inside the folder of the project open in Chloros adds them to that project's file list; files saved elsewhere are left alone. The command prints one line saying so (`Project: ...`), or, while a processing run is in flight, that they are held back and join when the run ends. So do `multi-capture`, `array-capture` (`--smart` too) and `project capture`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lattice continuous [--format tiff\|tif\|png\|jpg\|jpeg] [--jpeg-quality N] [--queue-depth N] [--no-daq] [--daq-tolerance-ms MS]`                    | Stream to disk until Ctrl+C. A `tiff` run's frames are the `raw` file an array capture writes of that camera: the sensor's mosaic, one plane at its own values, uncompressed, with the calibration packet (a 2048 x 1536 12-bit frame is 6.0 MiB plus the packet, whatever the scene), so `process` starts from them. `png` and `jpg` hold 8 bits, so those runs are demosaiced frames for viewing, which `process` does not start from. With a DAQ bound (`daq pool-bind`) or pooled, each frame gets its own `.daq` and `.match.json` in the run's `daq/` folder, as `lattice capture` saves one; `--no-daq` turns that off, and the stop prints how many. Each frame is written once, with its full metadata; on Ctrl+C the frames already grabbed are written before the camera is released. Stops itself when the drive fills, prints `Failed:` / `Disk full:` and exits `1`; any frame it could not write also exits `1`. A camera left armed for a hardware trigger (`TriggerMode` `On`) is set to free-run for the run. When the run ends the camera is put back as it was found — its trigger settings and every setting the run changed (exposure, gain, format, …) — unless `--keep-settings`, which saves the run's settings into the camera's own memory (free-running), or `--clear-settings`, which resets that memory to the factory settings. A run that records no frame is a failure: with no frame for 10 s it stops itself, prints `No frames:` with the reason and exits `1`. Frames the writers could not keep up with are counted as dropped, and the stop prints `Dropped:` with why (the camera's frame rate, the writers' and the queue); a lower frame rate or an 8-bit pixel format keeps them all. The command checks in with the backend every 2 s; if it dies without stopping the recording (`kill -9`, out of memory), the backend stops it 30 s after the last check-in and puts the camera back (`stop_reason` `client_gone`, and a line in the backend log). `multi-stream` and `align-stream` do the same. A start whose camera takes longer to open than the command waits (60 s; 180 s for `multi-stream` / `align-stream`) — a camera still booting — is undone by the backend: the camera is put back and closed and no recording is left running (HTTP 504 `CLIENT_DEADLINE_PASSED`). |
| `lattice viewer [--brightness N] [--ae-damping F] [--frame-rate FPS]`                                                                                | Browser-based live MJPEG preview: connects the camera, prints the stream URL and opens it in your browser. `--ae-damping` sets auto-exposure damping (0.4–100).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

**Live streams (MJPEG; no RTSP)**

Chloros serves live video as **MJPEG over HTTP** (`multipart/x-mixed-replace`, boundary `frame`) from the backend. **RTSP is not supported.** Open a URL in a browser, or read it with any MJPEG client (OpenCV's `cv2.VideoCapture(url)`, ffmpeg, VLC). The camera must be connected in the backend first (`lattice cam-connect`, `lattice array-connect`, `lattice viewer`, or the GUI).

| URL (`http://127.0.0.1:5000` + …)         | Stream                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/camera/stream/<serial>`             | The display preview, up to about 30 fps. For an array member, `?max_h=` (default `720`) and `?jpeg_q=` (default `80`) set the height and JPEG quality. This is the URL `lattice viewer` opens.                                                                                                                                                               |
| `/api/camera/<serial>/stream-annotated`   | The same preview with the GUI's overlays drawn in: `zebra=1`, `crosshair=1`, `grid=3x3` (or `9x9`), `histogram=1`, `peaking=1`, `spot=1`; with no query, the project's saved overlay settings for that camera.                                                                                                                                               |
| `/api/camera/<serial>/stream-reflectance` | 8-bit per-band reflectance: ρ = pixel ÷ the part's `X-Chloros-Pixel-Scale` header (255 unless `refl_max` is raised). `fps` (default `10`), `jpeg_q` (default `95`), `max_h` (default `0` = native), `band=<name>`, `align=1`. JPEG, so lossy. Refused with HTTP 409 when the camera has no reflectance (an RGB camera, no calibration pack, no DAQ reading). |

* **Matching frames across cameras.** Every part an **array member** sends, on all three streams, carries `X-Chloros-Group-Id` (the array's synced-group counter), `X-Chloros-Frame-Id` and `X-Chloros-Timestamp-Ns` headers. Parts from different cameras with the same `X-Chloros-Group-Id` come from the same trigger. A standalone camera has no group and sends no group id. Browsers ignore per-part headers; a client that parses the multipart stream itself reads them.
* **Paused while the array view is open.** `/api/camera/stream/<serial>` of an array member sends a static "paused" frame while the array's combined live stream is open (for example, the GUI's array view), and resumes when it closes.

#### Sensor Tuning

| Subcommand                                                                                                                                        | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lattice configure [{--get N1 N2… \| --set N=V N=V… \| --dump}] [--json]`                                                                         | Read/write any GenICam node. `--set ExposureTime=…` (`Gain=…`) without its `ExposureAuto` (`GainAuto`) switches that auto mode Off first, as `lattice exposure --set` does; a value the camera refuses prints `Failed to set <node>: …` on stderr and exits `1`. `--get` and the default grouped view print a `note:` under `ExposureTime` / `Gain` while that auto mode runs — see [Reading exposure and gain under auto mode](#reading-exposure-and-gain-under-auto-mode).                                                                                                                                                                                                                                                                                                                                                                                                        |
| `lattice exposure [{--auto \| --auto-once \| --off \| --set US}] [--brightness 0-255] [--brightness-auto] [--damping 0.4-100] [--upper-limit US]` | Exposure & AE. A `--set` exposure or `--brightness` target is held as yours (Chloros's automatic exposure control leaves it alone); gain stays as it was, so on auto it keeps adjusting toward the target until you set `lattice gain`. `--auto` hands exposure back, `--brightness-auto` hands the target back to Chloros's automatic target. With no flags it reads the exposure nodes, with the same `note:` as `configure --get`. A `--set` value the camera refuses prints `Failed to set ExposureTime: ExposureTime=<value> refused (<camera error>); the camera accepts <min>..<max> now (ExposureAuto put back to <mode>)` on stderr — the auto mode the write switched off is restored rather than left Off — prints no `Exposure: … us (auto OFF)` line, and exits `1`.                                                                                                   |
| `lattice gain [{--auto \| --off \| --set DB}]`                                                                                                    | Gain & auto-gain. A `--set` value the camera refuses prints `Failed to set Gain: …` on stderr, no `Gain: … dB (auto OFF)` line, and exits `1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `lattice resolution [--set WxH] [--offset X,Y] [--binning N]`                                                                                     | Sensor ROI & binning. Binning is always **Average** — see below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lattice format [--set FMT] [--list]`                                                                                                             | Pixel format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lattice trigger [--mode On\|Off] [--source SRC] [--delay-us US] [--activation EDGE] [--list-sources] [--software]`                               | Hardware/software trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `lattice white-balance [--auto] [--off] [--red R] [--blue B]` (no flags = one-shot WB)                                                            | WB operations. RGB/Bayer cams only; a no-op (skipped) on mono M3M. The one-shot keeps the white balance it solves (`BalanceWhiteAuto` and the gains); every other setting its open wrote goes back as found, and all of it when the one-shot cannot run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `lattice color-profile [--set raw\|linear\|natural\|enhanced\|custom_temp] [--cct 2000-10000] [--get]`                                            | RGB display colour pipeline. `natural` (default) is the cheap live finish; `enhanced` adds defringe + vibrance + CLAHE local contrast for the full hub-parity look at \~2× the per-frame finish cost, so a lower **live** framerate — saved captures always get the full finish either way. RGB/Bayer cams only; skipped on mono M3M.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `lattice color [--saturation 0-200] [--contrast 0-200] [--reset] [--get]`                                                                         | Live-preview saturation/contrast (RGB filter cams); `100` is neutral, `--reset` sets both to 100. Saved captures are not affected. Skipped on mono M3M.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `lattice highlights [{--set -100..0 \| --reset \| --get}]` (no flags = read)                                                                      | Display **Highlights** (RGB filter cams): pull the brightest, whitest pixels down — e.g. a bright white surface that renders as a flat white blob. `0` = off, `-100` = strongest. The live preview and display-level captures follow it; radiance/reflectance never do, and it cannot recover sensor data that clipped (lower the exposure for that). Skipped on mono M3M.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `lattice filter [--list]`                                                                                                                         | List the filter models Chloros knows (`RGN-IMX265`, `OCN`, `NGB`, …). A camera's filter is read from its model string and cannot be set: `--set NAME` only looks a model up, then exits `1` with `setting the filter model is not supported`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lattice power [--sleep]`                                                                                                                         | Probe power/thermal nodes; toggle low-power idle. `--sleep` leaves the camera asleep (its link throughput limit turned on (`DeviceLinkThroughputLimitMode` `On`) at its floor, the power-saving mode on where the camera has one) with every other setting its open wrote put back as found first; a sleep that fails is put back whole. The wake puts the link back as the sleep found it (the limit, its mode, and the packet delay `GevSCPD`, which the camera holds at 0 while the limit is on; the record is kept on this computer, so a wake after the backend restarted finds it too), or, for a camera this computer did not put to sleep that looks asleep (its limit on at the floor), with the limit off and a `GevSCPD` left at 0 at 80 (the factory settings); a limit set on above the floor is left as it is. The probe and the wake put back what their open wrote. |

> **Binning is always Average.** `lattice resolution --binning N` sets Average binning and does not offer a mode switch. Sum binning multiplies every DN by N², costing roughly two stops of highlight headroom per binning step; Chloros divides that factor back out before the radiometric chain, but pixels Sum drove into the sensor's ceiling are clipped and cannot be recovered. It buys nothing Average does not — an index is scale-invariant and the radiance scalars are calibrated at the Average scale. If a camera arrives already set to Sum (left there by another tool, or by a factory reset), Chloros detects it from a node readback and compensates; running `lattice resolution --binning N` puts it back on Average. The 1.2.0 `--binning-mode` flag is still accepted so older scripts run, but it only prints a warning: binning stays Average.

> **Change binning, pixel format and trigger on a camera nothing holds.** On a camera the backend holds open and streams (`cam-connect`, the GUI), `lattice resolution --binning` does not take effect (it prints the binning still in force, `Binning: 1x1`), and `lattice format --set` and `lattice trigger --mode` are refused by the camera (`SC_ERR_ERROR -1001`). Release it first (`lattice cam-disconnect -s <SN>`), or set them at connect (`cam-connect --pixel-format …`, `array-connect --binning …`).

**Reading exposure and gain under auto mode**

While a camera's `ExposureAuto` (`GainAuto`) is running, its `ExposureTime` (`Gain`) node keeps the **last value written**, not what the camera is doing now. For a camera the backend holds open (`cam-connect`, `array-connect`, the GUI), `lattice configure --get`, the default `lattice configure` view and `lattice exposure` (no flags) therefore print the node value and, under it, a note with the camera's newest frame:

```
ExposureTime = 2000.448
  note: ExposureAuto is Continuous: ExposureTime holds the last value written (2000.448); the camera's newest frame was at 4900 us.
```

Read the frame value from the note; the node value is only the last write. Over HTTP the same `POST /api/camera/<serial>/read-nodes` reply keeps `nodes` unchanged and adds `frame_values` (`{"ExposureTime": <us>, "Gain": <dB>}`, the newest frame's) and `notes` (the sentence above). Both are present only while the auto mode is not `Off` and a frame is known; a camera opened just for the read has no frame and gets neither. `lattice gain` (no flags) prints the node only — use `lattice configure --get Gain` for the note.

**Exposure on an array member**

While an array streams, each member runs with **`AcquisitionFrameRateEnable` on**, at a frame rate a little above the array's trigger rate: its period is the trigger period less 15 % (at least 3 ms), or the camera's own maximum rate when the trigger is already close to it. `configure --get` on a member therefore reads `AcquisitionFrameRateEnable` as `True` and `AcquisitionFrameRate` at that setting; the enable goes back off when the array stops. **Do not write these two nodes on an array member** — the array keeps them in step with its trigger and rewrites them.

That setting is also the member's exposure ceiling: about 85 ms at a 10 fps trigger (100 ms period), at **any ROI or binning**. Before 1.3.0 a small ROI capped a member's exposure at the sensor's free-run period instead (4.9 ms at 768 × 304), however slowly the array triggered.

**A manual `ExposureTime` longer than the ceiling slows the trigger to fit it** when it is written with `lattice exposure --set` or `configure --set` (or from the GUI). The array first opens that member's ceiling for the value and lets the slower rate run a few trigger periods, so the write can take a few seconds longer; the trigger then fires no faster than the exposure allows. On an auto-rate array the rate it ran before comes back once every member whose manual exposure slowed it is back on auto exposure. A value the camera itself cannot take is still refused, with the range it accepts in the error, and the member's auto exposure is put back if it was switched Off only for that write. A recipe `apply` exposure does not slow the trigger: it is held to the ceiling. Chloros never shortens a manual exposure to fit a faster trigger; a pinned rate (`array-connect --target-fps F`) faster than an exposure allows leaves that member a ceiling long enough for it, and that member takes triggers no faster than its exposure allows.

#### Calibration & Sensors

| Subcommand                                                                                                   | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lattice calibrate [--filter NAME] [--attempts N] [--save PATH]`                                             | Calibrate from a reflectance target. Up to `--attempts` frames (default `30`) are searched for it; an incomplete frame (GVSP packet loss) costs one attempt, not the run. It fails with `no target detected in N attempts`, or `no complete frame in N attempts: <last error>` when no frame arrived whole.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `lattice dls {--connect \| --spectrum \| --irradiance} --mac MAC [--filter NAME] [--camera SERIAL] [--json]` | A DAQ-M's spectrum and band magnitudes, read over Bluetooth (BLE) through the backend. `--mac` is the sensor's own BLE MAC and is required with any of the three actions: there is no default, since every unit has its own (`daq pool-discover --only ble` lists them); without it the command exits `1`. With no action it prints its help. `--camera SERIAL` integrates the printed band magnitudes through that camera's own measured spectral response instead of the filter model's fleet curve — RGB cameras, with the camera's calibration pack loaded (connected) or cached on this computer. The heading says whose curve was used: `Band magnitudes (camera <SERIAL>):`, or `Band magnitudes (model <filter>):` when the camera has none (not an RGB camera, or no pack loaded or cached) and the fleet curve was used instead. Over HTTP, `POST /api/dls/cli-read` takes `camera_serial` and returns `band_magnitudes_source`. |
| `lattice vignette --input DIR --output DIR [--lens-model KEY]`                                               | Apply vignette correction to existing images, each with its own lens's flat field (from its EXIF Model). `--lens-model` applies to images whose Model names no camera; an image whose Model contradicts it is skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

#### Multi-Camera (Transient Sessions)

A transient command opens the cameras for one run and closes them when it ends: `multi-capture` with no persistent array connected, `multi-stream` and `multi-test` here, and `align-calibrate`, `align-apply`, `align-stream` and `index --live` below. These rules hold for all of them:

* **`--serials SN1,SN2,…` chooses the cameras.** Only those are opened, and the first fires the trigger (for `align-calibrate`, `--reference` when given). A serial that is not on the network fails the run before any camera is opened. Without `--serials`, every camera on the network is opened. A camera Chloros already holds (the GUI, `cam-connect`, `array-connect`) refuses the run whether `--serials` names it or not: it shares the network the run is paced for. (`index --live` without `--serials` opens its profile's enabled cameras instead: see [Index / Vegetation Maths](#index--vegetation-maths).)
* **The cameras share the network the way `array-connect` shares it.** Each camera is paced to its share of what the host link carries (an inter-packet delay, not the camera's throughput limit, whose 31.25 MB/s floor four cameras on 1 GbE already exceed), so four cameras run on a 1 Gbps link. When the cameras cannot all send at once at the slowest pace they reach, they are triggered one after another, each with the link to itself, and the command prints `Serial emit: the wire cannot carry these cameras at once, so each is triggered <ms> ms after the one before; their frames are not exposed together`. When even one camera at a time does not fit, the run is refused before any camera streams: `array over-subscribes the wire: <n> cameras demand <x> MB/s but the collision-safe ceiling is <y> MB/s. …`, HTTP 409, exit `1`.
* **Every camera delivers, or the run fails.** A camera that delivers no frame is an error: the command prints `Error: … no frame from <n> of <total> cameras: SN:<serial> (<why>), …`, where `<why>` is that camera's fetch error, then what the causes point to, and exits `1`. A frame that arrived with GVSP packet loss (`IncompleteBufferError: GVSP packet loss …`) means the network is not carrying the cameras' combined bandwidth (`Every missing frame arrived with GVSP packet loss: …`): check the link speed of the host and of the switch's uplink (`lattice network`), use jumbo frames, or open fewer cameras with `--serials`. A camera that delivered nothing is usually not getting the master's trigger: check its M8 sync cable, then run `lattice multi-detect`. What each command does with a frame group missing a camera is in its row.
* **Each camera is put back as found.** When the run ends, every camera gets back what it had when the run opened it: `TriggerMode`, `TriggerSource`, `TriggerActivation`, `TriggerOverlap`, `TriggerDelay`, and `LineMode` / `LineSource` on `Line2` and `Line3` (and the trigger-input deglitch an array gives a slave's line, `LineFilterSelector` / `LineFilterWidth`); its `PtpEnable` (and the `PtpSlaveOnly` / `PtpDomainNumber` set with it); `ExposureAuto` / `GainAuto` (and `ExposureTime` / `Gain` where it was on a manual value); `TargetBrightness`, `ExposureAutoLimitAuto` / `ExposureAutoUpperLimit` / `ExposureAutoLowerLimit`, `GainAutoUpperLimit`, `ExposureAutoDamping`; `BalanceWhiteAuto` (and each `BalanceRatio` where white balance was manual); `BlackLevelAuto` / `BlackLevel`; `PixelFormat`, binning, `Width` / `Height` / `OffsetX` / `OffsetY`; `GammaEnable` (and `Gamma` where gamma was on), `LUTEnable`, `ColorTransformationEnable`; `ReverseX` / `ReverseY`; `UserSetSelector`; the packet size (`GevSCPSPacketSize` / `DeviceStreamChannelPacketSize`); the pacing, `DeviceLinkThroughputLimitMode` (and `DeviceLinkThroughputLimit` where the mode was `On`), the inter-packet delay `GevSCPD` and the start stagger `GevSCFTD` an array gives each camera; the chunk data every stream turns on (`ChunkModeActive`, each `ChunkEnable` under its `ChunkSelector`); `AcquisitionFrameRateEnable` (and `AcquisitionFrameRate` where the enable was on — with it off the rate is read-only and reads the most the pacing allows, so it is not a setting). Only what differs is written, the camera stopped first, the pacing and frame rate before an exposure that needs their frame period (a camera caps `ExposureTime` at one frame period). With `--keep-settings` the trigger and sync-line wiring goes back, the camera is free-running, and the rest is saved into the camera's own memory as the run set it; `--clear-settings` puts the factory settings there.
* **The exposure is set from the scene before the first frame is kept.** The run takes synchronized frame groups and discards them while it sets each camera's exposure and gain from those frames. The aim is a mean brightness on the camera's target with no more than 1 % of the frame clipped; a scene with bright highlights stops short of the target. This usually takes 2-6 frame groups, and at most 5 s.
  * Each camera aims at the target a connected array starts it at, by its filter: TargetBrightness **40** on a multispectral camera (RGN, OCN, NGB) and **60** on an RGB one. That is half the exposure target 80 gives (three quarters on RGB), so a bright reflectance panel is less likely to clip. `--brightness N` (0-255) sets every camera's target instead (`multi-test` has no `--brightness`: its auto-exposure is off). The backend's log names each camera's target: `[transient-ae] AE target per camera (filter default): SN:<serial> <target>, …`.
  * Exposure comes first, up to the camera's own auto-exposure limit. Gain covers only what is left.
  * The exposure and gain found are kept for the whole run, so every frame of a `multi-stream` is taken at the same exposure. A capture that must follow changing light belongs on a connected array (`array-connect`), whose auto-exposure keeps adjusting.
  * `--exposure` and `--gain` are kept exactly as given. With both given, no frame is discarded.
  * When the run ends, each camera's auto-exposure is switched back on.
  * The backend's log reports the result: `[array-ae] exposure solved in <s> s (<n> warm-up groups): SN:<serial> <ms> ms <dB> dB mean <m>/<target>, …`, or `exposure NOT solved after …` with the reason and `(not settled)` on each camera that was not. The frames are still taken in that case.
  * `CHLOROS_TRANSIENT_AE_SETTLE_S` changes the 5 s limit; `0` turns this off (see [Environment Variables](#environment-variables)).

**While Chloros holds any camera** (the GUI, `cam-connect`, or a connected array), `multi-stream`, `multi-test`, `multi-detect`, `align-apply`, `align-stream` and `index --live` refuse to run, because they open every camera on the network and a second open of a held camera can crash the backend. (`index --live` refuses when a camera it would open is held: its `--serials` or its profile's cameras, and any camera for a profile that names none.) The backend answers HTTP 409 `CAMERA_HELD`, naming each held camera and the release commands (`chloros-cli lattice cam-disconnect --all` / `chloros-cli lattice array-disconnect --all`), and the command exits `1`. With an array connected, `array-capture --continuous` records it in place of `multi-stream`, and `array-capture` (aligned by default) saves an aligned set in place of `align-apply`; `multi-capture` and `align-calibrate` use a connected array that holds their cameras instead of opening them.

| Subcommand                                                                                                                                               | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lattice multi-info [--serials SN1,SN2,…]`                                                                                                               | List all cameras with sync roles; with `--serials`, only those, the first as `MASTER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `lattice multi-capture [--serials SN1,SN2,…] [--format FMT] [--jpeg-quality N] [--processing LEVEL] [--brightness N] [--no-daq] [--daq-tolerance-ms MS]` | One synced frame from each cam. Saves **all export types by default** when a persistent array is connected, and the DAQ reading it used ([The DAQ reading a capture saves](#the-daq-reading-a-capture-saves)); the transient no-array fallback is **debayered only** (run `array-connect` first for the rest). `--brightness` applies to the fallback only: a connected array keeps its own auto-exposure. The fallback saves no `.daq` (`--no-daq` / `--daq-tolerance-ms` have no effect there), and `multi-capture` does not take `--force-daq`. In the fallback, a camera that delivers no frame fails the capture (`Error: multi-capture failed: no frame from …`, exit `1`) and no file of that frame group is saved.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lattice multi-stream [--serials SN1,SN2,…] [--fps F] [--count N] [--format FMT] [--jpeg-quality N] [--brightness N]`                                    | Stream synced frames (transient), `--fps` default `3`, until Ctrl+C or `--count` groups. A frame group a camera delivered nothing for is not written, and three in a row end the stream. If any group was skipped, the run ends by printing `Incomplete: <n> frame group(s) not written, a camera delivered nothing (SN:<serial> x<count>, …)`, plus `Error: the stream stopped: …` naming the camera when it ended the stream, and exits `1`. Stops itself when the drive fills, prints `Failed:` / `Disk full:` and exits `1`; any file it could not write also exits `1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lattice multi-test [--serials SN1,SN2,…] [--count N] [--ptp-settle SECONDS]`                                                                            | GPIO sync timing test (transient), `--count` default `10` triggers. Prints how the network is shared (`Wire: each camera paced to <x> MB/s (<n> on a <y> MB/s ceiling, <link> Mbps link)`, and the `Serial emit:` line when the cameras are triggered one after another, whose stagger the timestamps then include), a `Sync group: master SN:<serial> -> SN:<serial>, …` line per sync group (`(no slaves: not synced)` for a camera on no sync cable, which is triggered on its own), then one row per trigger: `[ 0] SN:<serial>=<timestamp> \| …`, with `SN:<serial>=(no frame)` for a camera that delivered nothing for that trigger. Then `Offsets from master SN:<serial> (<PTP / device (PTP off)> clock, <n> trigger(s)):` and a `SN:<serial>: mean <±x> us, jitter <y> us` line per camera, every camera against the master within one clock: a trigger whose stamps mix the cameras' device clocks and PTP (PTP off or still locking) is left out, with a `Note:` counting them. Any missed frame fails the test (`Error: multi-test failed: <k> of <n> frame groups incomplete (SN:<serial> missed <k>); …`, exit `1`); three incomplete triggers in a row end it early. It also fails (exit `1`) when fewer than two triggers have every camera on one clock (`… the clocks cannot be compared`), or when the clocks never agree: PTP clocks more than 1 ms (plus any serial-tier stagger) from the master (`… PTP is not locked`), or device clocks whose offset moves by more than that between triggers. It starts the PTP grandmaster if it is not running, turns every camera's PTP on (as `array-connect` does, whatever the network looks like), and before the first trigger waits for every camera's PTP clock to lock to the grandmaster and settle: `PtpStatus` Slave on one grandmaster, within 100 us of it and steady for 3 s, and each camera locked like that, without a break, for 120 s — about 2 minutes from power-on. A clock that has just locked is off by up to \~200 us for about 2 minutes after it reads Slave, and the camera's own `PtpOffsetFromMaster` does not show it; 120 s brings the cameras within \~10 us of a settled clock. A camera still locked since an earlier test that left PTP on, as this backend saw it, counts from that lock, so a test right after another does not wait again; a camera the test turns on, or one found with PTP on that this backend has not seen lock (turned on elsewhere, or before a backend restart), waits its 120 s, and in an array of both the cameras just locked still wait theirs. A camera that leaves Slave, goes past 100 us or follows another grandmaster for 3 readings in a row (1.5 s) during the wait starts its count again; one or two such readings are logged (`[array-sync] PTP SN:<serial> off lock at <s> s (<n> of 3): <status> <±x> us gm <id> -- locked <s> s, counting on`) and the count goes on, and a grandmaster id that cannot be read is taken as unknown, not as a change. Every camera's count restarting at once (within a second) is the grandmaster's time moving, not the cameras': the backend's log says `[array-sync] PTP grandmaster step: all <n> cameras restarted at <s> s …`, `ptp_lock` lists it in `grandmaster_steps`, and a wait that then runs out begins its error with `every camera's count restarted together at <s> s -- the PTP grandmaster's time moved under them …`. The bound is not extended for it. `--ptp-settle SECONDS` sets the settle time for the run (0-600; `0` for no settle wait). The wait is bounded at the settle time plus 90 s (210 s by default, at least 90 s), and the command waits for the backend 240 s plus the settle time (360 s by default). It prints `PTP: locked after <s> s (each camera locked <settle> s, already locked: SN:<serial>, …; from the grandmaster: SN:<serial> <±x> us, …)`, and the backend's log has a line every 5 s with each camera's state and offset, how long it has been locked and how long it has left: `[array-sync] PTP at <s> s: SN:<serial> Slave <±x> us for <s> s (<s> s left), … -- <s> s left, the wait gives up at <s> s`. Every camera powers on with PTP off; from there the clocks lock in about 10 s. Afterwards each camera is put back as the test found it — its PTP, the auto exposure and gain the test holds Off for its run, and the rest (unless `--keep-settings`) — so a camera left with PTP on (`lattice configure -s <serial> --set PtpEnable=True`, or a run with `--keep-settings`) stays locked, and once this backend has seen it locked for the settle time a later test does not wait for it. If the clocks do not settle in the wait, it fails before triggering (`PTP: NOT locked …`, exit `1`) and says what to do: a camera that never locked (`PtpStatus Listening`) means the grandmaster is not reaching it (`time-sync status`); one that kept dropping out is named with how long it had been locked (`… had not been locked for the 120 s settle time … (SN:<serial> locked <s> s, <s> s to go)`); clocks still converging: check `time-sync status`, and to have them locked before the test, turn PTP on and leave it on (`lattice configure -s <serial> --set PtpEnable=True` for each camera, or run the test with `--keep-settings`; the test puts back what it found, so it stays on), then run it. |
| `lattice multi-detect [--line LINE] [--json]`                                                                                                            | Find the cameras on the M8 sync line, and a default master: the RGB camera (model ending `-FRGB`) if it is cabled, else the first cabled camera by serial. The M8 cables meet at one junction, so **any cabled camera can be master** — the printed `MASTER` is a default, not a wiring fact. Each camera in turn drives the line and the others are checked for its pulse; a camera already found in the cabled group is not probed again, so a fully cabled array takes one round. With no `--line` it probes `Line2`, then `Line3`. Prints `MASTER: SN:…`, one `SLAVE: SN:…` per other cabled camera and `(probed on <line>)`; `--json` adds the full result (`master`, `slaves`, `no_cable` — cameras the pulse did not reach — `line`, and per-camera `results`). When it finishes, every camera gets back the trigger and sync-line settings it had (the same nodes as above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

#### Alignment

| Subcommand                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lattice align-calibrate [--serials SN1,SN2,…] [--method orb\|akaze\|phase\|checkerboard\|manual] [--model translation\|rigid\|affine\|homography] [--frames N] [--checkerboard RxC] [--points PATH] [--reference SN] [--save PATH] [--preview] [--vignette] [--prefilter none\|gradient\|clahe\|blur\|hist_match] [--rms-threshold-px N] [--brightness N]` — plus detector/matcher knobs `[--max-features N] [--ratio-threshold F] [--matcher bf\|flann] [--knn-k N]`, RANSAC knobs `[--ransac-threshold-px F] [--ransac-iters N] [--ransac-confidence F]`, multi-frame combination `[--averaging mean\|median\|inlier_weighted]`, geometric constraints `[--lock-rotation] [--lock-scale] [--lock-axis x\|y]`, spatial restriction `[--roi X0,Y0,X1,Y1] [--mask PATH]`, and per-slave overrides `[--per-cam-override SN:KEY=VALUE]` (repeatable) | Compute alignment profile from live cameras. Defaults: `--method orb`, `--model rigid`, `--frames 3`, `--save alignment_profile.json` (in the folder you run it from), `--max-features 2000`, `--ratio-threshold 0.75`, `--matcher bf`, `--knn-k 2`, `--ransac-threshold-px 3.0`, `--ransac-iters 2000`, `--ransac-confidence 0.99`, `--averaging mean`. (`project align calibrate` has its own defaults; see [its table](#project-align-calibrate-options).) `--prefilter` defaults to `gradient` (edge map; matches the GUI/array aligner — edges survive across spectral bands). `--matcher flann` pays off above \~5000 features; `--averaging median` is robust to one bad capture, `inlier_weighted` weights by match count; `--lock-scale` projects to the nearest rotation (no scale), `--lock-axis` zeroes one translation component; `--mask` applies to every camera (use `--per-cam-override` for per-cam settings, e.g. `--per-cam-override 214701292:method=phase`). `--rms-threshold-px` refuses to save a calibration whose reprojection RMS exceeds the gate. `--method manual` takes its points from `--points PATH`: a JSON object `{"<serial>": [[x, y], ...], ...}` giving each camera's pixel coordinates of the same features, the reference camera's included (at least 2 per camera); every one of the `--frames` is solved from those points. When a connected array holds the cameras, the calibration uses that array's live frames, and the profile also becomes the array's alignment for its captures. Otherwise it opens a [transient array](#multi-camera-transient-sessions): a camera that delivers no frame in any of the `--frames` fails the calibration (exit `1`, naming it), and no profile is saved. |
| `lattice align-apply --profile PATH [--serials SN1,SN2,…] [--format tiff\|png] [--bit-depth 8\|12\|16] [--bands NAMES] [--order NAMES] [--gpu\|--no-gpu] [--no-crop] [--per-camera] [--per-band] [--vignette] [--interpolation nearest\|linear\|cubic\|lanczos] [--border-mode constant\|replicate\|reflect\|wrap] [--border-value N] [--brightness N]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Capture one aligned multi-band frame. `--bit-depth` defaults to matching the camera; `--no-crop` keeps the full frame (pad with black); `--interpolation` (default `linear`) and `--border-mode`/`--border-value` (default `constant`/0) control the CPU warp — the GPU path is bilinear regardless. Opens a [transient array](#multi-camera-transient-sessions): a camera that delivers no frame fails the capture (exit `1`, naming it), and nothing is written.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `lattice align-stream --profile PATH [--serials SN1,SN2,…] [--fps F] [--count N] [--bit-depth 8\|12\|16] [--bands NAMES] [--order NAMES] [--gpu\|--no-gpu] [--no-crop] [--per-band] [--vignette] [--interpolation nearest\|linear\|cubic\|lanczos] [--border-mode MODE] [--border-value N] [--brightness N]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stream aligned multi-band frames (same warp knobs as `align-apply`), `--fps` default `3`. Opens a [transient array](#multi-camera-transient-sessions): a frame group a camera delivered nothing for is not saved, and three in a row end the stream. If any group was skipped, the run ends by printing `Incomplete: <n> frame group(s) not saved, a camera delivered nothing (SN:<serial> x<count>, …)` and `Error: …`, and exits `1`. A stream that ends on any other error also prints `Error: …` and exits `1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `lattice align-info --profile PATH [--json]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Display profile details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lattice align-reorder --profile PATH [--order NAMES] [--enable SERIALS] [--disable SERIALS]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Change layer ordering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### Index / Vegetation Maths

```bash
# Offline: compute NDVI from an aligned multi-band TIFF (an RGN camera's bands)
chloros-cli lattice index --input aligned.tif --preset NDVI \
  --channel red=Red_660_RGN --channel nir=NIR_850_RGN \
  --output ndvi.tif --colorize --gradient RdYlGn

# Live: open the cameras, capture one aligned set with a profile made by
# `lattice align-calibrate`, and compute the index from it
chloros-cli lattice index --live --profile align.json --preset NDVI \
  --channel red=Red_660_RGN --channel nir=NIR_850_RGN \
  --save-multiband -o output/
```

**`--channel` maps a preset's symbols to bands** (NDVI: `red`, `nir`), one `--channel SYMBOL=BAND` each.

* **`--live`: only for a symbol the stack cannot answer.** As with `--input`, a preset's symbol you leave out takes the one band of the stack (the profile's enabled cameras' bands) whose name starts with it. This is checked before any camera opens: a symbol that no band, or several bands, answer to is refused then, naming them, exit `1`. A custom `--formula` needs a `--channel` for every symbol.
* **`--live` products say whose they are.** `index.tif` and `index_LUT.png` carry the stack's camera (Make, Model, serial), its capture time (the reference camera's exposure, UTC) and lens, and both name the index as their one band (`XMP-Camera:BandName` `NDVI`; the colour PNG names the index, not its colour channels), as an `--input` product does. An index from several cameras' bands names every one of them instead, and its `Model` is `LATTICE` — see [Files made from several cameras](#files-made-from-several-cameras).
* **`--input`: only for a symbol the file cannot answer.** A symbol you leave out takes the one band of the file whose name starts with it: `red` takes `Red_660` or `Red_660_RGN`, `nir` takes `NIR_850`. The names come from the file itself: the stack's own band list, or, on a Chloros radiance / reflectance capture or `process` product, its `Chloros:Band{R,G,B}Name` / `XMP-Camera:BandName` tags. So `lattice index --input <reflectance capture> --preset NDVI` needs no `--channel`.
* **Two bands answering to one symbol are not guessed between** (a 9-camera stack has two NIR bands): name that one. A symbol nothing answers to is refused with `channel_map missing entries`, exit `1`.

**Band names in a stack** carry the camera's filter: an M3C camera's bands are `<band>_<filter>` — `NIR_850_RGN`, `Green_550_RGN`, `Red_660_RGN` on an RGN; `NIR_808_OCN`, `Cyan_490_OCN`, `Orange_615_OCN` on an OCN; `Blue_475_RGB`, `Green_550_RGB`, `Red_625_RGB` on an RGB; `Blue_475_NGB`, `Green_550_NGB`, `NIR_850_NGB` on an NGB — and an M3M camera's single band is `Mono_<filter>` (`Mono_660`, `Mono_850`). `lattice align-info --profile PATH` lists the bands of a profile.

Full flag set: `--input PATH | --live --profile PATH`, `--preset NAME` (NDVI/NDRE/EVI/SAVI/GNDVI/…), `--formula EXPR`, `--channel SYM=BAND` (repeatable), `--capture-level raw|debayered|radiance|reflectance|unknown` (override the capture level recorded in the source TIFF; default: read from TIFF metadata, falling back to a Chloros file's `Chloros:ProcessingLevel`, so a reflectance capture reports `reflectance`), `--output PATH` / `-o` (offline: a path; with an image extension the files are named from its stem — `-o ndvi_FRGN.png` writes `ndvi_FRGN.tif` and `ndvi_FRGN_LUT.png` — and without one it is a prefix, `-o ndvi` -> `ndvi.tif`, `ndvi_LUT.png`; default beside the input, as `<input name>_<preset>`; with `--live` and no `-o`, an `output/` folder under the folder you run the command from), `--output-format all|raw|tif|colorized|lut|png`, `--gradient NAME|JSON`, `--vmin/--vmax/--percentile LO,HI`, `--bg-mode clip|transparent|indexColor|backgroundColor`, `--colorize`, `--list-presets`, `--list-gradients`. With `--live` the alignment warp knobs also apply: `--save-multiband`, `--gpu/--no-gpu`, `--no-crop`, `--bit-depth 8|12|16`, `--vignette`, `--interpolation nearest|linear|cubic|lanczos`, `--border-mode constant|replicate|reflect|wrap`, `--border-value N`, `--brightness N` (the cameras' auto-exposure target, see the transient rules), `--serials SN1,SN2,…`. `--live` opens a [transient array](#multi-camera-transient-sessions): a camera that delivers no frame fails the run (exit `1`, naming it), and no stack or index is written. It opens `--serials` (the first fires the trigger), else the profile's cameras whose `layer_order` entry is enabled, its reference first — the reference even with its bands disabled, since the others are aligned to it and it fires the trigger. A camera whose bands are disabled is never calibrated, so an RGB camera disabled in the profile no longer fails a reflectance index (`no-absolute-radiance-scale`). A profile that names no cameras opens every camera on the network, as before.

Every form runs on the backend, so it must be running: start it from the Chloros GUI, or with the command the CLI prints when it cannot reach it. Offline, the backend reads `--input` and writes the float TIFF and the colorized PNG itself, so a relative `--input` or `-o` resolves against the folder you run the command from (see [Conventions](#conventions)). Both offline products carry the input's camera record, as a `process` index export does: Make / Model / serial, GPS, the lens tags, the capture time (the input's own; when its EXIF states none, the exposure instant it recorded or its file name's stamp, in UTC) and the MAPIR calibration identity — never the raw-DN calibration, which does not apply to an index — plus `Chloros:ProcessingLevel=index` and the index expression; the float TIFF names one band, the preset. `--list-presets` and `--list-gradients` print the backend's preset and gradient tables. A formula the backend rejects, or a `--channel` band the TIFF does not have, exits `1` with the backend's reason.

> **`--channel` symbols are case-sensitive.** The symbol side must match the preset's channel names exactly (presets use lowercase, e.g. NDVI = `red`,`nir` — check `--list-presets`), and the band side must match a band name in the aligned stack (or be a 0-based band index in offline mode). `--channel red=Red_660_RGN --channel nir=NIR_850_RGN` works; `--channel RED=660` fails with a `channel_map missing entries` error.

#### `lattice index` — multiband stack masks

At `--capture-level radiance` or `reflectance` each camera's 3×3 unmix can clamp a band to 0 (see [Unmix clamp mask](#unmix-clamp-mask-which-pixels-a-band-was-clamped-on)). A multiband stack holds bands of several cameras, and each camera clamps its own, so `--live --save-multiband` writes **one mask per source camera** beside the stack:

```
output/
├── index_multiband.tif
└── clamp_masks/
    ├── index_multiband_SN<serial A>-<filter A>_clampmask.tif
    └── index_multiband_SN<serial B>-<filter B>_clampmask.tif
```

* Each mask is single-band `uint8` on the **stack's** pixel grid (through the same alignment warp and crop), with that camera's own bits: bit 0 = its R channel's band, bit 1 = G, bit 2 = B. A stack band taken from channel *c* of a camera is clamped where that camera's bit *c* (R = 0, G = 1, B = 2) is set.
* Each band's embedded provenance names its camera's mask (`unmix_clamp_mask`, relative to the stack's folder, or `none`) and the bit to read (`unmix_clamp_mask_bit`).
* A camera whose unmix clamped nothing gets no file; a mono or RGB camera runs no unmix and gets none either. The CLI prints each mask under the stack (`clamp mask SN…: …`); the response lists them as `clamp_masks`.
* The index TIFF / PNG of the same run is computed from the same stack, on the same grid, so the masks describe it too. `--capture-level raw` runs no unmix and writes no mask.
* The stack and the index sit straight in `--output`, so the masks go in `--output`'s own `clamp_masks/` — never above the folder you named. That folder mixes product kinds (stack, index, colorized render): pick its files, don't hand the whole folder to photogrammetry software.

#### Persistent Connections (Smart-Prep, GUI-Equivalent Flow)

These commands keep cameras open in the backend pool across CLI invocations.

| Subcommand                                                                                                                                                                                                                                                                     | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lattice cam-connect [--serial SN]`                                                                                                                                                                                                                                            | Add one cam to the pool (single-cam, no array). The [common options](#common-options-shared-by-most-subcommands) `--exposure`, `--gain`, `--preset`, `--pixel-format`, `--width` / `--height` and `--packet-size` (`standard` = 1500, `jumbo` = 9000, or bytes; `auto` probes) are applied at connect (an `--exposure` or `--gain` switches that auto mode off). It returns once the camera's stream has started (waiting about 15 s for that, then 10 s for its first complete buffer) and prints `stream: streaming`, or `stream: no_frames -- connected, no frames yet: …` when the stream delivered nothing — for a camera at jumbo packets, with the advice to reconnect with `--packet-size standard`. While one camera connects (a first connect downloads its calibration, about 70 s), another command that needs a camera waits for it at most 5 s, then fails with HTTP 503 `CAMERA_POOL_BUSY` naming the camera connecting; run it again in a moment. `lattice status` and the camera list never wait: a camera mid-connect shows as connecting, with its phase.                                                                                                  |
| `lattice cam-disconnect [--serial SN] [--all] [--keep-settings \| --clear-settings]`                                                                                                                                                                                           | Release. The camera is put back as it was found at connect (trigger wiring, PTP, settings); `--keep-settings` saves its settings into its own memory instead, `--clear-settings` resets that memory to the factory settings (see [Camera memory](#camera-memory----keep-settings----clear-settings)). A camera that is an array member releases the whole array.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `lattice cam-list`                                                                                                                                                                                                                                                             | List cams in the pool.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **`lattice array-connect`**                                                                                                                                                                                                                                                    | **Connect a persistent synchronized array (THE recommended entry point).** Runs the full GUI smart-prep flow. About a minute for 9 cameras; right after the cameras power on it can take several. While it waits it prints each step the backend reaches, as `<s> s: <step>` (for example `41 s: open SN:214000535 (4 of 9)`), and the backend's log has one timing line per step (`[array-connect <id>] <step>: <s> s …`) and a last line with the slowest steps. It waits up to 600 s. A connect not done by then is undone by the backend: every camera it opened is put back as it was found and closed, the command prints `Error:` with the step it had reached and exits `1`, and no array is connected (HTTP 504 `CLIENT_DEADLINE_PASSED`). Ctrl+C cancels the connect the same way (`Interrupted: …`); if the array had already connected, the line says so and names the `array-disconnect` that releases it. A command killed while it waits (`kill -9`) leaves the connect to be undone when the backend has not heard from it for 30 s. An array that is up but has no synchronized frame group yet is still reported connected, with its stream as `no_frames`. |
| `lattice array-disconnect [--array-id ID] [--all] [--keep-settings \| --clear-settings]`                                                                                                                                                                                       | Release an array. Every camera is left free-running (`TriggerMode` `Off`), with everything else as the connect found it — its trigger and sync-line settings (the master's `TriggerSource` back to what it was, its sync line back to an input), its PTP, and the camera settings the session changed — so a single-camera command on a member works at once. `--keep-settings` saves each camera's settings as the session left them into the camera's own memory; `--clear-settings` resets that memory to the factory settings. See [Camera memory](#camera-memory----keep-settings----clear-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lattice array-list`                                                                                                                                                                                                                                                           | List connected arrays.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `lattice array-status [--array-id ID]`                                                                                                                                                                                                                                         | Live fps, PTP, last error. `ptp_enabled` is `True` only when every member reads PTP on; `ptp_off:` names a member that does not. The `state:` line reads `restarting (applying settings)` during a settings restart, `recovering (…)` while a member that lost power is re-opened (see the note below), `stalled (…)` while the grab loop runs but publishes no frame group, and `stopped (…)` once the grab loop has given up (reconnect the array).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lattice array-capture [--processing LEVEL\|all] [--levels L1,L2,…] [--aligned\|--no-aligned] [--orient] [--index\|--no-index] [--no-daq] [--daq-tolerance-ms MS] [--smart] [--fastest] [--compression deflate\|none] [--continuous\|--interval S] [--count N] [--duration S]` | One synced capture from the live array — Single / Continuous / Interval / Fastest. **Defaults to `all`** (one file per applicable export type per cam), **aligned** as the app's capture is (`--no-aligned` for native files). Skipped cams (e.g. RGB excluded from radiance/reflectance) are reported with `Skipped: SN:<serial> (<reason>)`; the DAQ reading the capture used is saved alongside, a raw-only capture included, and reported with `DAQ: <path>` ([The DAQ reading a capture saves](#the-daq-reading-a-capture-saves)). See [Capture Modes, Recorders & Offline Reprocess](#capture-modes-recorders--offline-reprocess).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `lattice array-record [--fps F] [--duration S] [--gif] [--gif-only] [--expr EXPR]`                                                                                                                                                                                             | Record the live combined-index view to video/GIF (monitoring-grade; with no GUI view open, the backend renders the array's NDVI, or `--expr`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `lattice array-burst [--duration S] [--max-frames N] [--orient] [--build] [--products …]`                                                                                                                                                                                      | High-fps raw-Bayer burst (analysis-grade; reprocess offline). Like `array-record` and `array-capture --continuous`, it checks in with the backend at each poll: killed without stopping (`kill -9`), the backend stops it 30 s after the last check-in (`stop_reason` `client_gone`; the burst's manifest is finalized and its combined-index build started, as a stop does) and the array stays connected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `lattice array-build-video --burst-dir DIR [--products …] [--fps F] [--save-tiffs] [--gif]`                                                                                                                                                                                    | Reprocess a saved raw burst into calibrated video(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

> **A camera that loses power or its link comes back by itself.** When a member stops answering (a switch power cycle reboots every camera it powers), the array waits for it, re-opens it when it answers again, and gives it back what `array-connect` set: PTP, the trigger and sync line, network pacing, pixel format and frame size, and auto exposure. It then streams again with no new `array-connect`. Meanwhile `array-status` shows `state: recovering (...)` and `last_error` says which camera it waits for; afterwards it prints `re-opened:`. A camera that rebooted comes back with PTP off, so until it is re-opened `ptp_enabled` is `False` and `ptp_off:` names it.

> **A held camera is never opened a second time.** A second open stops the holder's stream and rewrites its settings, and can crash the backend. So on a camera the pool holds (the GUI or `cam-connect`), an array member, or a camera a background job holds (a running `lattice continuous`, `multi-stream` or `align-stream`, its own or another client's), `lattice continuous`, `lattice capture`, `cam-connect`, `power --sleep`, `calibrate`, a one-shot `white-balance` and `presets --apply` refuse with HTTP 409 `CAMERA_HELD`, naming the holder and the release command (`chloros-cli lattice cam-disconnect -s <SN>`, `chloros-cli lattice array-disconnect --array-id <ID>`, or for a job its id and who started it), and exit `1`. So does a camera another command is using right now (a `multi-test` or `multi-capture` opening its cameras, another one-shot), for every command here: the error says to wait for that command to finish. `lattice power` without `--sleep` reads through the holder's own handle where there is one (the pool, an array, a job's open camera), and is refused for a camera another command is using. Every `CAMERA_HELD` reply carries the code in both `code` and `error_code`. For the commands that open every camera, see [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions).

**`array-connect` Options**

| Flag                                                                                  | Default                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--serials SN1,SN2,…`                                                                 | auto-discover all LATTICE cams (needs ≥2) | First serial is the MASTER. When omitted, discovery filters to LATTICE (M3C / M3M) models and connects all of them.                                                                                                                                                                                                                                                                                                                                               |
| `--line {Line0,Line2,Line3}`                                                          | `Line2`                                   | GPIO sync line.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--target-fps F`                                                                      | auto                                      | Master trigger fire rate.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--force-tier {sim-capture-sim-emit, sim-capture-ftd-stagger, slip-emit-and-capture}` | auto                                      | Override the tier picker.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--wire-ceiling-mbps MB_PER_S`                                                        | auto-detected                             | **The host's sustained wire budget, in MB/s — the number the whole array allocation hangs off.** Lower it when the array reports GVSP-corrupt frames: the auto value is derived from the NIC's advertised link rate, which over-states USB adapters, thin PCIe lanes and busy shared fabrics. Persisted in the project's array capture block, so a reopen / CLI / SDK reconnect restores it. See [Array health](#array-health--which-subsystem-is-losing-frames). |
| `--binning {1,2,4}`                                                                   | none (full sensor)                        | Hardware binning (always Average).                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--width N` / `--height N` / `--pixel-format FMT`                                     | full sensor; per-camera format            | An explicit frame size or pixel format for every camera, instead of the full sensor and the per-camera format pick (Mono12 / BayerRG12).                                                                                                                                                                                                                                                                                                                          |
| `--no-recommend`                                                                      | off                                       | Skip the network-analysis step (each camera then keeps its current sizing instead of being set to the full sensor).                                                                                                                                                                                                                                                                                                                                               |
| `--no-ptp`                                                                            | off                                       | Disable PTP (cross-cam timestamps are then **not** comparable).                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--packed {auto,on,off}`                                                              | `auto`                                    | Stream 12-bit frames packed and unpack on this computer — more frames per second at full sensor, identical data. `auto` packs only when it helps and this computer can afford it; `off` never packs. See [Packed 12-bit transport](#packed-12-bit-transport---packed).                                                                                                                                                                                            |
| `--packet-size {auto,jumbo,standard,N}`                                               | `auto`                                    | GVSP packet size for every camera in the array. `auto` lets each camera probe the network; `jumbo` = 9000, `standard` = 1500, or a size in bytes pins it. Before 1.3.0 `array-connect` accepted this flag and ignored it.                                                                                                                                                                                                                                         |

> **Full sensor by default.** With no `--width` / `--height` / `--binning` / `--pixel-format`, `array-connect` sets every camera to the full sensor — no binning, no ROI crop — and lets the frame rate fall to what this computer and network deliver, rather than shrinking the frames to keep the rate up. The network-analysis line shows the projected rate, and the next line lists faster options (binning or a smaller ROI) with their projected rates; pass `--binning` or `--width`/`--height` to take one. Connect never bins or crops on its own.

**Packed 12-bit transport (`--packed`)**

At full sensor an array's frame rate is set by how fast each camera may send its frames. 12-bit formats (`BayerRG12`, `Mono12`) normally travel as 16-bit words; **packed** transport sends the same 12 bits in 1.5 bytes a pixel and unpacks them on this computer, so each frame takes 25% less time to send — about **33% more frames per second at full sensor** (measured: 10.7 → 14.0 fps on a 9-camera array). **The saved data is identical**: same values, same 16-bit files, same metadata.

* `auto` (default) packs only when it helps **and** this computer can afford the unpack. At connect the backend measures its own unpack speed, CPU count, current CPU load and network budget, so a desktop with cores to spare packs at full sensor, while a busy or low-power computer streams unpacked. Small ROIs and binned frames gain little.
* `off` never packs — use it to rule packing out while diagnosing, or on a computer that must keep all of its CPU for other work.
* `on` always packs 12-bit formats.

The connect output shows the decision and why (`packed 12-bit: on (auto: projected 11.0 -> 14.4 fps, …)`); `/api/camera/array/status` reports `packed_transport` and `packed_decision`. To set a machine-wide default instead of passing the flag each time, set `CHLOROS_ARRAY_PACKED12=off` (or `on`) in the backend's environment — an explicit `--packed on|off` still wins. 8-bit and 16-bit formats are never packed.

### One project record, every mode

A project folder holds every device's settings: `cameras.json` — each camera's (`cameras[].settings`, for a single camera and for each array member) and each array's array-wide ones (`arrays[].capture`: format, ROI, binning, trigger rate, wire budget) — and `sensors.json`, each light sensor's (integration time, frame average, cap). The app, the CLI, the SDK and the MCP server all read and write the same files, the same way:

* **A device connected under a project is saved into it and records every change into it.** "Under a project" means with a project open in the backend (the app's), or — from the SDK — through a `ChlorosProject`, which names its own folder. A camera, array or light sensor the project does not hold yet is added to its files when it connects (`lattice cam-connect`, `array-connect`, `daq pool-connect`, the app, the SDK, `chloros-mcp`), with its settings. A change from any mode (`lattice exposure`, `gain`, `configure --set`, `resolution`, an array's settings and trigger rate, a light sensor's cap, the app's controls) is saved into that project's files a moment later. An exposure, gain or AE target set on a camera is saved as held, so reopening holds it again.
* **Opening a project sets its devices from it**, in every mode: a camera, array or light sensor connected with no settings of its own gets the project's saved ones (`lattice cam-connect` / `array-connect` with a project open, `chloros-cli project connect`, `open_project().connect_all()`, the app's reopen). An array connected under a new id updates the array the project saved with the same cameras; an array with other cameras is added beside it.
* **The app's own save never overwrites a device's live settings** with its older copy of them, and keeps per-member overrides a CLI or SDK caller saved.
* **The pixel format you set is the one a project keeps.** A format set in Array Settings, by `--pixel-format` or by `connect_array(pixel_format=)`, 8-bit included, is saved and reconnected exactly. With none set, each camera connects at its 12-bit default (`BayerRG12`, `Mono12` on a mono sensor). A format name means its bit depth; the family is the sensor's, so a colour camera is never set to a Mono format or a mono camera to a Bayer one, and the line `[PixelFormat <serial>] ... written` says so when a format was mapped. An 8-bit capture's exports are 8-bit, reflectance included: rescaled and stamped with its `PixelScale`.
* A device connected under no project records nothing.
* **A recording follows a project created after it; an open leaves it with its project.** When a project is created — an SDK `create_project()`, `chloros-mcp`'s `create_project`, or the app's **New Project** — or duplicated (the app's **Duplicate**, which opens the copy) while a recording still writes into the project that was open before, the recording keeps going, and what it writes ends up in the new project, in the same place inside it (below). Opening an existing project — `chloros-cli process`, `project devices --reconnect`, `ChlorosProject.process()`, the app's **Open Project** — leaves a recording still going with the project it records into: it finishes there, and its files join that project's file list (the app stops every recording before it opens a project).

  * `array-record` and `array-burst`: the video, or the burst folder with every frame, moves there whole when the recording stops (its `--duration`, Ctrl+C). The `Burst dir` it prints is the new one, and `--build` and `array-build-video` work from it. A move the drive refuses leaves the recording where it was written; the backend's log says why, and so does the stop's HTTP reply (`relocation_error`). A stopped burst's raw frames and `.daq` join the file list of the project it ends up in; a video (an `array-record`, a burst's built video) is not added to a project's file list.
  * `array-capture --continuous`: every capture after the change is saved into the new project; the ones saved before stay where they are.
  * `daq pool-record` and `project sensor log` (and the app's own light-sensor recording): the `.daq` moves into the new project's `light_sensor` folder when the recording stops, and joins that project's file list.

  A recording into a folder outside the open project (an `-o` somewhere else) stays where it is, and `lattice continuous` and `multi-stream` keep the folder they were given.
* **In the app, the captures after a new project go into it.** Creating or duplicating a project keeps every capture run and recording going, and each capture taken after it (Capture All, Start Capturing) is saved into the new project and joins its file list. Opening an existing project in the app stops all of them first.
* **A project is not moved while it records.** Moving the open project to another working directory (the app's **Settings → Working Directory**; no CLI command moves a project, an HTTP client posting to `/api/move-project` does) is refused with HTTP 409 `PROJECT_RECORDING` while an array recording or burst, an array continuous capture, a `lattice continuous` / `multi-stream` job or a light-sensor recording writes into it: `Project '<name>' is recording (<what>), so moving the project now is refused. Stop the recording, then try again.` The app refuses the same way, before it asks for a folder, while its own Capture All, Start Capturing or light-sensor recording runs.

This is separate from what the cameras are left as at disconnect (see [Camera memory](#camera-memory----keep-settings----clear-settings)): a project sets its cameras itself when it opens.

### Camera memory — `--keep-settings` / `--clear-settings`

When an array is connected its cameras take the array's settings, and you can then change them. When Chloros lets cameras go — `array-disconnect`, the end of a transient command (`multi-capture` with no array, `multi-stream`, `multi-test`, `align-calibrate`, `align-apply`, `align-stream`, `index --live`), the stop of `lattice continuous`, the end of a `lattice capture` of a camera it does not hold — it puts each one back the way it was found before the connect: its trigger and sync-line wiring, PTP and camera settings (the full list is under [Multi-Camera (Transient Sessions)](#multi-camera-transient-sessions)).

For using the cameras outside a project, two flags on any of those commands write the camera's **own memory** — what it powers up with, in any software:

* **`--keep-settings`** saves each camera's settings as the session left them into its memory (UserSet2, made the boot set). The cameras are still left free-running (`TriggerMode` `Off`), the sync-line wiring as found. A camera with no UserSet2 saves into UserSet1; this computer remembers it, so Chloros's array self-heal — which resets a UserSet1 that has drifted from Chloros's baseline — leaves it alone.
* **`--clear-settings`** resets each camera's memory to the factory settings: Chloros's baseline, the one its array self-heal bakes — factory defaults with `TriggerMode` `Off`, `TriggerSource` `Line2`, auto exposure, an RGB camera's calibrated white balance kept — in UserSet1, made the boot set.
* The two cannot be combined. Each camera gets a line: `SN:…: settings saved to the camera's memory (UserSet2); it powers up with them.` or `SN:…: camera memory reset to the factory settings.`; the reply's `camera_memory` has the same per camera.

The app does not offer these flags.

**Every way out puts the cameras back.** The same as-found put-back runs on each exit path, not only the commands above: `cam-disconnect` (and the app's camera **X**); the app's **X** on an array or on any array member's row (an array cannot run on without a member, so the whole array is released); closing the app (it gives the backend up to 20 s to put every camera, array and running `lattice continuous` back before it stops it; a command still running then — a transient command opening its cameras or waiting for their PTP clocks, a one-shot `lattice capture`, `power`, `white-balance` or `presets --apply` — stops at its next safe point, puts its cameras back first, for up to 8 s, and answers HTTP 503 `SHUTTING_DOWN`; an array connect still running — `lattice array-connect`, the app's connect — stops before its next camera and puts back the cameras it has opened, for up to 10 s, and answers HTTP 503 `SHUTTING_DOWN`; and one that arrives during the shutdown opens nothing: HTTP 503 `SHUTTING_DOWN`); and a CLI command that is killed or whose terminal closes (SIGTERM / SIGHUP stop its job — and put its cameras back — before it exits `143` / `129`, like Ctrl+C). A `lattice continuous`, `multi-stream` or `align-stream` killed outright (SIGKILL), which can stop nothing, has its job stopped and its cameras put back by the backend 30 s after its last check-in. A backend that crashes or is force-killed cannot put anything back; a power cycle returns each camera to its memory, and the next Chloros connect rewires a camera it finds armed.

**A project sets its cameras itself.** When an array connects with a project open, each member gets the settings the project saved for it — an exposure, gain or AE target held on it (held as yours, so automatic exposure leaves it alone) and its white-balance mode (Chloros's correction; the camera's own white balance stays off) — whatever the camera's memory holds.

### Smart-AE / Smart-Capture

LATTICE arrays run continuous AE in the background as soon as they're connected, but a freshly-pointed scene takes a moment to converge. `array-capture --smart` is the **packaged convenience**: it waits for AE to settle across every cam in the array, then triggers the capture. Use it when you change scenes mid-session.

```bash
# Connect once, then take settled captures whenever you re-point the rig
chloros-cli lattice array-connect --serials SN1,SN2,SN3,SN4
chloros-cli lattice array-capture --smart --processing reflectance -o pose_a/
# (move the rig)
chloros-cli lattice array-capture --smart --processing reflectance -o pose_b/
```

The settle policy is conservative by default: 5 s timeout, 1.5 s stability window, ±5 % exposure spread tolerance. Tune via the SDK (`ArrayHandle.capture_smart(settle_timeout_s=…, stability_window_s=…, exposure_tolerance_pct=…)`) if you need different behaviour from automation.

#### How auto exposure behaves

* **Exposure first, gain last.** With gain on Auto, gain stays at 0 dB until the exposure has reached the longest value it is allowed.
* **A manual exposure leaves gain on Auto** until you change gain or set it to manual. Back on Auto, gain's limit is what it was before.
* **Small highlights do not darken the scene.** A specular up to 1 % of the frame is ignored, and in a known calibration target's panels, up to 0.5 % of a panel.
* **The DAQ exposure ceiling applies only while a calibration target is in view.** It keeps a white panel from clipping; with no panel seen, the camera exposes for the scene.
* **Constant light holds steady, and changed light settles in seconds.** At constant light the exposure and its limit stay put, and after a large change in light the view settles within a few seconds. A clip no longer caps exposure for good, and an ROI change finds the exposure again.
* **The brightness target stays within reach.** It does not climb while the camera is at its exposure limit and its gain cannot rise, so a light that comes back does not flare the frame.
* **A camera whose auto exposure stops responding is held at the level for the light it is in.** In bright sun a camera could fall to its shortest exposure and stay there with a dark frame, its settings all reading normal. Chloros watches the frame, holds that camera at the level it kept for that light, and lets it go when the light changes. A dark or covered light sensor does not disturb this.

### Capture Export Levels (the `all` default)

As of this release, `lattice capture`, `lattice multi-capture`, and `lattice array-capture` **default to `--processing all`** — one saved file per export type that applies to each camera, matching the GUI's "Capture All" behaviour. The levels are:

| Level         | Output                                                                                                                                                                                                                                                                                                                                                                                                                                             | Applies to                                                                                       |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `raw`         | Single-channel Bayer (mono cams: the single band) straight from the sensor.                                                                                                                                                                                                                                                                                                                                                                        | All cams.                                                                                        |
| `debayered`   | 3-channel colour, saved in **RGB** channel order (a TIFF with RGB photometric interpretation; PNG/JPEG likewise open as RGB): the calibration pack's dark offset (DSNU) taken off the raw, then OpenCV's edge-aware demosaic — no linearity LUT, flat field or unmix (mono cams: 1-channel grayscale). The in-memory debayered frames the Python SDK returns (`grab()`, `frame_stream()`) are **BGR**, OpenCV's order; only the saved file is RGB. | All cams.                                                                                        |
| `radiance`    | float32 W/m²/sr/nm via the full radiometric chain.                                                                                                                                                                                                                                                                                                                                                                                                 | Multispectral (M3C/M3M) only — **skipped for RGB-filter cams**.                                  |
| `reflectance` | uint16 ρ (`32768` = 1.0), Pix4D-ready.                                                                                                                                                                                                                                                                                                                                                                                                             | Multispectral only, and **only when a DAQ is bound + the cam is calibrated**; otherwise skipped. |
| `display`     | Full GUI-preview chain (CCM + WB + gamma per the cam's profile). Saved in a `preview/` folder. `lattice capture` also accepts the name `preview` for it; `array-capture` / `multi-capture` take only `display`.                                                                                                                                                                                                                                    | All cams.                                                                                        |

Pass a single level to save just that one (`--processing debayered`). When you ask for `all`, levels that don't apply to a given cam are skipped (and reported), not errored — an unconnected or uncalibrated cam still gets `raw` / `debayered` / `preview`.

#### The DAQ reading a capture saves

Whenever a DAQ is bound to the camera or array, or pooled, the downwelling reading a capture used is written to a **`.daq`** file in the captures folder's `daq/` subfolder, with its `.match.json` (how far the reading was from the exposure) and its `.cameras.json` (whose reading it is), and reported on a `DAQ:` line. That holds for every level, a raw or debayered capture included, so any capture can be re-processed into radiance, reflectance or an index later. It is the same file, with the same name and sidecars, whether the capture came from the GUI, the CLI or the SDK. With no DAQ reading at all there is no `.daq`, and a `multi-capture` with no connected array (the transient fallback) saves none.

| Flag                    | Effect                                                                                                                                                                                                                                                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--no-daq`              | Do not save the reading on a capture whose levels do not use it (`raw`, `debayered`). A `radiance`, `reflectance` or `display` level still writes it, because re-import needs the reading that product was made with.                                                                                                      |
| `--daq-tolerance-ms MS` | How far from the exposure the reading may be and still count as in tolerance (default 500). Only the verdict changes (the `.match.json`'s `in_tolerance` and `tolerance_ms`, the reflectance's `DlsInTolerance`), never the reading used. See [A DAQ Reading Far From the Exposure](#a-daq-reading-far-from-the-exposure). |
| `--force-daq`           | The older way to ask for the `.daq` on a raw-only capture. It is the default now, and `lattice capture` and `array-capture` still accept the flag (`multi-capture` does not). `--no-daq` wins over it.                                                                                                                     |

Which DAQ: the one bound to the camera or array (the GUI's light-sensor selection, a project's saved binding, or `chloros-cli daq pool-bind`), else the freshest one the backend has. A raw burst (`array-burst`) keeps its own `.daq` per distinct reading under the burst folder as before.

**PNG and JPEG hold 8 bits per channel, so they take the `display` / `preview` and index products only.** `--format png` or `jpg` with a level they cannot hold is refused before anything is captured, naming the level and TIFF as the format that holds it:

* `radiance` (float32) and `reflectance` (uint16, `32768` = 1.0) — always, so `--processing all` (the default) with `--format png`/`jpg` is refused too: use `--format tiff`, or `--levels display`.
* `raw` and `debayered` from a camera streaming more than 8 bits (the 12-bit M3C / Mono12 M3M frames) — the CLI cannot see the camera's bit depth, so the backend refuses these (HTTP 400). The single-frame `lattice capture --processing debayered` grabs an 8-bit frame for PNG/JPEG and is not refused, and nor is a `multi-capture` without a persistent array (8-bit debayered).

Every capture route answers the same way (`error_code` `FORMAT_CANNOT_HOLD_LEVEL`): `lattice capture`, `multi-capture`, `array-capture`, `project capture` / `burst`, and the HTTP routes behind them.

### What a captures folder looks like

Each export type lands in its **own subfolder** under `-o`, so a multi-level capture never mixes types. The sketch shows the **default `all` capture of one camera by `lattice capture`** — several levels per camera, so every file carries a `_<level>` suffix:

```
output/
├── raw/           capture_<ts>_SN<serial>-<filter>_raw.tiff
├── debayered/     capture_<ts>_SN<serial>-<filter>_debayered.tiff
├── radiance/      capture_<ts>_SN<serial>-<filter>_radiance.tiff
├── reflectance/   capture_<ts>_SN<serial>-<filter>_reflectance.tiff
├── preview/       capture_<ts>_SN<serial>-<filter>_display.tiff
├── index/         per-camera vegetation-index (LUT) render, when --index is on
├── composite/     array foreground/background live-view composite, when produced
├── clamp_masks/   radiance/…_radiance_clampmask.tif, reflectance/…, index/… — the unmix clamp
│                  masks, one subfolder per product folder, only when a band clamped
└── daq/           daq_data_<sensor id>_<ts>.daq: the downwelling reading matched to the capture
                   (+ .daq.cameras.json: whose)
```

How the file names vary:

* **Camera field — serial, then filter:** every capture file names the camera that took it as `SN<serial>-<filter>`, where `<filter>` is the filter part of the camera's model: `SN261902142-F450` for an `M3M-L87-F450`, `SN213800234-FRGN` for an `M3C-L87-FRGN`, `SN214701292-FRGB` for an RGB camera. The filter joins the serial with `-`, not `_`, so a name has the same `_`-separated fields as before (prefix, date, time, milliseconds, camera, level). A camera whose model cannot be read (a wiped DeviceUserID) is named `SN<serial>` alone. Captures from earlier releases have no filter in the name; Chloros reads both.
* **Prefix:** `lattice capture` names files `capture_…`; `array-capture`, `multi-capture` with a connected array, and `project capture` / `burst` / `stream` of an array name them `sync_<ts>_SN<serial>-<filter>…`.
* **Level suffix only with several levels.** A camera that saves **several** levels in one capture (`all`, or `--levels a,b`) adds `_<level>`. A camera that saves **one** level keeps the plain name, with no suffix — `--processing reflectance` writes `reflectance/sync_<ts>_SN<serial>-<filter>.tiff` — so scripts written against single-level captures keep working. The level is still given by the folder.
* **Clamp masks follow the product's name:** `<product name>_clampmask.tif`. A single-level reflectance capture writes `clamp_masks/reflectance/sync_<ts>_SN<serial>-<filter>_clampmask.tif`; an `all` capture writes `clamp_masks/reflectance/sync_<ts>_SN<serial>-<filter>_reflectance_clampmask.tif`.
* **Extension** follows `--format`: the default `tiff` gives `.tiff`, `--format tif` gives `.tif` (clamp masks are always `.tif`).
* **One exception:** `lattice capture --processing debayered` (or `--levels debayered`) takes a fast single-frame path and writes `capture_<ts>_SN<serial>-<filter>.tiff` straight into `-o` — no subfolder.
* **Streams and bursts** carry the same field: `lattice continuous` writes `frame_<seq>_SN<serial>-<filter>.tiff`, `lattice multi-stream` `stream_<seq>_SN<serial>-<filter>_<frame id>.tiff`, and a raw burst `<burst>_f<frame>_SN<serial>-<filter>_raw.tiff`.

`<ts>` is the capture timestamp and `<serial>` the camera serial, so one synced group shares a timestamp across cameras. **Note the one asymmetry:** the `display` level is stored in a folder named `preview/` while the multi-level files keep `_display` in the name — folder and suffix differ for that level only. Unknown levels fall back to a folder of their own name, and if the subfolder can't be created the file is written to the output root rather than being lost.

**Re-processing a captures folder:** point `chloros-cli process` at the **captures root** (`output/`). `process` normally imports only the folder you name, but when that folder holds no images and does have subfolders it descends automatically — so the level subfolders and the `daq/` subfolder are all picked up in one go. Every level of a capture imports as a single image with the other levels available as modes, rather than as one image per level.

Naming a **level subfolder** directly (e.g. `output/raw/`) also works. Doing so leaves `daq/` behind, so copy or point the DAQ reading in alongside when you re-derive a radiometric product from `raw/` — otherwise the timestamp match has nothing to resolve against.

**Processing always starts from `raw`.** Within each capture the raw frame is the pipeline source; `debayered`, `radiance`, `reflectance` and `preview` come along as viewable modes but are never fed back through the pipeline. Re-processing a derived product would re-apply vignette, CCM and radiance math that is already baked into its pixels, so Chloros declines rather than double-processing. Two consequences worth knowing:

* The `index/` and `composite/` renders are **never** processed. They are outputs, not captures — an NDVI LUT render has no meaningful radiance interpretation.
* A captures folder exported **without** `raw` (e.g. `array-capture --processing reflectance`) has no legitimate pipeline source. Those captures import and display normally, but `process` skips them and says so:

  ```
  [IMPORT-LEVEL] Skipping 4 already-processed file(s) with no raw source: capture_…_reflectance.tif
  [IMPORT-LEVEL] Processing starts from raw. Re-capture with --processing raw, or force an entry
                 point with --input-level.
  ```

  If you genuinely need to push a derived product through — a hub session captured with `demosaic` on, or a legacy folder — `--input-level {raw,debayered,processed}` forces the entry point and overrides the skip. That flag is the deliberate escape hatch; `auto` (the default) never processes a capture that has no raw.

**Calibration tags: on `raw` only.** The `raw` file of a capture carries the camera's calibration packet: the `CalibrationJSON` payload and the MicaSense-compatible tags (`BlackLevel`, `RadiometricCalibration`, `Band{R,G,B}RadiometricCalibration`, `MicaSenseVignetting*`), which describe the sensor's raw values. Every other level's file (`debayered`, `display`, `radiance`, `reflectance`, the `index/` render) and every `lattice continuous` / `multi-stream` frame carries the camera's identity (`XMP-mapir:CameraSerial`, `CameraModel`, `FilterType`, `LensModel`, `CalBundleSha256`, ...) and the frame's own record, `XMP-mapir:FrameJSON` (exposure, gain, temperature, pixel format, capture time, DAQ match), as every `process` product carries the identity. `process` finds such a file's calibration by its serial and `CalBundleSha256` in Chloros' calibration cache, downloading the pack once if this computer lacks it.

#### Files made from several cameras

A file made from more than one camera's bands — a multiband stack (`align-apply`, `align-stream`, `index --live --save-multiband`), a live index made from several cameras (`index.tif`, `index_LUT.png`), an array capture's `composite/` image — names every camera that went into it:

* **Per-camera lists, in band order** (the composite: background layer, then foreground; an index layer, the cameras its bands came from): `XMP-mapir:SourceCameraSerials`, `SourceCameraModels`, `SourceSensorProfiles`, `SourceProductLines`, `SourceFilterTypes`, `SourceLensModels`, `SourceCalDateUTCs`, `SourceCalBundleSha256s` (the calibration pack each camera's bands went through, else — an `align-apply` / `align-stream` stack, whose bands go through none — the camera's pack Chloros has cached, the one its capture files name), `SourceLightboxCertIds`, `SourceHalogenLampCertIds`, `SourcePackTiers` — parallel lists, item *n* of each describing the same camera; `-` where a camera has no value (no calibration pack, an unknown lens). Each camera is **one** item: where its pack has several values for a field — a pack's halogen lamp certificates — they are joined with `;` (`F-1479-1;F-1480-1;F-1481-1`), never a comma, so a list reads one item per camera however it is printed.
* **EXIF `SerialNumber`** holds the same serials, comma-joined (`214000535,214000551`).
* It carries **no** single-camera identity (`XMP-mapir:CameraSerial`, `CalBundleSha256`, …): those name one camera and its pack, and `process` would resolve the file's calibration from them. An index computed from several cameras' bands (`index.tif`, `index_LUT.png`) has EXIF `Model` `LATTICE` (the rig), not one camera's `LATT-…` model.

A file of **one** camera's bands — a per-band TIFF (`--per-band`), an `align-apply --per-camera` frame, a stack or live index of a single camera — carries that camera's own identity tags, as every other capture file does. `align-apply`'s stack, per-band and per-camera files, and each `align-stream` stack and its per-band files, carry their group's capture time (the reference camera's exposure, UTC), and a mono camera's `--per-camera` frame is one plane, at `--bit-depth` like the stack.

**Camera orientation (flip / rotate).** A camera's orientation setting (the GUI's Mirror H / Mirror V / rotation) shapes what a capture saves:

* **`raw` and `debayered` are saved exactly as the sensor read them**, whatever the setting. A Bayer mosaic turned or flipped would be a different colour-filter pattern, and the calibration maps (dark offset, flat field) are on the sensor's own grid.
* **`preview`/`display`, `radiance`, `reflectance` and the `index/` render are oriented** — turned once, after all the calibration math, so they open the way the camera was framed. Their `clamp_masks/…_clampmask.tif` files are on the same grid.
* **Every capture file records the setting** in XMP: `XMP-Camera:ChlorosFlipHorizontal` / `ChlorosFlipVertical` (`true`/`false`), `ChlorosRotation` (0 / 90 / 180 / 270, clockwise, after the flips) and `ChlorosOrientationApplied` — `false` on raw and debayered (native pixels), `true` on the oriented products. `ChlorosProcessing` lists the operations applied to that file's pixels (`none` when native). That includes every frame `lattice continuous` streams (the camera's own setting, unapplied) and every frame of `lattice multi-stream` (the identity: its member frames are native, like an array capture's). `lattice align-stream` / `align-apply` stacks record the master camera's setting, unapplied: their bands are warped into the master's frame but not turned.
* **`process` applies the recorded orientation** when it processes a raw: dark offset, flat field, demosaic and unmix in sensor coordinates first, the array alignment warp next, the orientation last — so the preview, radiance, reflectance and index products come out exactly as the live capture's, and record `ChlorosOrientationApplied=true`. The uncalibrated fallback products (`Sensor_Response_Images`, `Vignette_Corrected_Images`) are oriented the same way, after the flat field. The debayered product stays native.
* **The Chloros image viewer shows a raw or debayered file turned by its record** (display only — the file is not changed), so it looks like its products; the thumbnail, the full-size view, the cursor readout and the Index/LUT sandbox all use the same turn. A file without the record, and a product (already oriented), is shown as stored. A sandbox export records the orientation its pixels carry (`ChlorosOrientationApplied=true`; the identity for a layer without a record).
* **Captures without the record are processed as native** (unchanged behaviour). Before 1.3.0 a single-camera capture with a flip or rotation set turned its raw and debayered files itself; Chloros cannot tell such an already-turned raw from a native one and does not guess, so it processes it as stored. The calibration maps are on the sensor's own grid, so for such a capture use one taken with 1.3.0 when its calibration matters.
* **Arrays turn no member file by default** (the alignment warp and the `Alignment*` XMP are in the cameras' own, unturned frames) and record the identity. `array-capture --orient` turns each member's products, after the alignment warp: by the **master's** orientation when they were warped into its frame (so the members stay co-registered), else by their own camera's. Each file records the orientation of the frame its own pixels are in — a raw, its own camera's — and a raw that carries the alignment transform also records `ChlorosAlignedFlipHorizontal` / `ChlorosAlignedFlipVertical` / `ChlorosAlignedRotation`: the master's, for a product warped into the master's frame. `process` turns each product by the one that belongs to its pixels: the aligned one when it warps the raw (`--array-alignment`, the default — the live aligned capture's products), the camera's own when it does not (`--no-array-alignment` — the live unaligned capture's). The same option exists for `array-burst`, `project capture` / `burst` / `stream`, recipes, and the SDK.

### Skipped Captures in Mixed-Filter Arrays

When you mix RGB and multispectral cams in one array, `array-capture --processing radiance` (or `reflectance`) saves the multispec frames and **skips** the RGB cams — per-Bayer radiance is not meaningful for a broadband sensor. The CLI prints each saved file (with its export level), each `.daq` written, and each skip explicitly, so the file count isn't surprising:

```
  Saved: …/output/reflectance/sync_…_SN213800234-FRGN.tiff [reflectance] (SN:213800234, fid:1)
  Saved: …/output/reflectance/sync_…_SN214000533-FOCN.tiff [reflectance] (SN:214000533, fid:1)
  Saved: …/output/reflectance/sync_…_SN214701288-FNGB.tiff [reflectance] (SN:214701288, fid:1)
  DAQ:   …/output/daq/daq_data_daq-e-54b5e0_….daq
  Skipped: SN:214701292 (reflectance-not-applicable-to-rgb-cam filter=RGB)

  3 synchronized frames captured. (1 skipped)
```

Skip-reason tokens follow the pattern `<level>-not-applicable-to-rgb-cam`. A camera whose calibration pack is not loaded skips `radiance` / `reflectance` with `<level>-needs-calibration (connect the camera so its cal pack loads)`, and with no usable DAQ reading reflectance skips with `reflectance-skipped-no-dls`. Reflectance can also skip with `reflectance-skipped-no-fresh-dls` / `reflectance-skipped-bound-daq-unavailable (…)`, and with `dls-uncalibrated-band-<nm>` when the band lies mostly outside the DAQ light sensor's radiometrically calibrated range (\~374–974 nm) — among shipping SKUs only F988, whose supported path is the reflectance-panel workflow.

Use `--processing debayered` (or `display`) to include every cam regardless of filter type, or the default `all` to get every applicable level per cam in one shot.

### A DAQ Reading Far From the Exposure

Each `.daq` a capture saves is the DAQ reading matched to that exposure, and the `.match.json` beside it records how far apart the two were (`gap_ms`) and whether that is within the tolerance (`in_tolerance`, 500 ms unless the capture set `--daq-tolerance-ms`). A reading outside it is still used, so no frame is lost, and it is labelled: the reflectance file's XMP carries `DlsInTolerance=False` and `DlsMatchGapS`. `lattice capture`, `multi-capture` and `array-capture` also print it under the `.daq` it concerns, with the DAQ's stream fault when one explains it:

**How a reading is matched to an exposure.** A capture waits for the DAQ's first reading after the exposure, so it can blend the readings on either side of it (`method` `interpolated`). A DAQ-E sends a reading every 0.4 s in daylight and every 1-2 s indoors, so the wait adds up to about one and a half of those intervals to the command, not to the exposure. A DAQ that has stopped sending is not waited for. A DAQ-E reading is the light averaged over the interval since its previous reading, so it is placed at the middle of that interval: `gap_ms` is measured from the exposure to that middle, and `bracket_stamps_ns` gives the readings' own timestamps. `array-capture --continuous` waits without slowing the capture: its raw files are written straight away and their `.daq` once the reading arrives. With `--interval`, each pass waits like a single capture.

```
  DAQ:   …/output/daq/daq_data_daq-e-54b774_….daq
         DAQ reading 114.9 s from the exposure (tolerance 500 ms): reflectance uses it, labelled DlsInTolerance=False
         DAQ stream fault: no frame accepted from daq-e-54b774.local in 25 s, after 1932 good frame(s). …
```

When no reflectance file was written from that reading, the first line ends `saved anyway; its .match.json says in_tolerance: false` instead.

The capture still exits `0`: every file was written and says what it holds. A DAQ whose stream has stalled keeps supplying its last reading, so check it with `chloros-cli daq pool-list` before relying on that capture's reflectance. The backend reconnects a pooled DAQ-E that has stopped delivering (see [A DAQ-E That Stops Delivering](#a-daq-e-that-stops-delivering)). An in-tolerance reading prints only its `DAQ:` line, unless it is a kept reading (below).

**A reading kept after its DAQ went away.** When no DAQ can supply a reading for an exposure (the bound DAQ is unavailable, or no pooled DAQ has one, e.g. after `daq pool-disconnect`), the capture reuses the last reading Chloros had, and its `.match.json` describes that reading against this exposure: `method` `retained`, `gap_ms` from this exposure to the samples the reading was made from, `in_tolerance` from that gap, and `retained_from_epoch_ns`, the exposure the reading was first matched to. A capture taken long after the DAQ went away therefore prints the lines above, and under them one more, which is printed even while the reading is still within tolerance:

```
         This is the DAQ's last reading: the DAQ is no longer reporting, so each capture reuses it until a new one arrives
```

Its `.daq` still names the DAQ that took the reading, with the calibration and cap that reading was taken under, so a re-import knows which DAQ, calibration and cap produced it.

### Files That Fail to Write

A camera whose file cannot be written — a full drive, a permissions error — does not stop the other cameras' files from saving. Every capture command (`lattice capture`, `multi-capture`, `array-capture`; `project capture`, `burst`, `stream`; and a recipe's `capture`, `burst` and `stream`) prints each file that failed to stderr, then **exits `1`** even though the rest saved:

```
  Failed: SN:214701292 [reflectance] OSError: [Errno 28] No space left on device
  Disk full: the drive the backend captures to has no space left. Free space on it (or capture to another drive) before capturing again.
```

Every file a capture owes is covered, the single-frame debayered `lattice capture --levels debayered` included. A `.daq` reading whose `.match.json` provenance sidecar could not be written is listed as `[match]` (the `.daq` itself was saved).

On a full drive, a repeating capture (`array-capture --continuous` / `--interval`, `project burst` / `stream`, a recipe `burst` / `stream`) **stops at that pass** instead of writing nothing to the same drive for the rest of the run. Any other failure is reported on every pass it happens, and the run carries on to the end, then exits `1`. `array-capture --continuous` (the backend's continuous capture) lists no files, failed ones included: it counts them on its progress and summary lines (`N failed`, `N file(s) failed to write.`) and exits `1` — see [Continuous mode](#continuous-mode---continuous).

The recorders — `array-burst` and `array-record` — report their own failures. `array-burst` stops itself when the drive fills, or just before it does. Both keep going past any other failed write. When either one reports an error it is printed after the counters, and the command **exits `1`**:

```
  Recorder error: disk-full: OSError: [Errno 28] No space left on device
  Disk full: the drive the backend captures to has no space left. Free space on it (or capture to another drive) before capturing again.
```

`Disk low:` in place of `Disk full:` means the burst stopped short of filling the drive. The frames recorded before the stop are kept. `array-burst --build` skips the build when space ran out, because the videos would go to the same drive. Free space first, then run `array-build-video --burst-dir …`. After any other error the build still runs.

An `array-record` that wrote no frame at all is a failed recording too (`Recorder error: no-frames: the combined view published no frame to record …`, exit `1`) — see [`array-record`](#array-record--combined-index-videogif-monitoring-grade).

***

## Capture Modes, Recorders & Offline Reprocess

These all operate on a **persistent array** (run `array-connect` first). They mirror the GUI capture panel.

### `array-capture` modes

`array-capture` is a single command with four shutter modes plus a set of export toggles:

| Mode                   | Flag           | Behaviour                                                                                                                                                                                                                                   |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Single** *(default)* | (none)         | One synced capture group, then exit.                                                                                                                                                                                                        |
| **Continuous**         | `--continuous` | Back-to-back captures until `Ctrl+C`, `--count N` captures, `--duration S`, or a full drive. Runs the backend's own continuous capture (the GUI's Continuous mode) — see [Continuous mode](#continuous-mode---continuous) below.            |
| **Interval**           | `--interval S` | One pass every `S` seconds (measured from the start of each pass), same bounds.                                                                                                                                                             |
| **Fastest**            | `--fastest`    | Raw-only + the assigned DAQ reading + the combined-index composite; skips the radiance/reflectance/display math so the frame lands fast. Implies `--processing raw --force-daq`. Reprocess the saved `.daq` into calibrated products later. |

Export toggles (combine with any mode; all share the GUI/SDK endpoint):

| Flag                               | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--array-id ID`                    | The array to capture from (omit when only one is connected).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `-o, --output DIR`                 | Output folder (default `output`, under the folder you run the command from).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--format {tiff,tif,png,jpg,jpeg}` | File format (default `tiff`). PNG / JPEG take only `display` and the index render; see [Capture Export Levels](#capture-export-levels-the-all-default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--processing LEVEL`               | Single export level (`raw`, `debayered`, `radiance`, `reflectance`, `display`), or `all` (default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--levels L1,L2,…`                 | Explicit subset of export types (e.g. `raw,radiance,reflectance`); **overrides `--processing`**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--aligned` / `--no-aligned`       | **Default: aligned, as the Chloros app's capture of the same array is** (its per-array **Aligned** Capture Setting, on unless you turn it off). Every member's non-raw export (`debayered`, `display`, `radiance`, `reflectance`, the index render) is warped into the master camera's frame and cropped to the members' common overlap, so the files are pixel-registered and come out the size, crop and `Alignment*` tags the app's do — smaller than the sensor (or the ROI) by the members' offsets; under an ROI the transform is re-based onto the window. `XMP-mapir:AlignmentJSON` says `"applied": true` and gives the `crop_roi`. Raw stays unwarped at the native size but carries the transform in metadata (`"applied": false`). `--no-aligned` saves every file at the native size, unwarped. `--aligned` is the default spelled out. Whether or not the warp is applied, each member file records its camera's `Alignment*` transform once the array has an alignment profile — except a camera the profile does not align (left out, or forced to identity by a failed solve), and the reference camera when no other camera is aligned: those carry no `Alignment*` tags. With no profile on the array the capture is saved unaligned, and the CLI prints the reason on an `Alignment:` line, as it does for every other case the warp could not be applied (members at different resolutions, an array not cable-synced, a frame the profile cannot be mapped onto). The array's auto-alignment makes the profile once its exposure settles; `align-calibrate` makes one on demand. |
| `--orient`                         | Turn each member's **products** — `display`, `radiance`, `reflectance`, the `index/` render and the `composite/` — by the camera orientation, after the alignment warp: a product warped into the master's frame (the default) by the **master's** orientation, so the members stay co-registered; an unaligned one (`--no-aligned`, or a capture the warp could not be applied to) by its own camera's. **Default: off — every member file stays native**, as array captures always have. `raw` and `debayered` stay native either way. Every file records the orientation its products carry (see [Camera orientation](#what-a-captures-folder-looks-like)); the `Alignment*` XMP stays the native-frame transform, applied before the orientation, so `process` (warp, then orientation) reproduces the live product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--index` / `--no-index`           | Save / skip the per-cam vegetation-index overlay where one is configured. Default: render it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--no-daq`                         | Skip the `.daq` sidecar when no chosen level uses the DAQ (a raw-only grab). By default the reading is saved, so the frames can be reprocessed into reflectance/index offline. `--force-daq` is still accepted (the default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--daq-tolerance-ms MS`            | The DAQ match tolerance for these captures (default 500 ms).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--smart`                          | Wait for AE to settle across all cams before triggering (see [Smart-AE / Smart-Capture](#smart-ae--smart-capture)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--compression {deflate,none}`     | TIFF pixel compression. `none` (default since 1.3.0; 1.2.0 wrote `deflate`) = uncompressed — the sensor's pixels exactly as read, \~6.3 MB per full-res frame, and the fastest sustained rate; `deflate` = lossless zlib L1 + horizontal predictor, \~4.1 MB per frame, slower. Both are lossless and read identically on import.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

> **Single-write TIFF + the sustained-rate model.** Every file is written **once**: pixels, the XMP packet, IFD0 Make/Model/CameraSerialNumber and the EXIF `ExposureTime` / `SerialNumber` tags in one pass, with nothing rewriting it afterwards. `--continuous` captures consecutive synced groups — each capture takes the group after the previous one, including one published while that capture was still saving — so it runs at the array's rate. DEFLATE holds the Python GIL, so compressed writes do **not** parallelize across the per-cam writer threads; sustained full-res capture at sensor rate needs uncompressed writes (the default) **and** NVMe-class disk (\~600 MB/s sustained for a 9-camera array at \~10 fps). The same knob is exposed as `compression` on `POST /api/camera/array/capture`.

```bash
# Interval timelapse: one reflectance pass every 10 s for 5 minutes
chloros-cli lattice array-capture --interval 10 --duration 300 \
  --processing reflectance -o timelapse/

# Fastest grab for a moving rig — raw + .daq now, calibrate later
chloros-cli lattice array-capture --fastest -o flightline/

# Co-registered multi-band export (aligned is the default; drop the index overlay)
chloros-cli lattice array-capture --processing reflectance --no-index -o out/

# Each member at its native size, unwarped
chloros-cli lattice array-capture --processing reflectance --no-aligned -o native/

# Continuous raw capture for 60 s, as fast as the array publishes
chloros-cli lattice array-capture --continuous --duration 60 --fastest -o flightline/
```

#### Continuous mode (`--continuous`)

`array-capture --continuous` (without `--interval` or `--smart`) hands the run to the **backend's own continuous capture** — the session the GUI's Continuous mode runs. The backend saves every synced group itself, with two captures in flight and no request from the CLI between groups, so it keeps up with a fast array where a request per capture falls behind (measured 73–77 captures/s on a 9-camera array at a 512-pixel ROI). Every export toggle above applies to each capture.

* **Bounds:** `--count N` stops after N captures (one capture = one synced group: every member's files); `--duration S` after S seconds. Without either it runs until `Ctrl+C`, a full drive, an error, or the array going away. `Ctrl+C` stops the backend's session, then prints the summary.
* **Progress** every 2 s, with `, N failed` and `, N groups skipped` appended when non-zero (a skipped group is one the array published that no capture took):

  ```
     12.0s  880 captures (73.3/s), 7920 files
  ```
* **No per-file listing.** The run ends with one summary line — captures, rate, files and the output folder — followed by `N file(s) failed to write.` / `N group(s) skipped.` when non-zero:

  ```
  Done — 880 captures (73.3/s), 7920 files in /home/user/flightline.
  ```
* **Stops** on a full drive with `Continuous capture stopped: the drive is full.`, and on an error or the array going away with `Continuous capture stopped: <reason>.` (both on stderr).
* **Exit status:** `0` when it saved captures and every file was written, `Ctrl+C` included; `1` on any file that failed to write, a full drive, an error, the array going away, or no capture at all.
* **Microsoft Defender:** when Defender spends a CPU core or more scanning the files the capture writes, the run prints once, on stderr: `Note: Microsoft Defender is using N.N CPU cores scanning the capture files, CPU the capture needs. Re-run the Chloros installer with "Exclude the Chloros backend from Microsoft Defender scanning" checked.` See the installer's [System settings](#windows-exe).
* One continuous capture per array at a time; a second is refused with `a continuous capture is already running for this array`. Over HTTP the session is `POST /api/camera/array/continuous/start` (the `/api/camera/array/capture` body plus `max_captures` / `duration_s`), `GET /api/camera/array/continuous/status?array_id=ID` and `POST /api/camera/array/continuous/stop`.

**Interval** (`--interval S`, with or without `--continuous`) and **`--continuous --smart`** keep the per-request loop: one capture request per pass — at each scheduled moment for Interval, after AE settles for `--smart` — with every pass's files listed as in Single mode, a `Done — N capture pass(es).` line at the end, and `--count N` counting passes.

### `array-record` — combined-index video/GIF (monitoring-grade)

Records the array's **live combined-index view** to an `.avi` (and optionally a `.gif`). With the GUI's combined view open, it records that view as displayed. With none open, the backend renders the view itself: the index you pass with `--expr`, or by default the array's NDVI, once the array is aligned. The default NDVI uses the red and NIR bands nearest 660 nm and 850 nm, as the live view does. A GUI view opened during the recording is recorded while it stays open. It polls progress every 2 s and stops on `--duration`, `Ctrl+C`, or when the recorder self-ends.

A recording that writes no frame fails: the recorder reports `no-frames: …` (the array may still be aligning or settling its exposure) and the command **exits `1`**.

```bash
# 30-second combined-index clip at 10 fps, plus a GIF (no GUI needed)
chloros-cli lattice array-record --duration 30 --fps 10 --gif -o monitoring/

# Record a chosen index instead of the default NDVI
chloros-cli lattice array-record --duration 30 \
  --expr "(NIR_850_RGN-Red_660_RGN)/(NIR_850_RGN+Red_660_RGN)" -o monitoring/
```

| Flag               | Default          | Description                                                                                                                                                                                                                                                                                                                           |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--array-id ID`    | only array       | Target array (omit if just one is connected).                                                                                                                                                                                                                                                                                         |
| `-o, --output DIR` | `output`         | Output directory. A relative path is under the folder you run the command from.                                                                                                                                                                                                                                                       |
| `--fps F`          | `10`             | Recording frame rate.                                                                                                                                                                                                                                                                                                                 |
| `--duration S`     | until Ctrl+C     | Auto-stop after `S` seconds.                                                                                                                                                                                                                                                                                                          |
| `--gif`            | off              | Also write an animated GIF.                                                                                                                                                                                                                                                                                                           |
| `--gif-only`       | off              | Write only a GIF (no `.avi`).                                                                                                                                                                                                                                                                                                         |
| `--expr EXPR`      | the array's NDVI | Index expression to record when no GUI view is open, in the array's band names (e.g. `'(NIR_850_RGN-Red_660_RGN)/(NIR_850_RGN+Red_660_RGN)'`; see [band names](#index--vegetation-maths)). A short colour name (`NIR`, `Red`) works only when one band of the array has it. A GUI view that is open is recorded as displayed instead. |

### `array-burst` — raw-Bayer high-fps burst (analysis-grade)

Reads the grab loop's synced-group buffer directly — **no calibration chain, no exiftool, no live view needed** — so it runs at the camera's full grab rate. Writes raw frames + a per-frame manifest + one `.daq` per distinct DLS reading under `<output>/bursts/<base>/`. Reprocess offline (next command), or pass `--build` to do it immediately on stop.

```bash
# 5-second raw burst, then build the combined index video in one shot
chloros-cli lattice array-burst --duration 5 --build \
  --products combined:index --fps 10 -o capture/
```

| Flag               | Default          | Description                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--array-id ID`    | only array       | Target array.                                                                                                                                                                                                                                                                                                  |
| `-o, --output DIR` | `output`         | Output directory (burst lands in `<DIR>/bursts/<base>/`).                                                                                                                                                                                                                                                      |
| `--duration S`     | until Ctrl+C     | Auto-stop after `S` seconds.                                                                                                                                                                                                                                                                                   |
| `--max-frames N`   | unbounded        | Auto-stop after `N` raw frames.                                                                                                                                                                                                                                                                                |
| `--orient`         | off              | The products a build makes from this burst are turned by the camera orientation — per-camera products by their own camera's, the combined index by the master's — as `array-capture --orient` does. The raw frames stay native; the burst's `manifest.json` records every member's orientation and the option. |
| `--build`          | off              | After stopping, immediately reprocess the burst (same as `array-build-video`).                                                                                                                                                                                                                                 |
| `--products …`     | `combined:index` | With `--build`: which video(s) to build (see below).                                                                                                                                                                                                                                                           |
| `--fps F`          | `10`             | With `--build`: output video fps.                                                                                                                                                                                                                                                                              |
| `--save-tiffs`     | off              | With `--build`: also save per-frame calibrated TIFFs (each with its [unmix clamp mask](#unmix-clamp-mask-which-pixels-a-band-was-clamped-on) when a pixel clamped; the build result lists them as `clamp_masks`).                                                                                              |
| `--gif`            | off              | With `--build`: also write animated GIF(s).                                                                                                                                                                                                                                                                    |

### `array-build-video` — offline reprocess a saved burst

Time-matches each raw frame to the nearest saved `.daq` reading and pushes it through the **same radiance / reflectance / index chain as the import pipeline**, rendering one or more videos.

`--products` is a comma list of `kind:level` items, where `kind` ∈ `per_cam` | `combined` and `level` ∈ `radiance` | `reflectance` | `index`. A bare `level` (no `kind:`) defaults to `per_cam`. Default is `combined:index`.

```bash
# Per-cam reflectance video for every member + one combined NDVI video
chloros-cli lattice array-build-video \
  --burst-dir "capture/bursts/2026-06-24_141500" \
  --products per_cam:reflectance,combined:index \
  --fps 10 --save-tiffs
```

| Flag              | Default          | Description                                                  |
| ----------------- | ---------------- | ------------------------------------------------------------ |
| `--burst-dir DIR` | (required)       | Path to the burst folder (`…/bursts/<base>/`).               |
| `--products …`    | `combined:index` | `kind:level` list, as above.                                 |
| `--fps F`         | `10`             | Output video fps.                                            |
| `--save-tiffs`    | off              | Also save per-frame calibrated TIFFs alongside the video(s). |
| `--gif`           | off              | Also write animated GIF(s).                                  |

**A video holds no clamp mask** (one image stream, 8-bit). Instead the build result carries `clamp_fractions`: per video product, every frame's share of pixels the unmix clamped in the band its R / G / B channel holds — the `Chloros:Band{R,G,B}UnmixClampFraction` that frame's radiance/reflectance product would be stamped with (for the combined index, each member camera's). The run prints the worst frame per product on a `Clamp:` line. `--save-tiffs` adds the per-pixel masks for the TIFFs, in `clamp_masks/<level>/` beside the TIFFs' `<level>/` folder.

**A build cut short leaves no broken video.** Each video is written as `<name>.partial.avi` and takes its final name only when it is finished, so an older video of that name stays until its replacement is whole. Run the build again to replace a `.partial.avi` left behind.

The run prints every video it wrote, then any `Skipped:` product (a requested camera/level — or the combined index — that produced no video, with the reason — e.g. no calibration bundle, no DLS reading for reflectance, or no red/NIR band pair for the combined index) and any `Note:`. An RGB camera asked for radiance or reflectance gets its display video instead, white-balanced when the camera's calibration bundle is available; a camera rendered without it is named in a `Note:`. It **exits non-zero** when a requested product was skipped or was not built as requested (a configured index expression is not evaluated offline); the videos that were built are still written and listed.

> **Pick the right recorder.** `array-record` is *monitoring-grade* — it records the rendered live composite: the GUI's combined view, or with no GUI open the backend's own NDVI (or `--expr`) view. `array-burst` → `array-build-video` is *analysis-grade* — it saves raw sensor data at full rate and reconstructs calibrated radiance/reflectance/index videos afterward, with no live view required.

### Mono (M3M) Single-Band Cameras

The **M3M** line is the mono sibling of the Bayer **M3C**: one narrowband interference filter per camera (`M3M-<lens>-F<wavelength>`, e.g. `M3M-L87-F685`), so the sensor delivers a **single grayscale band** with no Bayer mosaic. There is nothing to demosaic, no inter-channel crosstalk to unmix, and no white balance to set — the whole RGB-display colour pipeline simply doesn't apply.

What that means on the CLI:

* **`lattice white-balance`, `lattice color-profile`, `lattice color`** detect a mono cam and **skip with a one-line message** instead of pushing meaningless settings. They still run normally against an RGB/Bayer M3C cam in the same session.
* **A Bayer pixel format means its depth.** An M3M offers only Mono formats, so a Bayer one from `--pixel-format` or `--preset` sets the Mono format of the same depth: `BayerRG8` and `--preset high_speed` give `Mono8`; `BayerRG12`, `high_quality` and `triggered` give `Mono12`; a packed name stays packed (`BayerRG12p` gives `Mono12p`). The files and `lattice format` name the Mono format. An array that mixes M3C and M3M cameras takes one format the same way: Bayer on each M3C, its Mono depth on each M3M. A name is its bit depth: the same holds the other way round, so an M3C is never put on a Mono format (`--pixel-format Mono12` is `BayerRG12` on an M3C, whichever camera is the array's master), and `lattice format --set` maps the same way and prints the format it set.
* **`lattice calibrate` / `process --reflectance` / `array-capture --processing radiance`** still work — radiance and reflectance are *per-band* radiometric maps and are perfectly well-defined for one band. Mono frames carry an **identity** sensor-response matrix (no 3×3 unmix), so the plane passes through the calibration math untouched.
* **A single mono cam cannot produce a vegetation index.** NDVI/NDRE/etc. need at least two bands (e.g. Red + NIR). To get an index from mono hardware, point **several** M3M cams at different wavelengths, align them into one multi-band stack, and index *that*:

```bash
# Red (660) + NIR (850) mono pair -> aligned 2-band stack -> NDVI
chloros-cli lattice index --live --profile align.json \
  --preset NDVI --channel red=Mono_660 --channel nir=Mono_850 \
  --save-multiband -o output/
```

`index --live` opens the cameras itself (a [transient session](#multi-camera-transient-sessions)), so connect nothing first: `--serials`, else the profile's enabled cameras (see [Index / Vegetation Maths](#index--vegetation-maths)). While Chloros holds any camera (the GUI, `cam-connect`, `array-connect`) it is refused with HTTP 409 `CAMERA_HELD` and exits `1`; release them with `chloros-cli lattice cam-disconnect --all` / `chloros-cli lattice array-disconnect --all`.

`--channel` symbols must match the preset's channel names **exactly** (case-sensitive; NDVI's are lowercase `red`,`nir` — see `--list-presets`), and the band side names a band in the aligned stack (offline mode also accepts 0-based band indices, e.g. `--channel red=0 --channel nir=1`).

The discriminator throughout the stack is the `M3M` token in the model string (it never appears in an `M3C` string), surfaced to the GUI/SDK as `is_mono`.

***

## Host NIC Setup & Tuning (LATTICE arrays)

LATTICE cameras stream GVSP over the host's Ethernet adapter, so for multi-camera arrays the adapter's **driver** and **receive-ring size** matter as much as the link rate. Wrong settings surface as a `FRAMES WILL DROP` / `Reduce ROI to enable` gate in the Array Settings panel (and in `lattice network-analysis` / the SDK's `analyze_array_network()`), even when the cameras themselves are healthy.

### USB 10GbE adapters — Realtek RTL8157 ("Realtek USB 10GbE Family Controller")

The settings below are Windows driver properties. On Linux a USB adapter gets a cap too (400 MB/s on x86\_64, 200 MB/s on NVIDIA Jetson) (see [Array fps & burst model](#array-fps--burst-model)), and the kernel's socket receive buffers matter for every adapter — see [Linux hosts](#linux-hosts--socket-receive-buffers).

| Item                                             | Required value                                   | Why it matters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Driver version**                               | **≥ v10.67 (Jan 2026)**, INF `rtump64x64sta.inf` | The legacy **2016** driver (v10.65, `rtump64x64.inf`) mishandles power-down and bugchecks with **`DRIVER_POWER_STATE_FAILURE` (BSOD `0x9F`)** on shutdown/restart/sleep. The transition hangs (\~5 min timeout), the user force-powers-off, and repeated unclean shutdowns **corrupt the WMI repository** (PowerShell/tools begin failing with `Invalid class`) and **wedge the USB stack** on the next boot (NIC won't enable; USB drives stop enumerating). Update from realtek.com (or the dongle vendor) before relying on clean restarts.                                                                                           |
| **Receive Buffers** — keyword `ReceiveBufferLen` | **256** (driver max)                             | The NIC RX ring. The driver default of **32** leaves only \~0.26 MB usable ring — far too small for a multi-cam burst — so the array panel reports `Sim-emit burst … exceeds NIC RX ring usable capacity 0.26 MB` and blocks connect. At **256** the ring is large (**\~13.5 MB measured on the lab 10GbE host**), giving the RX pipeline real headroom for multi-cam GVSP bursts. (Whether a given config actually *connects* is decided by two checks — the **drain-aware** admittance check and the **aggregate over-subscription** check — not a raw burst-vs-ring compare; see [Array fps & burst model](#array-fps--burst-model).) |
| **Receive URBs** — keyword `PendingReceives`     | **64** (max)                                     | USB request blocks in flight; raise alongside Receive Buffers for burst absorption.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Jumbo Frame** — keyword `*JumboPacket`         | **9014**                                         | Needed for 9000-byte GVSP packets (6× fewer packets/frame than 1500).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

> ⚠️ **A NIC driver update RESETS these advanced properties to defaults.** After updating or replacing the adapter driver, **re-apply** `ReceiveBufferLen=256` and `PendingReceives=64`, or the array panel will gate again even though "nothing changed in the hardware." This is the #1 cause of a previously-working rig suddenly refusing to connect.

Apply from an **elevated** PowerShell (substitute your adapter name, e.g. `"Ethernet 5"`):

```powershell
Set-NetAdapterAdvancedProperty -Name "Ethernet 5" -RegistryKeyword ReceiveBufferLen -RegistryValue 256
Set-NetAdapterAdvancedProperty -Name "Ethernet 5" -RegistryKeyword PendingReceives  -RegistryValue 64
Get-NetAdapterAdvancedProperty  -Name "Ethernet 5" -RegistryKeyword ReceiveBufferLen,PendingReceives   # verify
```

> **`lattice network --fix` covers USB 10GbE adapters.** It now detects the adapter type and tunes the correct receive-ring keyword: `*ReceiveBuffers`→2048 for PCIe NICs (Intel I219, etc.), or `ReceiveBufferLen`→256 + `PendingReceives`→64 for the Realtek **USB** 10GbE controller (which does not expose `*ReceiveBuffers`). Targets are clamped to each driver's reported max (`NumericParameterMaxValue`), so it never writes an out-of-range value. Run it from an **elevated** terminal; like any registry-based tune, the change takes effect after an adapter restart or reboot. The manual `Set-NetAdapterAdvancedProperty` commands above remain a fine alternative — they apply live (re-bind the adapter) without a restart.

### Linux hosts — socket receive buffers

On Linux, NVIDIA Jetson included, the kernel's socket receive buffers matter as much as the NIC's receive ring. At the kernel default (`net.core.rmem_max` / `net.core.rmem_default` = 212,992 bytes) a camera's burst of GVSP packets overflows the stream socket before Chloros reads it. The packets are dropped in the kernel while the NIC itself reports no loss, and an array loses frame groups and backs its frame rate off. Measured on a 4-camera array behind a USB 10 GbE adapter, raising both to 32 MB took the array from 4.96 to 7.52 fps after connect, and a continuous raw capture from 4.7 to 7.6 captures/s, with no packets dropped in the kernel.

* **The .deb sets them.** Installing the package writes `/etc/sysctl.d/60-chloros-gige.conf` (both at `33554432`) and applies it at once. A value already set higher is left alone.
* **`lattice network` checks them.** When either is lower, it lists `socket receive buffers too small for GigE Vision (…)` under *Issues found*, and the backend's log carries the same warning at the first camera or array connect.
* **To raise them by hand** (until the next reboot; the package's file applies them at every boot):

  ```bash
  sudo sysctl -w net.core.rmem_max=33554432 net.core.rmem_default=33554432
  ```

  `lattice network --fix` raises and persists them too, but only when the backend runs as root. A backend that runs as your user (one started with `chloros-backend`, or [`chloros-backend@<user>`](#running-the-backend-as-a-service-headless)) cannot change kernel settings, and prints the `sudo sysctl` line instead.

**The automatic adapter tune touches only connected adapters.** At the first camera connect, a backend running as root tunes the wired adapters whose receive ring is small. It now tunes only adapters with a link, so an unplugged onboard port keeps its MTU, and it leaves the receive buffers alone. `lattice network` no longer lists an unplugged adapter's MTU as an issue. `lattice network`, `--fix`, `lattice probe` and the adapter tune consider only wired Ethernet ports, not a Jetson's CAN bus (`can0`) or the USB device-mode links (`usb0`, `usb1`) it offers a host PC; a USB Ethernet adapter for cameras still counts.

### Network basics (all LATTICE links)

* **Addressing:** link-local `169.254.0.0/16` (GigE Vision LLA). The host takes a static `169.254.x.x/16`; cameras + DAQ-E self-assign in the same range. No DHCP/gateway required.
* **Packet size:** prefer jumbo (9000), but let the auto-probe find it — it looks past the camera's 1500-byte ICMP cap via a GVSP probe, so it lands on jumbo wherever the wire truly carries it. **Each camera is measured once per backend session, and again when its link changes (another adapter, another link speed, or a link that dropped, as swapping a switch does); reconnects reuse the result. After a change behind a switch that stayed up, restart the backend to measure again.** A first connect can occasionally take a few minutes on this check, and the log says so when it does. Pin with `CHLOROS_GVSP_PACKET_SIZE_FORCE=9000` only when you know better than the probe, and prefer per-command over permanent: a pin skips the probe, so if the path can't actually carry 9000 **every** capture times out with `SC_ERR_TIMEOUT -1011` (see [Environment Variables](#environment-variables)).
* **RX ring scales with `ReceiveBufferLen`:** at the default `32` the usable ring is \~0.26 MB (too small for any multi-cam burst); at the max `256` it is large (\~13.5 MB measured on the lab 10GbE host), giving real headroom. Whether a config connects is then decided by the drain-aware admittance check **and** the aggregate over-subscription check below — not a raw burst-vs-ring compare.

### Array fps & burst model

How to read the Array Settings panel (and `lattice analyze-array` / the SDK's `analyze_array_network`):

* **Burst is summed per-camera at each cam's real pixel format.** Mono **M3M** cams stream **Mono12 (2 B/px)**, or with `--pixel-format` the Mono format of its depth (`BayerRG8` is `Mono8`, 1 B/px); **M3C** Bayer cams stream 8- or 12-bit (M3C firmware silently emits BayerRG12 even when BayerRG8 is requested). So a 4-cam full-res frame is **\~12.6 MB if all 8-bit but \~25 MB with three 12-bit mono cams**. The projection resolves each cam's format from its model (identity cache), so the burst matches what the wire actually carries — not a one-size BayerRG8 assumption.
* **A USB Ethernet adapter is capped at 200 MB/s regardless of its nameplate.** The efficiency table that turns a link rate into a sustained figure is PCIe-derived; a USB NIC advertises its *Ethernet* link rate but is bounded by the USB bus and its driver. A USB 10GbE dongle used to score \~1063 MB/s "sustained" — a number that was never probed — and the resulting pacing corrupted 6–18 % of frames while still reporting a healthy target fps. USB-attached NICs are now capped as an absolute: **200 MB/s** on Windows and on NVIDIA Jetson, **400 MB/s** on Linux x86\_64 (on Linux, an adapter on a USB 2.0 port is budgeted **30 MB/s**, and the capability record says to plug it into a USB 3 port) (the limit is the host's USB bus and driver, so it does not scale with the nameplate; a USB 1 GbE adapter derives \~80 MB/s and is unaffected). On Linux the adapter is identified from sysfs (falling back to `ethtool -i`'s `bus-info`). Each figure is measured: on Windows the same 4-camera array corrupted 6–10 % of frames above 200 MB/s; on Linux x86\_64 the same adapter ran clean at every ceiling up to 480 MB/s (273 MB/s delivered, the cameras' own limit). On NVIDIA Jetson the same adapter was clean only at 200 MB/s and lost frames intermittently above it. `wire_ceiling_source` on the capability record says so in words, and `nic_is_usb` flags it. Override either way with `--wire-ceiling-mbps`.
* **Admittance is drain-aware, not whole-burst-vs-ring.** A simultaneous burst only has to fit the *transient backlog* = `max(0, Σ per-cam arrival − host drain) × emit_window`, not the entire burst. On a fast-host / slow-cam fabric (a **PCIe** 10G host + 4× 1 GbE cams: arrival ≈ 320 MB/s, drain ≈ 1063 MB/s) the host drains faster than the cams fill, backlog ≈ 0, so full-res sim-emit **admits** even though the 25 MB burst exceeds the 13.5 MB ring. Put the same four cameras behind a **USB** 10GbE adapter on Windows and the drain is 200 MB/s, not 1063 — arrival outruns it, and the loss shows up as corrupt frames rather than as a lower frame rate. On a 1 GbE host the cams' 31.25 MB/s DLThr floor makes arrival outrun the drain → it correctly **blocks** (for *this* class of block, reduce ROI or use binning ≥ 2). Admittance is one of **two** connect gates — the other is the aggregate over-subscription check below.
* **Projected fps is the slowest camera's cycle.** In simultaneous emit every camera sends its frame at the same time, so the array cycles at the longer of its slowest member's sensor readout and emit time (frame bytes ÷ its emit rate: the camera's **access link**, 1 GbE ≈ 80 MB/s, or its share of the host's wire ceiling when that is smaller). Each exposure overlaps the previous frame's readout, so exposure does not enter the cycle: auto exposure fills the period the rate gives, then raises gain, and a dim scene no longer lowers the rate (in 1.2.0 it did). Only a manual exposure longer than the period slows the trigger (see [Exposure on an array member](#exposure-on-an-array-member)). Adding cameras does not slow the array until their wire shares shrink. In serial emit (`slip-emit-and-capture`) the cameras' emit times add up instead, and each member's exposure is priced into the stagger. Measured at full sensor, 12-bit, on a 9-camera array with a PCIe 10 GbE host: 10.7 fps, or 14.0 fps with [packed transport](#packed-12-bit-transport---packed).
* **After a continuous capture, the projection says what it held.** A capture of 30 s or more at an automatic rate records the rate it settled on at that array size on this computer; the rate controller's short trials of a faster rate are left out. From then on `array-connect`'s line and the Array Settings panel quote that rate when it is below the model's, with what limited it: `clock-bound` (the array ran at the rate it settled on, the grab loop waiting on its trigger clock), `loop-bound` (the grab loop had no time left), `capture-bound` (the capture fell behind and skipped groups) or `measured` (nothing says which). The model's figure is in `wire_fps_max`. The array still climbs to what the wire carries.
* **An array works on any network — the frame rate is what gives.** Each camera gets an even share of the **collision-safe wire ceiling** (`sustained × sim_emit_factor`), paced with GevSCPD, and all of them still expose on the same trigger. On a slow wire the share is small and the frame rate falls with it: 8 full-res 12-bit cameras on 1 GbE without jumbo frames get 52 / 8 = 6.5 MB/s each, about **1 fps** (about 1.3 fps packed), where a 10G host runs them at 11-14. If the cameras cannot be paced that slowly — connect reads each camera's GevSCPD range to find out — the array switches to **serial** emit (`slip-emit-and-capture`): the cameras take turns on the wire at full link rate, triggered one after another, so every frame still arrives but the members are **not exposed simultaneously**. `analyze-array` and the connect output name the mode; pin `--force-tier sim-capture-sim-emit` to refuse the fallback. Frame size does not enter this sharing, so **binning and a smaller ROI raise the frame rate but do not change whether an array fits**. Only a wire that cannot carry the array even serially is **over-subscribed** — e.g. far more cameras than one wire can pace, or many other cameras streaming on it — and there the symptom is GVSP packet loss, not a lower rate: `analyze-array` zeroes the achievable-fps figures and prints `** OVER-SUBSCRIBED **`, the connect goes ahead with a loud warning, and an HTTP connect with `pin_resolution: true` (strict mode) **refuses** instead. Remedies are fewer cameras, jumbo frames end-to-end, or a faster NIC. `CHLOROS_ARRAY_ALLOW_OVERSUBSCRIBED=1` downgrades the refusal to a loud warning for bench work — see [Environment Variables](#environment-variables).

### Array health — which subsystem is losing frames

A connected array's `GET /api/camera/array/<array_id>/capability` carries a live `health` block, re-evaluated on a rolling **10-second** window. It splits frame loss into the two causes that need opposite fixes, rather than reporting one "incomplete" rate that names neither:

| Field                                                | What it means                                                                 | Which subsystem                                       |
| ---------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
| `gvsp_corrupt_rate_pct` (per serial)                 | The frame **arrived and was structurally bad** — GVSP packet loss.            | **Network**: wire budget, pacing, NIC RX ring, MTU    |
| `never_arrived_rate_pct` (per serial)                | The frame **never came at all** — the camera didn't fire, or nothing left it. | **Trigger / sync**: M8 cable, `--line`, `TriggerMode` |
| `worst_gvsp_corrupt_pct` / `worst_never_arrived_pct` | The worst camera's rate for each.                                             | —                                                     |
| `per_cam_rate_pct`                                   | Combined incomplete rate per camera (both causes together).                   | —                                                     |
| `stable_for_seconds`                                 | How long every camera has stayed under 0.01 %.                                | —                                                     |

Above 5 % the backend logs an `[array-health <id>] WARN` line naming the split — on the first breach, on a severity-band change, once a minute while it persists, and once when it clears. The corrupt half writes `[gvsp-corrupt <SN>]` to the backend log file on the first hit per camera and reason, then a roll-up every 60 s; the app's log panel shows the `[array-health <id>]` line instead. Every evaluation still lands in the backend log file; the counters move on every buffer regardless of what is printed.

The same record reports the number the whole allocation hangs off:

| Field                      | What it means                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wire_ceiling_mbps`        | The host's sustained wire budget in force, MB/s.                                                                                                                                                                                                           |
| `wire_ceiling_source`      | Where that number came from, in words — e.g. `USB-capped 200 MB/s (was theoretical 1062; PnPDeviceID=USB\VID_0BDA&PID_815A)` (on Linux x86\_64, `USB-capped 400 MB/s (…; sysfs: bus=usb (usb2/2-1/2-1:1.0))`) or `user override 120 MB/s (auto said 200)`. |
| `wire_ceiling_is_user_set` | `true` when `--wire-ceiling-mbps` (or the GUI's **Wire Budget** field) set it.                                                                                                                                                                             |
| `nic_is_usb`               | `true` for a USB Ethernet adapter — see the USB cap above.                                                                                                                                                                                                 |

**Reading it:** non-zero `gvsp_corrupt_rate_pct` with `never_arrived_rate_pct` at 0 means triggering and cable sync are perfect and 100 % of the loss is on the network path — lower `--wire-ceiling-mbps` and reconnect. The reverse pattern points at the sync cable or the trigger line instead.

> **`--target-fps` is not the lever for corrupt frames.** GevSCPD pacing is written once at connect, so lowering the trigger rate changes the duty cycle and not the simultaneous-emit burst rate. A measured 5× demand cut produced no improvement; dropping the wire ceiling from 240 to 200 MB/s took the same rig from 10.4 % corrupt to 0.00 %.

> **A running array cannot re-plan itself on LATTICE (M3C / M3M) firmware.** It cannot fix this itself; disconnect and reconnect so the connect-time picker can re-plan with the new ceiling.

### Symptom → fix

| Symptom (Array Settings / connect / `analyze_array_network`)                                                                                                | Cause                                                                                                                                                                   | Fix                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FRAMES WILL DROP … exceeds NIC RX ring usable capacity 0.26 MB`, `Reduce ROI to enable`                                                                    | `ReceiveBufferLen` reset to 32 (typically after a driver update)                                                                                                        | Set `ReceiveBufferLen`→256, `PendingReceives`→64; reopen the panel (restart the backend if it cached the old ring size)                                                                                             |
| Restart/shutdown hangs; later `Invalid class` WMI errors, NIC won't enable, USB drives missing                                                              | Old 2016 Realtek USB 10GbE driver → BSOD `0x9F` → forced power-offs                                                                                                     | Update the adapter driver to ≥ v10.67 (2026), then re-apply the receive-ring settings above                                                                                                                         |
| Array connects at full sensor but a low frame rate                                                                                                          | Auto keeps the full sensor and lets the rate fall to what the wire carries                                                                                              | Take one of the faster options the connect output lists (`--binning 2` / `4`, or a smaller `--width`/`--height`), enable jumbo frames, or upgrade the link                                                          |
| Array reports a healthy target fps but delivers a fraction of it; `health.gvsp_corrupt_rate_pct` non-zero, `never_arrived_rate_pct` 0                       | The host's inferred wire budget over-states what it actually sustains (typical on a USB Ethernet adapter, a thin PCIe lane, or a shared fabric)                         | Reconnect with a lower `--wire-ceiling-mbps` and re-check the health block. **Not** `--target-fps` — GevSCPD pacing is fixed at connect                                                                             |
| Linux: an array loses frame groups and backs its frame rate off while the NIC reports no drops; `lattice network` lists `socket receive buffers too small`  | The kernel's socket receive buffers are at their default, so camera packets are dropped in the kernel                                                                   | Raise `net.core.rmem_max` / `rmem_default` to 32 MB — see [Linux hosts](#linux-hosts--socket-receive-buffers). The .deb does this at install                                                                        |
| Cameras missing from published groups; `health.never_arrived_rate_pct` non-zero, `gvsp_corrupt_rate_pct` 0                                                  | Trigger / sync path — the cams are not firing, not a network problem                                                                                                    | Check the M8 sync cable and `--line`; confirm every member is armed (`TriggerMode=On`)                                                                                                                              |
| `** OVER-SUBSCRIBED **` / `Wire budget` exceeded in `analyze-array`, or connect refusal in strict mode (`pin_resolution`; `array over-subscribes the wire`) | The wire cannot carry the array at any pacing the cameras reach, simultaneously or in turn — far more cameras than the wire can share, or other cameras streaming on it | Fewer cameras, jumbo frames end-to-end, or a faster NIC. **ROI/binning will NOT help** (sharing is frame-size-independent). `CHLOROS_ARRAY_ALLOW_OVERSUBSCRIBED=1` overrides on the bench (accepts the packet loss) |
| Array connects in `slip-emit-and-capture` (serial) on a slow network                                                                                        | The cameras cannot be paced slowly enough to share the wire simultaneously, so they take turns; frames are not exposed at the same instant                              | Jumbo frames or a faster NIC restore simultaneous capture; `--force-tier sim-capture-sim-emit` insists on it (and loses packets instead)                                                                            |

***

## `chloros-cli daq`

Spectral-sensor commands. The `pool-*` commands are thin HTTP clients that drive the sensor through the backend's persistent pool, so they need a running backend (see [Start the Backend](#start-the-backend)). The backend owns the transport, so the CLI and SDK scripts share one live handle instead of fighting over the serial port. `pool-discover` is the only way to learn a DAQ-M's BLE MAC.

> **`chloros-cli daq --help`** (or `-h`, or `daq help`) lists the `pool-*` subcommands (on Linux, together with the direct-hardware commands that build includes), and `chloros-cli daq <subcommand> --help` (or `daq help <subcommand>`) gives each one's options. They cover connect, stream, record calibrated `.daq` files, swap cap profiles and bind a DAQ to a camera, and for a DAQ-E its network settings, PTP, a restart and firmware updates. The DAQ can also be driven from Python with `chloros_sdk.connect_daq_sensor()`, which uses the same pooled path.
>
> **Use the `pool-*` commands on every platform.** They behave the same on Windows, Linux and Jetson. On Windows, `daq discover` and `daq list` are aliases of `pool-discover`, and any other `daq` command that is not `pool-*` exits `1` with `DAQ direct-hardware commands require the full daq package`. On Linux and Jetson, `daq discover`, `daq list` and the other non-`pool-*` `daq` commands are the DAQ tool's direct-hardware commands: they open the sensor in the CLI's own process, outside the backend's pool (so not on a sensor the backend, the GUI or a script holds), and `daq discover` there takes `--only` and `--timeout` but not `--json`. This reference documents the `pool-*` commands only.

### DAQ Sensor First-Connect Workflow

```bash
# 1. Scan every transport, showing the address to connect with.
#    This is how you find a DAQ-M's BLE MAC — unlike a DAQ-E hostname or a
#    DAQ-U serial port, a MAC isn't printed on the device or listed by the OS.
chloros-cli daq pool-discover
chloros-cli daq pool-discover --only ble           # BLE only
chloros-cli daq pool-discover --json               # machine-readable

# 2. Open a persistent pool session (handle stays alive across CLI calls)
chloros-cli daq pool-connect                                   # smart-detect
chloros-cli daq pool-connect --port /dev/ttyUSB0               # DAQ-U on a serial port (Windows: COM3)
chloros-cli daq pool-connect --mac AA:BB:CC:DD:EE:FF           # DAQ-M by BLE MAC
chloros-cli daq pool-connect --eth-host daq-e-xxx.local        # DAQ-E by hostname

# 3. List what's in the pool, including the sensor_id you'll use next
#    (DAQ-U ids look like 'CB-7C-A8-2E-5F'; DAQ-E ids like 'daq-e-def330')
chloros-cli daq pool-list

# 4. Read the latest spectrum frame
chloros-cli daq pool-latest --sensor-id CB-7C-A8-2E-5F

#    Bind it to a camera, so that camera's captures use and save its readings
chloros-cli daq pool-bind --camera 213800234 CB-7C-A8-2E-5F

# 5. Record a calibrated .daq file for 60s
chloros-cli daq pool-record --sensor-id CB-7C-A8-2E-5F --duration 60 \
  -o ~/Documents/spectra --device-name "field-A"

# 6. Release
chloros-cli daq pool-disconnect --sensor-id CB-7C-A8-2E-5F
```

### `pool-*` Reference

| Subcommand                                                                                                                     | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daq pool-connect` (smart-detect)                                                                                              | Open a sensor in the backend pool.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `daq pool-connect --port PORT` (`-p`)                                                                                          | DAQ-U on a specific serial port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `daq pool-connect --ble`                                                                                                       | DAQ-M over BLE, MAC auto-scanned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `daq pool-connect --mac MAC` (`-m`)                                                                                            | DAQ-M over BLE at a known MAC (implies `--ble`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `daq pool-connect --eth-host HOST`                                                                                             | DAQ-E over Ethernet at a known hostname or IP (implies `--eth`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `daq pool-connect --eth`                                                                                                       | DAQ-E over Ethernet, host auto-discovered (mDNS + ARP fallback; works from a cold ARP cache on Windows and Linux).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `daq pool-connect --integration-time MS (-t) --frame-avg N (-f) --no-ae`                                                       | Tune integration window / AE state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `daq pool-connect --no-stream`                                                                                                 | Connect but do not start streaming yet (resume with `pool-stream --start`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `daq pool-connect --cap-id {none, fov_15, fov_30, fov_45, fov_60, fov_90, sunshine_cosine}`                                    | Cap-correction profile. Default at the backend is `sunshine_cosine`; `none` is a bare sensor. A [DAQ-E-S](#daq-e-s--fixed-diffuser-and-tilt-sensor) ignores it (fixed diffuser). **The sensors ship bare, so name the cap you fitted:** the default is recorded as assumed (`cap_id_source=auto_default`) and processing warns about it, since a bare DAQ-U under the sunshine correction reads \~30x high.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `daq pool-discover [--only usb,ble,eth] [--timeout SEC] [--json]`                                                              | Scan every transport for sensors you could connect to, without connecting. **This is how you find a DAQ-M's BLE MAC.** `--timeout` is per transport (default 5 s, 1-20). Sensors already open in the pool are not listed — a connected DAQ-M stops advertising — so use `pool-list` for those. `usb` lists USB serial devices only: a computer's own serial ports (`COM1`, Linux's `/dev/ttyS*`) cannot be a sensor and are left out.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `daq pool-list`                                                                                                                | Show every sensor in the backend pool.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `daq pool-bind (--camera SERIAL \| --array ARRAY_ID) {SENSOR \| --clear}`                                                      | Bind a camera or an array to a DAQ, as the GUI's light-sensor selection does: its captures use, match and save that DAQ's readings. `SENSOR` is a sensor id from `pool-list` or the address the DAQ is reached on. `--clear` (no `SENSOR`) drops the binding, and the captures fall back to the freshest DAQ. The binding lasts until the backend restarts, or until that camera, array or DAQ is disconnected: a disconnect (here, from the SDK or in the app) drops every binding of the hardware it disconnects, whoever set it, an array's members' with the array's. The camera must be connected, in the open project, or opened on this computer before, and the array connected or in the open project; any other serial or id is refused by name and nothing is bound.                                                                |
| `daq pool-disconnect {--sensor-id ID \| --all}`                                                                                | Release — whoever opened the sensor, so it also frees a sensor a crashed script left in the pool (any recording on it is finished first). A sensor that is not in the pool has nothing to release: it prints `ID: already released (not in the pool)` and exits `0`; a release the backend refused or did not confirm exits `1`. SDK: `DAQSensorSession.force_disconnect()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `daq pool-latest --sensor-id ID [--recent N] [--json]`                                                                         | The most recent N spectrum frames (default 1).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `daq pool-stream --sensor-id ID [--start \| --stop]`                                                                           | Resume / pause streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `daq pool-record --sensor-id ID [--duration SEC] [-o DIR] [--device-name NAME] [--confirm-after S] [--heartbeat S]` / `--stop` | Start / stop a .daq recording. `-o` defaults to `~/Documents/DAQ Live View` on the backend's computer (a relative path is under the folder you run the command from); `--duration` (`-d`, default `0` = until `--stop`). `--confirm-after S` warns when no reading has arrived S seconds after the start (default 20; 0 turns it off); with `--duration`, `--heartbeat S` prints the reading count every S seconds and warns when it stops growing (default 30; 0 turns it off). A recording on a DAQ-E that goes silent carries on in the same file once the backend has reconnected it, and `--stop` lists the gaps ([A DAQ-E That Stops Delivering](#a-daq-e-that-stops-delivering)). Ctrl+C ends a `--duration` recording early and reports it; without `--duration` the recording keeps running after Ctrl+C (exit `130`) until `--stop`. |
| `daq pool-set-cap --sensor-id ID --cap-id CAP`                                                                                 | Swap the cap-correction profile at runtime. `--cap-id` is required; `--cap-id none` removes the cap correction (a bare sensor). A DAQ-E-S keeps `as_recorded` whatever is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `daq pool-enable-ptp --sensor-id ID`                                                                                           | Switch PTP back on for a DAQ-E whose PTP is off. The setting is saved on the unit, so a unit left off stays off — its timestamps are not PTP-synced — until this is run. `pool-list` flags such a unit (`!! PTP is switched OFF`) and prints this command for it. Chloros never switches a unit back on by itself, because off can be deliberate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `daq pool-info --sensor-id ID [--json]`                                                                                        | A DAQ-E's own settings: its firmware (and whether this Chloros release carries a newer one), its address and how it got it (DHCP / link-local / static), the saved network setting until the sensor runs it (one saved with `--no-reboot` included), stream at power-on, and PTP. On a sensor whose stream is not reaching this computer it reads the sensor on a fresh connection and says so.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `daq pool-set-network --sensor-id ID {--auto \| --static IP [--mask M] [--gateway G]} [--no-reboot] [--force] [--timeout S]`   | Set a DAQ-E to DHCP (`--auto`) or a static address (`--mask` default `255.255.255.0`). The sensor restarts to apply it and is reconnected with the settings it had, waiting up to `--timeout` seconds (default 45) for it; `--no-reboot` only saves it. See [DAQ-E Device Settings](#daq-e-device-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `daq pool-set-auto-stream --sensor-id ID {--on \| --off}`                                                                      | Whether a DAQ-E starts streaming at power-on with no software connected (saved on the sensor). Chloros starts the stream itself either way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `daq pool-reboot --sensor-id ID [--timeout S]`                                                                                 | Restart a DAQ-E and reconnect it with its previous settings (waits up to `--timeout`, default 45 s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `daq pool-update-firmware --sensor-id ID [--timeout S]`                                                                        | Flash the DAQ-E firmware included with this Chloros release onto a sensor running an older version, then reconnect it (about a minute; do not power it off; `--timeout` default 45 s for it to come back). A sensor already current is left alone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### A DAQ-E That Stops Delivering

A DAQ-E in the pool that delivers no spectrum for 20 seconds is reconnected by the backend. A power cycle of the switch that powers the sensor does this: the sensor restarts with it and does not stream again until it is told to (unless `pool-set-auto-stream --on`).

* **It checks that it is the same sensor first.** It asks at the address the sensor had, changing nothing, for the sensor's name, MAC and serial. It also asks under the sensor's `daq-e-<id>.local` name, but trusts that answer only when it comes from the sensor's own network adapter (MAC). Nothing else that answers is reconnected or written to.
* **It reconnects with the session's settings:** integration time, frame averaging, auto exposure and cap profile as they were, not the sensor's power-on defaults. A sensor that had PTP on and came back with it off is switched back on. Then it restarts the stream, and the computer's receiver for it.
* **It retries at growing intervals:** at once, then after 5, 10, 20 and 40 seconds, then every 60 seconds while the sensor is gone. Each try only asks the sensor who it is. A sensor that answers but still sends nothing after three reconnects is left alone and reported (`auto-reconnect GAVE UP`). `pool-stream --start` tries again.
* **`pool-list` shows where it stands.** While the sensor is silent, its `STREAM FAULT` line says what the reconnect is doing. The line clears with the first spectrum, and the sensor then reads `reconnected automatically N time(s)`.
* **A recording carries on in the same `.daq`.** The file marks each gap with two rows: `event_type` 5 at the last spectrum before the gap and 6 at the first after it, each with a timestamp only. `pool-record --duration` prints `!! STREAM LOST …` while the sensor is gone and `stream resumed after …` when it is back. `pool-record --stop` lists each gap and warns, as it does for an empty file (a recording that holds no reading exits `1`).
* **A recording keeps one calibration.** If the sensor comes back with a different calibration while a recording runs, the rest of the recording keeps the one it started with, and the stop warning says so. `pool-disconnect` + `pool-connect` takes up the new one.
* **Your commands win.** A sensor you `pool-disconnect`, or pause with `pool-stream --stop`, is never reconnected, even when a reconnect is already under way.
* **`pool-info` on a silent sensor** reads the sensor on a fresh connection and adds `!! stream NOT reaching this computer`. A sensor that does not answer is reported at once. `pool-list` no longer shows a PTP state for a sensor that has stopped answering.
* DAQ-U and DAQ-M are not covered. A DAQ-M reconnects over Bluetooth by itself, and a DAQ-U unplugged from USB needs `pool-connect` again.

### DAQ-E-S — fixed diffuser and tilt sensor

The **DAQ-E-S** is a DAQ-E with two differences that matter to software. Everything else — discovery, connecting, PTP, recording, the device settings below — works exactly as for a DAQ-E.

**Its diffuser is permanent, so it takes no cap correction.** The Sunshine-style diffuser is built in and was on the unit when its factory calibration was measured, so that calibration already reads true downwelling irradiance. Chloros sets its cap to `as_recorded` (no profile) whatever is asked: a cap named for it (`sunshine_cosine`, `fov_*`, `none`) is ignored with a message, and its recordings store `cap_id_source=model`, so the assumed-cap warning never fires for it. Do not apply a cap to its data by hand either: `sunshine_cosine` on top would read about 11x high.

**It carries a 3-axis accelerometer.** The sunshine diffuser's cosine response is only valid while it is level, so a tilted sensor reports a wrong irradiance — and reflectance inherits the error — with no other symptom. Each DAQ-E-S reading therefore carries its attitude:

| Field                               | Meaning                                                                                                                                                                          |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tilt_deg`, `roll_deg`, `pitch_deg` | Angles in degrees. `None` when the firmware marks the angle undefined (free fall, a dead axis).                                                                                  |
| `x_mg`, `y_mg`, `z_mg`, `mag_mg`    | Acceleration in milli-g. `mag_mg` far from \~1000 means the unit was moving and the angles are not meaningful for that sample.                                                   |
| `cal_applied`                       | Set: the axes and angles are in the diffuser's frame (the unit's mounting calibration is applied). Clear: raw board frame, which can show up to \~2.3° of tilt that is not real. |
| `sample_age_ms`                     | Age of the accelerometer sample when the spectrum was sent.                                                                                                                      |
| `temp_raw`                          | Uncalibrated die-temperature **trend** — differences only, never a thermometer reading.                                                                                          |

`daq pool-latest --json` returns them under each frame's `imu` key (`null` on a DAQ-U, DAQ-M or plain DAQ-E). A `.daq` recorded from a DAQ-E-S stores the same values in its `imu_*` columns (`imu_tilt_deg`, `imu_roll_deg`, `imu_pitch_deg`, `imu_mag_mg`, `imu_cal_applied`, …) beside every spectrum, so a reader can tell a cloud from a knocked tripod. On every other model those columns are empty.

The attitude stream is reported on its own: `daq pool-list` prints `!! ATTITUDE STREAM FAULT (spectra unaffected)` while it is down, and how many faults it recovered from afterwards. A fault there never marks a gap in the spectral recording. `daq pool-discover` lists the unit as `DAQ-E-S` (as `DAQ-E` if it does not answer the identity check within about 2 s).

### DAQ-E Device Settings

```bash
chloros-cli daq pool-info --sensor-id daq-e-def330

# A fixed address on the network this computer is on (192.168.1.x)
chloros-cli daq pool-set-network --sensor-id daq-e-def330 \
  --static 192.168.1.50 --gateway 192.168.1.1

# Back to the factory setting: DHCP, falling back to a 169.254.x.x
# link-local address when no DHCP server answers
chloros-cli daq pool-set-network --sensor-id daq-e-def330 --auto

chloros-cli daq pool-update-firmware --sensor-id daq-e-def330
```

* **`--static` without `--gateway` saves no gateway** (any gateway set before is dropped), which is right for a camera network with no router.
* **A static address must be on this computer's network.** Chloros refuses one whose subnet does not include this computer's address on the sensor's network: after the restart nothing could reach the sensor to change it back. Pass `--force` only when this computer will be readdressed, or routed, to the new subnet.
* **A restart is refused while the sensor records.** Stop the recording first (`pool-record --stop`). A recording started in the moment before a restart is closed by it, and `pool-set-network`, `pool-reboot` and `pool-update-firmware` end with a `Warning:` line naming the recording's file (also when the sensor then does not come back).
* **After a restart Chloros reconnects only the sensor itself.** It waits where the sensor was -- and after `--auto` also under its `daq-e-<id>.local` name -- for an answer with the sensor's name, hostname and model, from the network adapter (MAC) it had, and reconnects it at the address that answered. An answer under the name is accepted only with that MAC, so from a computer that reaches the sensor through a router, or from WSL2 in its default NAT networking, a sensor that DHCP moved to a new address is not reconnected: the command says so and prints the `pool-connect --eth-host <its address> …` command that brings it back with the cap and exposure settings it had.
* **`pool-update-firmware` refuses a sensor whose firmware version it cannot read.** A sensor that takes longer than the wait to come back after the flash has not failed: once it answers it is reconnected with the new firmware's settings filled in, and the command warns that it was slow.
* **A firmware update needs an inbound TCP connection.** The sensor connects back to this computer to collect the image. Chloros listens on the adapter that routes to the sensor (on every adapter only when it cannot tell which) and serves only the sensor's own address; any other connection is closed unserved. On Windows the installer's `Chloros Backend (TCP-In)` firewall rule lets it in (see [Windows (.exe)](#windows-exe)); a firewall that blocks it fails the update with `… device never connected back on TCP <port> …`.
* **Under WSL2, use mirrored networking** (`networkingMode=mirrored` in `%UserProfile%\.wslconfig`). In the default NAT mode this computer's address on the sensor's network is WSL's own, so every static address is refused (short of `--force`), the live stream does not reach WSL, and a firmware update cannot complete, because the sensor connects back to the computer to receive the image.
* **The sensor ID and hostname do not change.** Whatever its address, a DAQ-E is still `daq-e-<id>` and `daq-e-<id>.local`, so `--eth-host daq-e-<id>.local` keeps finding it.
* **The GUI has the same settings**: Light Sensors tab, the sensor's settings (gear), Network. The GUI keeps its own connection to a sensor, so change a sensor the GUI has open from the GUI: a restart from the CLI ends the GUI's session with it.
* The SDK equivalents are `DAQSensorSession.device_info()`, `set_network()`, `set_auto_stream()`, `reboot()` and `update_firmware()`.

***

## `chloros-cli project`

Open, connect to, and drive a saved Chloros project (a folder with `cameras.json` + `sensors.json` + `project.json`). Everything routes through the backend so the GUI and CLI produce identical hardware state.

### Subcommand Reference

| Subcommand                                                                                                                                                                                                                                    | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project open PATH [--relink FOLDER]`                                                                                                                                                                                                         | Print the project's device manifest (cameras, arrays, sensors), read from its files, and check its source files (see [A moved project](#a-moved-project---relink)). It does not open the project in the backend: the project open there, and its devices and recordings, stay as they are. Exits `1` when none of the project's source files can be found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `project devices PATH [--reconnect]`                                                                                                                                                                                                          | List or re-run discovery.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `project connect PATH [--cameras-only] [--sensors-only] [--packed {auto,on,off}]`                                                                                                                                                             | Connect every saved camera / array / sensor. Each array connects as `lattice array-connect` does: up to 600 s, its steps printed to stderr (`[array <id>] <s> s: <step>`; stdout is the JSON report), and an array not connected in that time is undone — its cameras put back as found — and reported under `errors`, never left connected. `--packed` sets every array's packed 12-bit transport (default `auto`; a project saves no per-array setting; see [Packed 12-bit transport](#packed-12-bit-transport---packed)). Each light sensor is opened in the backend's DAQ pool at its saved address with its saved integration time, frame averaging, auto-exposure and cap: a sensor with no cap chosen gets `sunshine_cosine`, one saved bare (`none`) stays bare, and a DAQ-E-S never takes a cap. The GUI's DAQ panel is not part of the pool: close a sensor there first. |
| `project capture PATH NAME [-o DIR] [--format FMT] [--exposure US] [--gain DB] [--prefix P] [--orient]`                                                                                                                                       | Single capture from a named camera or array (`--prefix` default `capture`). `--orient` (arrays): the array saves raw, which stays native — this records that the products `process` makes from it are to be oriented, as `array-capture --orient`. Default: native. `project burst` / `stream` and a recipe's `capture` / `burst` / `stream` (`orient: true`) take the same option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `project burst PATH NAME [-n N] [-i S] [-o DIR] [--format FMT] [--exposure US] [--gain DB] [--prefix P] [--orient]`                                                                                                                           | N-frame burst from a named camera or array (`-n/--count` default 5; `-i/--interval` inter-frame seconds, default 0). Array bursts de-dup repeated synced groups (staleness watchdog) so a partial-cycling array can't hand back N copies of one frame; prints per-iteration results. A capture that fails partway stops the burst and exits `1`, saying how many were saved before it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `project stream PATH NAME [-n N] [--fps F] [-o DIR] [--format FMT] [--exposure US] [--gain DB] [--orient]`                                                                                                                                    | Capture to disk in a loop: `--fps F` captures a second (default 3), one frame per capture from a camera, one synced frame group from an array (with the same staleness watchdog as `project burst`), until `-n N` captures (default `0` = until Ctrl+C, which prints how many were saved and exits `0`, or `1` when none was or a file failed; a Ctrl+C before `-n N` captures exits `130`). A capture that fails partway stops the stream and exits `1`, saying how many frames were saved before it. `--poll-interval` is deprecated and ignored: it is still accepted so older scripts run, with a note on stderr.                                                                                                                                                                                                                                                              |
| `project sensor read PATH NAME [--json]`                                                                                                                                                                                                      | Latest spectrum frame.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `project sensor log PATH NAME [--seconds SEC] [-o DIR] [--device-name NAME]`                                                                                                                                                                  | Record a .daq for `--seconds` (default 10). A recording that holds no reading is reported on stderr and exits `1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `project run PATH RECIPE.yaml`                                                                                                                                                                                                                | Execute a YAML/JSON capture recipe. `--dry-run` validates without running.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `project align calibrate PATH NAME [--method M] [--model M] [--frames N] [--reference SN] [--max-features N] [--ratio-threshold F] [--ransac-threshold-px F] [--min-matches N] [--max-reproj-err-px F] [--checkerboard RxC] [--name PROFILE]` | Compute alignment for an array — see [the flag table below](#project-align-calibrate-options).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `project align status PATH NAME [--json]`                                                                                                                                                                                                     | Print current alignment profile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `project align clear PATH NAME`                                                                                                                                                                                                               | Drop the cached profile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `project align tweak PATH NAME --serial SN [--dx N] [--dy N] [--rotation-deg N] [--scale N]`                                                                                                                                                  | Nudge one slave's transform (defaults `0`, `0`, `0`, `1.0`: no change).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `project align export PATH NAME --to FILE`                                                                                                                                                                                                    | Save the profile to JSON.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `project align import PATH NAME --from FILE [--no-validate]`                                                                                                                                                                                  | Load a saved profile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

#### `project align calibrate` Options

| Flag                                                                             | Default       | Description                                                                                                                                                                                |
| -------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--method {feature_orb, feature_akaze, phase_correlation, checkerboard, manual}` | `feature_orb` | Alignment method. **These spellings differ from `lattice align-calibrate`**, which takes the short forms `orb` / `akaze` / `phase`; the two commands are not interchangeable on this flag. |
| `--model {translation, rigid, affine, homography}`                               | `affine`      | Transform model to fit.                                                                                                                                                                    |
| `--frames N`                                                                     | `1`           | Synced frame snapshots to average.                                                                                                                                                         |
| `--reference SN`                                                                 | the master    | Reference camera serial; every other member is warped onto it.                                                                                                                             |
| `--max-features N`                                                               | `5000`        | ORB feature-count cap.                                                                                                                                                                     |
| `--ratio-threshold F`                                                            | `0.75`        | Lowe's ratio test.                                                                                                                                                                         |
| `--ransac-threshold-px F`                                                        | `3.0`         | RANSAC inlier threshold.                                                                                                                                                                   |
| `--min-matches N`                                                                | `15`          | **Quality gate** — refuse the solve below this many inlier matches.                                                                                                                        |
| `--max-reproj-err-px F`                                                          | `4.0`         | **Quality gate** — refuse the solve above this RMS reprojection error.                                                                                                                     |
| `--checkerboard RxC`                                                             | —             | Board geometry for `--method checkerboard`, e.g. `9x6`.                                                                                                                                    |
| `--name PROFILE`                                                                 | empty         | Profile name embedded in the saved JSON. **Not the array name** — that is the positional `NAME`.                                                                                           |

The two quality gates are the reason a calibrate can succeed at solving and still decline to save: a profile that fails either one would silently mis-register every later capture, so it is refused rather than persisted.

### A moved project (`--relink`)

A project's `project.json` names each source file -- every image and light-sensor recording -- by its full path. Move the project folder, or the whole projects folder to another drive, and those paths still name the old place.

Opening a project fixes what it can on its own: a file that was inside the project's folder is looked for in the folder the project is in now, and every path found there is re-pointed and saved (`project.json` is first backed up as `project.json.before-relink-<date>-<time>`). This happens on every open -- the app's, `chloros-cli project open`, `chloros-cli process` into an existing project, the SDK's and `chloros-mcp`'s. A path is only ever re-pointed at a file that is there.

Files that were outside the project folder -- a hub session, an Add Folder import -- cannot be found that way. Name the folder they are in now:

```bash
chloros-cli project open "N:/Chloros Projects/Field_A" --relink "E:/backup/Hub Projects"
```

`--relink` takes the folder the files went to, or any folder above it: each missing file's folder is looked for under it by its trailing folder names (`Hub Projects/<session>/raw/<serial>`, then `<session>/raw/<serial>`, ...), and each folder's files are taken from the one place that finds the most of them. `project open` prints what was re-pointed, how many source files were found, and the folders the rest were in. Some still missing: a warning, exit `0` -- the project opens with the rest. None found: an error naming those folders and `--relink`, exit `1`; the backend likewise refuses to open such a project for `process` or `project devices --reconnect` (HTTP 409 `PROJECT_SOURCES_MISSING`).

### Examples

```bash
# Open a project and see what it knows about
chloros-cli project open "/home/user/Chloros Projects/Field_A"

# Its hub captures moved to another drive: point it at them
chloros-cli project open "/home/user/Chloros Projects/Field_A" --relink "/media/backup/Hub Projects"

# Connect everything saved in the project
chloros-cli project connect "/home/user/Chloros Projects/Field_A"

# Capture from a named camera (defined in cameras.json)
chloros-cli project capture "/home/user/Chloros Projects/Field_A" FrontLeft \
  -o output/ --format tiff

# Capture from a named array
chloros-cli project capture "/home/user/Chloros Projects/Field_A" main_rig \
  -o output/ --format tiff

# Capture with overrides
chloros-cli project capture "/home/user/Chloros Projects/Field_A" main_rig \
  --exposure 5000

# Read a spectrum
chloros-cli project sensor read "/home/user/Chloros Projects/Field_A" Sky --json

# Record a DAQ log
chloros-cli project sensor log "/home/user/Chloros Projects/Field_A" Sky \
  --seconds 120 -o ~/Documents/spectra/

# Align an array (live)
chloros-cli project align calibrate "/home/user/Chloros Projects/Field_A" main_rig
chloros-cli project align status "/home/user/Chloros Projects/Field_A" main_rig

# Run a recipe
chloros-cli project run "/home/user/Chloros Projects/Field_A" recipe.yaml
```

### Recipe DSL

`project run RECIPE.yaml` accepts a YAML or JSON file describing a sequence of actions:

```yaml
# recipe.yaml
overrides:
  cameras:
    FrontLeft:
      exposure_us: 5000
      target_brightness: 80

stop_on_error: true
actions:
  - apply:
      name: FrontLeft
      settings:
        auto_exposure: "Off"
        gain_db: 6.0
        auto_gain: "Off"
  - wait: 2s
  - capture:
      name: FrontLeft
      output: pose_a/
      format: tiff
  - stream:
      name: main_rig
      count: 60
      fps: 5
      output: stream/
  - burst:
      name: main_rig
      count: 10
      interval: 0.5
      output: burst_a/
      format: tiff
  - sensor:
      name: Sky
      action: read
```

Supported actions: `apply`, `wait`, `capture`, `stream`, `burst`, `sensor`. `apply` takes the `cameras.json` `settings` keys — `exposure_us`, `auto_exposure`, `gain_db`, `auto_gain`, `target_brightness`, … (the older names `exposure_time`, `exposure_auto`, `gain`, `gain_auto` are accepted as aliases). An exposure, gain or target set this way is held as yours: Chloros's automatic exposure control (including the DAQ-metered exposure) leaves it alone. A manual exposure leaves gain as it was: on auto, the camera keeps adjusting gain (over its full range) toward the target brightness until you set `gain_db` or `auto_gain: "Off"`. A later `auto_exposure: "Continuous"` hands exposure back to automation, and `target_brightness_auto: true` hands a held target back to Chloros's automatic target. The `burst` action takes `name` (required), `count` (default 5), `interval` (seconds, default 0), `output`, `format`, and `settings` (same per-camera settings shape as `apply`); array bursts use the same fresh-synced-group watchdog as `project burst`.

A `capture`, `burst` or `stream` step's `output` defaults to `output`. A relative `output` — the default included — is resolved against the folder you run `chloros-cli project run` from, not the recipe file's folder or the project folder (in 1.2.0 it landed in the backend's install folder).

Run it:

```bash
chloros-cli project run "/path/to/project" recipe.yaml

# Dry-run to validate without firing hardware
chloros-cli project run "/path/to/project" recipe.yaml --dry-run
```

**Every run is checked first, against the project.** Each action must be exactly one of the verbs above as its key — `- capture: {name: FrontLeft}`, not `- action: capture` or `- type: capture` — with a `name` the project's `cameras.json` / `sensors.json` has, a camera or array for `apply` / `capture` / `burst` / `stream` and a light sensor for `sensor`; a `stream` needs `count` > 0 and a `wait` a duration. A recipe with any such error runs **no** action (`[recipe] error: …`, `[recipe] not run: …`, exit `1`), even with `stop_on_error: false`. Keys a step does not use are a `[recipe] warning:`, as is every array or light sensor the recipe drives that is not connected now. A recipe never connects devices: run `chloros-cli project connect PATH` first. `--dry-run` prints the recipe, then the same errors and warnings and `[recipe] valid: …` / `NOT valid: …`, runs nothing, and exits `1` when the recipe has an error.

***

## Environment Variables

| Variable                             | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CHLOROS_BACKEND_URL`                | Override the backend URL (default `http://127.0.0.1:5000`) — **honoured only by the `lattice`, `project`, and `daq pool-*` command families** (`lattice network-analysis` takes `--backend-url` instead). The core commands (`process`, `login`, `logout`, `status`, `export-status`, `time-sync`, `selftest`) pin `http://127.0.0.1:<port>` and ignore this variable (the IPv4 literal sidesteps the Windows `localhost`→`::1` \~2 s-per-request penalty), so they always target the local machine. |
| `CHLOROS_ARRAY_ALLOW_OVERSUBSCRIBED` | Set in the backend's environment. `1` downgrades the over-subscription refusal — an array connect with `pin_resolution`, or a [transient multi-camera command](#multi-camera-transient-sessions) (`error_code` `ARRAY_OVERSUBSCRIBED`) — to a loud warning, accepting GVSP packet loss. For testing only — see [Array fps & burst model](#array-fps--burst-model).                                                                                                                                   |
| `CHLOROS_ARRAY_PACKED12`             | Set in the backend's environment: `on` or `off` sets the default of [packed 12-bit transport](#packed-12-bit-transport---packed) for every array (default `auto`). An explicit `--packed` still wins.                                                                                                                                                                                                                                                                                                |
| `CHLOROS_DISABLE_UPDATE_CHECK`       | `1` (or `true` / `yes`) turns off the Linux CLI's [automatic update check](#chloros-cli-update) at startup.                                                                                                                                                                                                                                                                                                                                                                                          |
| `CHLOROS_CLI_MODE`                   | Set by the CLI itself; tells the backend to enable parallel processing.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `CHLOROS_GVSP_PROBE_FALLBACK`        | `0` skips the GVSP fallback probe (ICMP results only). **This turns jumbo off, it doesn't just quieten the log** — the camera answers DF pings only up to 1500 on every path, so this probe is the only thing that can detect jumbo. Saves \~1 s per camera per connect; costs \~1.45× wire ceiling if the network *could* have carried jumbo. The SDK warns when you set it.                                                                                                                        |
| `CHLOROS_GVSP_SESSION_REUSE`         | Set in the backend's environment: `0` measures the packet size on every connect instead of once per camera per backend session.                                                                                                                                                                                                                                                                                                                                                                      |
| `CHLOROS_GVSP_PACKET_SIZE_FORCE`     | Pin GVSP packet size to N bytes; skips probing entirely. Prefer per-command (`CHLOROS_GVSP_PACKET_SIZE_FORCE=9000 chloros-cli …`) over setting it permanently: a pinned size stops adapting to the network in front of it, and pinning 9000 on a path that can't carry jumbo makes **every** capture time out with `SC_ERR_TIMEOUT -1011`.                                                                                                                                                           |
| `CHLOROS_TRANSIENT_AE_SETTLE_S`      | Set in the backend's environment: the most seconds a [transient multi-camera command](#multi-camera-transient-sessions), or a `lattice capture` of a camera nothing holds, spends setting each camera's exposure from the scene before it keeps a frame (default `5`). `0` turns it off: each camera's own auto-exposure then runs from the first frame, starting at its exposure limit.                                                                                                             |
| `CHLOROS_LOG_DIR`                    | Set in the backend's environment: the folder its detailed log goes to. Default `%LOCALAPPDATA%\Chloros\logs` on Windows, `~/.cache/chloros/logs` on Linux (`$XDG_CACHE_HOME/chloros/logs` when that is set). The .deb's root service sets `/var/log/chloros`, readable by the `adm` group — see [Running the backend as a service](#running-the-backend-as-a-service-headless).                                                                                                                      |
| `TMPDIR` (Linux)                     | Where temporary files go. The CLI auto-uses `/mnt/ssd/tmp` if present.                                                                                                                                                                                                                                                                                                                                                                                                                               |

***

## Exit Codes

| Code          | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`           | Success.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `1`           | Generic failure (most subcommand errors). A capture command also exits `1` when any file it was asked to write failed to write, even though the others saved, and `array-burst` / `array-record` exit `1` when the recorder reports an error — see [Files That Fail to Write](#files-that-fail-to-write). `process` also exits `1` when a run's exports could not be verified, or when it lost an image, though the other products are written.                                                                      |
| `2`           | Argument error (an unknown or missing flag; also `time-sync set-priority` with neither priority).                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `130`         | Interrupted by Ctrl+C: any command it cuts short — `lattice`, `project`, `daq` and `process` alike (`process` after the backend has stopped the run, see [`process` Notes](#notes)). A command whose normal stop is Ctrl+C — `lattice array-capture --continuous` / `--interval`, `lattice viewer`, `lattice continuous`, `multi-stream`, `align-stream`, `array-record`, `array-burst`, and `project stream` with `-n 0` — exits on what it did instead: `0` when everything was written, `1` when anything failed. |
| `143` / `129` | Killed by SIGTERM / SIGHUP (128 + the signal), after the command's cleanup ran: a running job stopped and its cameras put back, a processing run stopped in the backend. A `lattice continuous` or other recording whose normal stop is Ctrl+C exits `143` too, not `0`.                                                                                                                                                                                                                                             |

`lattice network-analysis` exits `1` for the `needs_force_slip` and `error` verdicts, and `selftest` exits `1` unless all seven checks pass.

***

## Troubleshooting Pointers

* **"Login required"** → Run `chloros-cli login EMAIL PASSWORD` once on this machine.
* **"The project folder is too deep for this computer"** → Windows long paths are turned off on this machine (the Windows default), so no path may pass 260 characters, and products sit up to about 130 characters below the project folder. Nothing was processed. The message gives the longest project folder that fits: use a shorter one (`-o`, or `chloros-cli set-project-folder`), or turn on Windows long paths and restart Chloros. The Windows installer offers this as "Enable Windows long paths", checked by default; otherwise use Group Policy: *Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths*.
* **"backend unreachable"** → Start the Chloros desktop app (Windows), or start the backend yourself: `"C:\Program Files\Chloros\backend\chloros-backend.exe"` on Windows (the `backend` folder of your install folder; it is not on `PATH`), `chloros-backend` on Linux. Or check `CHLOROS_BACKEND_URL` if remote.
* **`lattice` commands fail with "LATTICE camera drivers not found"** → The backend could not load the LATTICE camera runtime it is installed with. Every `lattice` command runs on the backend; the CLI itself carries no camera drivers. Reinstall Chloros: the Windows installer and the .deb install the runtime beside the backend.
* **Array connect / Array Settings shows "FRAMES WILL DROP" or "Reduce ROI to enable"** → Host NIC receive ring is too small (commonly reset to 32 after a NIC driver update). See [Host NIC Setup & Tuning](#host-nic-setup--tuning-lattice-arrays) — set `ReceiveBufferLen=256`, `PendingReceives=64`.
* **Machine hangs on restart/shutdown, then WMI `Invalid class` / NIC won't enable / USB drives missing** → Outdated USB 10GbE adapter driver causing `DRIVER_POWER_STATE_FAILURE` (BSOD `0x9F`). Update the adapter driver — see [Host NIC Setup & Tuning](#host-nic-setup--tuning-lattice-arrays).
* **Linux: captures belong to root, so you cannot delete them, and the backend's log is not in your `~/.cache`** → The backend runs as root through `chloros-backend.service`. Switch to `chloros-backend@<user>.service`, which runs it as you — see [Running the backend as a service](#running-the-backend-as-a-service-headless). Until then the root service's log is in `/var/log/chloros` (readable by the `adm` group).
* **Linux: a backend unit is `failed` with "Another instance is already running" (exit status 98)** → Another backend already holds the port: only one runs at a time. If two backend units are enabled, keep one: `sudo systemctl disable --now <unit>` for the one you do not use — see [Running the backend as a service](#running-the-backend-as-a-service-headless). If only this unit is enabled, a backend started outside systemd (by `chloros-backend`, `chloros-cli` or an SDK script) holds it: stop that backend, then `sudo systemctl start <unit>`.
* **Jetson swap warning** → Add file-backed swap; the CLI prints the exact `fallocate` / `swapon` commands.
* **"backend not reachable" from a `lattice`, `project` or `daq` command** → no backend is running: those commands never start one. Run `chloros-cli backend status`, and see [Start the Backend](#start-the-backend).
* **"`daq net ...` is not available in Chloros"** (Linux and Jetson) → Some of a DAQ-E's own settings are reserved for MAPIR service. Network settings, restarts and firmware updates are `pool-set-network`, `pool-reboot` and `pool-update-firmware`; contact MAPIR support for the rest.
* **"DAQ direct-hardware commands require the full daq package"** (Windows) → Use `pool-*`, which drives the same sensor through the backend, or `chloros_sdk.connect_daq_sensor()` from Python.

***

## See Also

* [Python SDK Reference](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/sdk-reference.md) — programmatic equivalent of every CLI command.
* [DAQ Light Sensors](https://mapir.gitbook.io/chloros/daq-light-sensors) in the Chloros manual — the sensors, their caps and calibrated range, recording, DAQ-E networking.
* [LATTICE Cameras](https://mapir.gitbook.io/chloros/lattice-cameras/lattice) in the Chloros manual — connecting, camera settings, capture modes, arrays.
* Online docs: `https://mapir.gitbook.io/chloros/cli`
