> 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/sdk-reference.md).

# Chloros Python SDK Reference

**Version:** 1.3.0 **Generated:** 2026-07-29 19:19 · **Revised:** 2026-11-06 **Package:** `chloros-sdk` (PyPI) **Audience:** Optimised for LLM consumption; human-readable. **Scope:** Every public class, function, and helper exposed by `import chloros_sdk`, with copy-pasteable examples covering image processing, single-camera control, synchronized arrays, DAQ sensors, and project automation, plus the `chloros-mcp` server for AI assistants.

If you only need the highlights, jump to:

* [Installation & Quickstart](#installation)
* [Smart-Connect for LATTICE Arrays](#smart-connect-for-lattice-cameras)
* [DAQ Sensor Sessions](#daq-sensor-sessions)
* [Camera Utilities](#camera-utilities)
* [Transient Arrays, Alignment Profiles & Indices](#transient-arrays-alignment-profiles--indices)
* [Project Folder & Recipes](#project-folder--recipes)
* [Project Automation](#project-automation--chlorosproject)
* [Smart-AE / Smart-Capture](#smart-ae--smart-capture)
* [Live Frames in Your Own Pipeline](#live-frames-in-your-own-pipeline)
* [MCP Server (AI Assistants)](#mcp-server-ai-assistants)

> **Changed in 1.3.0** (what an existing 1.2.0 script notices).
>
> **Changes a 1.2.0 script may need to handle:**
>
> * **A release the backend does not confirm now raises.** `CameraSession.disconnect()`, `ArraySession.disconnect()` / `force_disconnect()` on an array the session opened, `DAQSensorSession.disconnect()` / `force_disconnect()` on a sensor it opened, and `ChlorosProject.disconnect_all()` raise `ChlorosConnectError` when the backend refuses the release or does not confirm it in time, because the device may still be held. In 1.2.0 they returned quietly. A `with` block's exit still never raises.
> * **A borrowed device is never torn down.** `with attach_array(...)` and an explicit `disconnect()` on it leave the array running (in 1.2.0 leaving the block tore it down, even when the GUI owned it); call `force_disconnect()` when you mean to end it. Likewise a `connect_daq_sensor()` that found the sensor already in the pool, the zero-flag smart-detect included, leaves it open on `disconnect()` and on leaving its `with` block.
> * **PNG and JPEG take only the `display` and index products.** `capture()` with `format="png"` / `"jpg"` (`ext=".png"` / `".jpg"`) and a `radiance` or `reflectance` level, or `processing="all"`, raises `ValueError` before any request; a 12-bit `raw` / `debayered` is refused by the backend. See [PNG / JPEG](#png--jpeg-take-the-display-and-index-products-only).
> * **`connect_daq_sensor(sensor_id=...)` opens that sensor or raises** `ChlorosConnectError` listing what it found; it never falls back to another sensor. See [Pinned Transport](#pinned-transport).
> * **`frame_stream()` raises instead of going silent:** `FrameFetchError` on a refusal the next tick would repeat (a reflectance read with no DAQ at all included), after 60 s with no frame, and after 60 s with no new trigger. See [One trigger per read](#one-trigger-per-read--group_id).
> * **A read timeout or dropped connection raises `ChlorosConnectError`** from every smart-connect call and `analyze_array_network()`, where 1.2.0 raised the underlying timeout or connection error.
> * **`connect_array()` waits 600 s by default (`timeout`, 180 s in 1.2.0), and a connect it gives up on is undone.** The call sends its `timeout` to the backend, which puts every camera back as it was found and connects nothing when the connect is not done in time; the call raises `ChlorosConnectError` (HTTP 504 `CLIENT_DEADLINE_PASSED`). In 1.2.0 a connect right after the cameras powered on could outlast the call and connect the array after it had raised. `connect_all()` waits for each saved array the same way (120 s in 1.2.0). See [`connect_array()` Signature](#connect_array-signature).
> * **`connect_array()` keeps the full sensor.** With no `width` / `height` / `binning` every camera is set to the full sensor and the frame rate falls to what the host and network deliver; 1.2.0 shrank or binned the frames to keep the rate up. See [Synchronized Array](#synchronized-array--arraysession-smart-prep).
> * **A Bayer pixel format on an M3M (mono) camera is its depth.** An M3M offers only Mono formats, and the presets name Bayer ones: in 1.2.0 the camera refused the format and kept its own while `settings.pixel_format` named the Bayer one. `LatticeCamera(preset=...)`, `apply_preset()`, `set_format()`, a `CameraSettings(pixel_format=...)`, `connect_camera(preset=...)` and an array's shared format now set the Mono format of the same depth on an M3M: `"BayerRG8"` and `high_speed` give `Mono8`; `"BayerRG12"`, `high_quality` and `triggered` give `Mono12`; `cam.settings.pixel_format` names it. The same the other way round: an M3C is never put on a Mono format, so `"Mono12"` -- from any of these, `connect_array(pixel_format=...)`, `set_settings(pixel_format=...)` or an array's saved format -- gives `BayerRG12` on an M3C, whichever camera is the array's master. A `CameraSettings` you pass keeps its name, so the same object still asks each camera for that depth in its own family. `connect_camera(preset=...)` keeps the preset's format (1.2.0 set the camera to 12-bit after applying the preset), and a camera opened on a preset no longer writes what it took into `PRESETS`. Any other format a camera refuses (one its `PixelFormat` list lacks, such as `RGB8` on an M3M or `BayerRG16` on firmware without it) is not named as its own either: after a `LatticeCamera` connect, `apply_settings()` or `set_format()`, `cam.settings.pixel_format` and `packed_transport` name the format the camera streams, and one printed line names the format it refused.
> * **`analyze_array_network()` projects what connect applies:** `pixel_format=None` (was `"BayerRG8"`) means the formats connect sets (Mono12 / BayerRG12), and `packed="auto"` the packed-transport decision, so the fps it quotes can differ from 1.2.0's. A `pixel_format` you pass projects an M3M at that depth. See [Network-Analysis Helper](#network-analysis-helper).
> * **`CameraSession.capture()` returns a `CaptureResult`** (still a list of frame dicts) with `.skipped`, `.failed`, `.daq_files` and `.daq_matches`. An `ArraySession.capture()` result also carries `.alignment` (whether the alignment warp was applied, and why not) and `.oriented`.
> * **Array captures are aligned by default, as the app's are.** `ArraySession.capture()`, `continuous()`, `capture_repeated()` and `ArrayHandle.capture()` / `capture_smart()` warp every member's `debayered`, `display`, `radiance`, `reflectance` and index files into the master camera's frame and crop them to the members' overlap (smaller than the sensor by the cameras' offsets, `XMP-mapir:AlignmentJSON` `"applied": true`), so they are the same files as the Chloros app's capture of the same scene; `raw` stays native. Before, a capture without `aligned=True` saved every file at the native size, unwarped. `aligned=False` keeps that. `chloros-mcp`'s `capture_array` and `start_capture_run` take the same default. See [`ArraySession` Methods](#arraysession-methods).
> * **`connect_all()` names a backend that refuses the SDK.** A running backend that is logged out or on a plan below Copper is reported under `errors` with its own reason (HTTP 401 / 403), not as "no Chloros backend is running", and each `connect_all()` call checks the backend again, so calling it after logging in works on the same project object.
> * **A relative `output_dir` works against a local backend.** Relative paths are made absolute against your script's working directory before they are sent. In 1.2.0 the backend resolved them in its own install folder, which failed with "Access is denied".
> * **`numpy` is now a requirement** of the SDK (the live-frame calls return numpy arrays).
> * **An export level name that is not one is refused.** `processing=` and `levels=` 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`: `capture()` raises `ChlorosConnectError`, `grab()` / `frame_stream()` `FrameFetchError`); 1.2.0 saved or returned `raw` for it.
> * **Texture Aware is refused for LATTICE captures.** On a project holding LATTICE captures, `configure(debayer="Texture Aware (Slow, Highest Quality)")` raises `ChlorosConfigurationError`, and so does `process()` after a `configure()` that asked for it before the import. A Texture Aware value the project saved earlier is set to Standard, with a `UserWarning`. LATTICE captures always get the standard demosaic, so 1.2.0 accepted the setting and ignored it; the Chloros app does not offer it for them either. See [Supported Values](#supported-values).
> * **Cameras go back the way they were found — unless `keep_settings=True`.** `ArraySession.disconnect()` / `force_disconnect()`, the end of every transient function (`capture_cameras_transient()`, `start_multi_camera_stream()`, `test_array_sync()`, `calibrate_alignment_profile()`, `capture_aligned_multiband()`, `start_aligned_stream()`, `capture_live_index()`) and the stop of `start_camera_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=True` instead saves each camera's settings into the camera's own memory, so it powers up with them; `clear_settings=True` 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 SDK, the app, the CLI 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; a `ChlorosProject` names its own folder to the backend. Before, only the app saved the project. See [One project record, every mode](#one-project-record-every-mode).
> * **Files made from several cameras name every one.** A multiband stack, 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, 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, continuous-recording and multi-camera-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. Processing 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).
> * **`import_images(recursive=True)` counts only your images and recordings.** A folder holding a project's `camera_cal/` no longer has those calibration files counted as images and recordings, and a project that already took them in drops them.
> * **`configure(radiometric_output=...)` applies.** It now sets the project's `Export radiance` / `Export reflectance` products; before, every project's own product settings won over it, so `radiance`, `sensor-response` and `all` all exported radiance and reflectance.
> * **`test_array_sync()` 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 (`ptp_lock`) — every camera locked for 120 s, about 2 minutes from power-on (`ptp_settle_s=` 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).
> * **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 (`connect_daq_sensor(cap_id=...)` or `DAQSensorSession.set_cap()`, `chloros-cli daq pool-connect --cap-id` / `daq pool-set-cap`, or the GUI's cap dropdown), 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").
> * **`DAQSensorSession.record_start()` on a busy disk no longer stalls the sensor**: readings are queued and written on a thread of their own, and one that could not be written is counted in `status()`'s `record_errors` (with `record_last_error`).
> * **Direct `LatticeCamera`:** a frame without chunk exposure/gain now reports the camera's **real** exposure and gain (the fallback read a cached value that could stay frozen for a whole auto-exposure run), and `apply_settings(trigger_source='LineN')` / `set_trigger_source('LineN')` apply the same 5 µs input deglitch Chloros's cable slaves get (unfiltered, a slave fired frames with no trigger sent).
> * **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.
> * **`discover_daq_sensors()` names a DAQ-E-S `DAQ-E-S`.** Its `model` was `DAQ-E` for every Ethernet sensor; one that does not answer the identity check within about 2 s is still listed, as `DAQ-E`.
> * **New: `chloros-mcp`, an MCP server for AI assistants.** Claude Desktop, Claude Code, Cursor and other MCP clients can process imagery (create a project, import captures, choose settings, process, report what the run exported) and run LATTICE cameras, arrays and DAQ light sensors: connect, preview, set exposure and colour, capture, record. Its tools cover what this SDK does. It installs with the SDK, and the Linux .deb puts it in `/usr/bin`. See [MCP Server (AI Assistants)](#mcp-server-ai-assistants).
> * **New: camera utilities**, the `chloros-cli lattice` commands as SDK calls: colour profile, saturation / contrast, highlights, white balance (one-shot, auto, fixed ratios), presets, filter models, firmware status and update, power (probe, sleep, wake), target calibration, network adapters (check, estimate, fix), vignette correction on files, a DLS reading, and the host probe. See [Camera Utilities](#camera-utilities).
> * **New: the rest of the CLI as SDK calls**, so the CLI, the SDK and `chloros-mcp` offer the same features (the CLI keeps only sign-in, a DAQ-E's provisioning and the direct DAQ servers, for security): cameras opened for one command (`start_camera_continuous()`, `start_multi_camera_stream()`, `capture_cameras_transient()`, `test_array_sync()`, `detect_array_master()`, `analyze_array_models()`), alignment-profile files (`calibrate_alignment_profile()`, `capture_aligned_multiband()`, `start_aligned_stream()`, `alignment_profile_info()`, `reorder_alignment_profile()`), indices (`index_catalog()`, `compute_index()`, `capture_live_index()`), the PTP grandmaster (`time_sync_status()` and friends), the project folder (`project_folder()`, `set_project_folder()`, `reset_project_folder()`) and recipes (`run_project_recipe()`, the CLI's own runner). For light sensors: `connect_daq_sensor(cap_id=...)`, `DAQSensorSession.set_cap()`, `daq_bindings()` / `set_daq_bindings()`, `daq_band_presets()` and `light_sensor_reflectance()` (two sensors' Ambient + Object reflectance and indices); for a camera: `CameraSession.status()` and `capture_repeated()`; for an array: `ArraySession.capability()` and `set_member_settings()` (a member's exposure, gain, ...). See [Transient Arrays, Alignment Profiles & Indices](#transient-arrays-alignment-profiles--indices), [Project Folder & Recipes](#project-folder--recipes) and [DAQ Sensor Sessions](#daq-sensor-sessions).
> * **Improved LATTICE index products** (NDVI and other indices) from `process()`, in every processing mode.
> * **LATTICE OCN cameras: improved radiance, reflectance and index products in sunlight.** A fleet correction is applied after the band unmix — live, in captures and in `process()`; RGN cameras are unchanged. See [Radiometric Output](#radiometric-output-lattice-multispectral-pipeline).
> * **Every capture saves the DAQ reading it used, as the GUI does.** `CameraSession.capture()` and `ArraySession.capture()` / `continuous()` 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=True`. `daq=False` turns it off and `daq_tolerance_ms=` sets the match tolerance; both results say what was saved in `.daq_files` and `.daq_matches`. 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--daq_files-and-daq_matches).
> * **`ArraySession` has live frames and a server-side continuous capture.** `grab()` and `frame_stream()` return numpy frames from one trigger (the same read as the project API's `ArrayHandle.grab()` / `frame_stream()`), and `continuous()` saves every synced group in the backend and returns a [`ContinuousHandle`](#continuoushandle). See [Live Frames in Your Own Pipeline](#live-frames-in-your-own-pipeline).
> * **An array `grab()` is pinned to one trigger** (`ArrayHandle.grab()`, and the new `ArraySession.grab()`). In 1.2.0, 12 of 20 four-camera `ArrayHandle.grab()` reads straddled two triggers. Every frame now carries `group_id`, and an array `frame_stream()` yields each trigger once. See [One trigger per read](#one-trigger-per-read--group_id).
> * **Per-band and aligned frames:** `grab()` / `frame_stream()` take `band=`, `align=`, `bit_depth=` and `refl_max=` on camera and array handles. See [Exporting a single band](#exporting-a-single-band--band).
> * **New `ArraySession` methods and arguments:** `set_target_fps()`, `force_disconnect()`, `capture(after_seq=..., orient=...)` (with `CaptureResult.group_seq` and `.failed`), `continuous()`, `connect_array(packed=...)`; `capture_repeated()` chains consecutive groups and stops on a full drive.
> * **`ArraySession.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 as `expr=`. `RecorderHandle.stop()` raises `ChlorosConnectError` for a recording that failed, one that wrote no frame included, and keeps the stop result on `.result` (leaving a `with` block does not raise: check `rec.result`). See [`RecorderHandle`](#recorderhandle).
> * **New `DAQSensorSession` methods:** `enable_ptp()`, `force_disconnect()`, and for a DAQ-E's own settings `device_info()`, `set_network()`, `set_auto_stream()`, `reboot()` and `update_firmware()`. `record_stop()` returns `warning` and `gaps`. A restart that closed a recording names it, in its reply or, when the restart fails, on the `ChlorosConnectError` (`recording_closed`; see [DAQ-E Device Settings](#daq-e-device-settings)). See [`DAQSensorSession` Methods](#daqsensorsession-methods).
> * **A pooled DAQ-E that stops delivering is reconnected by the backend**, with the settings it had, and a recording on it carries on in the same `.daq` with the gap marked in the file; `record_stop()` returns the gaps as `gaps`. In 1.2.0 the sensor stayed silent until it was disconnected and connected again, which ended the recording. See the CLI reference's [A DAQ-E That Stops Delivering](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#a-daq-e-that-stops-delivering).
> * **`open_project()` works from an installed SDK.** The wheel (the installer's and PyPI's) now carries the project loaders it needs; before, `open_project()` raised `ImportError` naming `project_cameras` / `project_sensors` in any pip-installed SDK. `connect_all()` connects the saved cameras, arrays and light sensors through a running backend (light sensors through its DAQ pool), and a saved device it has no way to look for is listed under `errors` with the reason instead of being skipped without a word. A saved array that is already up in the backend (the GUI's, or `chloros-cli project connect`'s) is attached and left running, where before it was reported as an error (`Camera <sn> is already in array <id>`). See [`ChlorosProject` Methods](#chlorosproject-methods).
> * **`ChlorosLocal()`, `process_folder()` and `process_lattice_capture()` find Chloros on Windows.** They look where the installer puts the backend (`<install folder>\backend\`, `C:\Program Files\Chloros\backend\` by default, a custom folder from the installer's own record), and connect to a backend that is already running without looking for one at all. In 1.2.0 they raised "Chloros backend not found" on an installed machine unless you passed `backend_exe=`.
> * **A backend that dies at startup is reported at once.** When `ChlorosLocal()` or a smart-connect call starts a backend that exits before it answers, the call raises within seconds, `ChlorosBackendError` from `ChlorosLocal` and `ChlorosConnectError` from the smart-connect calls, with the exit code, the command it ran and the last lines the backend printed. 1.2.0 waited out the 60 s startup timeout and did not say why. See [Backend Auto-Start](#backend-auto-start).
> * **The backend keeps running between scripts.** Leaving a `with ChlorosLocal(...)` block, `process_folder()` / `process_lattice_capture()` returning and `chloros-mcp` exiting no longer stop a backend the SDK started; the next script reuses it. It stops on `logout()` (unless the Chloros app is open or a run is in progress), on `shutdown_backend()`, or by itself after 30 minutes with nothing using it (`CHLOROS_BACKEND_IDLE_MIN` in the backend's environment changes that; `0`: never).
> * **A backend the SDK started is asked to shut down, not killed.** `shutdown_backend()` lets the backend release its cameras and light sensors and finish any recording; it is terminated only if it is still running 10 s later. 1.2.0 terminated it at once (on Windows, a hard kill), which could leave a DAQ light sensor connected to that backend unresponsive. A backend the SDK found running is still left alone.
> * **On Linux, auto-start never runs a `backend_server.py` from the current folder.** With no installed backend, a script started in a folder that held one ran it; now only the installed backend is started (or, for `ChlorosLocal`, the one `backend_exe=` names).
> * **`configure(indices=...)`** adds each preset to the project for its camera's bands, a new project included, and warns (`UserWarning`) for a name it cannot add. **`import_images()`** reports `.daq` recordings as `scan_count` and no longer warns about a LATTICE capture folder.
> * **`read_image_audit_tags()` works from a pip install.** It reads the image's metadata itself; in 1.2.0 it returned `{}` without the desktop install's internals on the Python path.
> * **`capture()` right after `connect_array()`** waits up to 20 s for the array's first frame group instead of failing with HTTP 503 "Array still warming up".
> * **`status()` reports a stall.** The new `stalled` field is True while the grab loop runs but publishes nothing, and `actual_fps` is then 0. In 1.2.0 `actual_fps` kept its last value during a stall, so a stalled array showed `actual_fps > 0` while captures failed with 503 "No fresh synced frame group".
> * **Fewer incomplete frame sets and capture 503s:** each slave camera's trigger input is now deglitched.
> * **Packed 12-bit transport** (`connect_array(packed="auto")`) raises full-sensor array frame rates by about a third. See [Packed 12-bit Transport](#packed-12-bit-transport-packed).
> * **Array exposure under an ROI:** a small ROI no longer caps a member's exposure at the sensor's free-run period (4.9 ms at 768 × 304). See [Exposure on Array Members](#exposure-on-array-members).
> * **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 slows the trigger to fit it instead of being refused. See [Exposure on Array Members](#exposure-on-array-members).
> * **`read_nodes()`** adds `frame_values` and `notes` while auto exposure runs (see [`read_nodes()` under auto exposure](#read_nodes-under-auto-exposure--frame_values-and-notes)). When the camera refuses an exposure or gain, **`set_settings()`** says the range it accepts and puts back the auto mode it had switched Off for that value; `set_settings(target_brightness_auto=True)` is new.
> * **`orient=`** on `ArraySession.capture()` / `capture_fastest()` / `continuous()` / `burst()` and `ArrayHandle.capture()` / `capture_smart()` turns the products by the camera orientation. See [`ArraySession` Methods](#arraysession-methods).
> * **`DLS()` needs the sensor's own `mac_address`.** There is no default MAC any more (it was one unit's address); `DLS()` without one raises `DLSError`. See [DAQ-M band magnitudes](#daq-m-band-magnitudes--dlsband_magnitudes).
> * **The Windows installer** offers "Enable Windows long paths" and "Exclude the Chloros backend from Microsoft Defender scanning", both checked by default. See [Step 1](#step-1--install-the-chloros-platform-package).
> * **The Linux .deb** installs the Python SDK for the system `python3` (before, it only placed the wheel on disk), raises the kernel's socket receive buffers that camera streams need, and adds a backend service that runs as your user. The Jetson package is `chloros_1.3.0_arm64_jp6.deb`, for JetPack 6, with JetPack's CUDA PyTorch. See [Step 1](#step-1--install-the-chloros-platform-package) and [Step 2](#linux-deb).

***

## Architecture in 60 Seconds

The SDK is a thin Python layer over the Chloros backend (the same Flask server the desktop GUI and CLI use). For automation you import `chloros_sdk` and call high-level methods; under the hood, every call becomes an HTTP request to the local backend on port 5000 — `http://127.0.0.1:5000/api/...` (deliberately not `localhost`, which resolves to `::1` first on Windows and costs \~2 s per request against an IPv4-only backend). The backend owns the hardware pool — cameras, DAQ sensors, alignment profiles, frame buffers — so SDK scripts can co-exist with the GUI without fighting for serial ports or NIC bandwidth.

There are three surfaces you'll use:

1. **`ChlorosLocal` + free functions** (`process_folder`, `process_lattice_capture`) — Image-processing pipeline. Run an entire folder through calibration / debayer / index export from one Python call.
2. **Smart-connect handles** (`connect_camera`, `connect_array`, `connect_daq_sensor`) — Open a persistent backend session for live hardware. Same "smart-prep" flow as the GUI: network probe, tier auto-pick, PTP, AE seeding, GPIO trigger config.
3. **`ChlorosProject` / `open_project`** — Load a saved project (folder with `cameras.json` + `sensors.json` + `project.json`), connect its cameras, arrays and light sensors at once, and drive captures with named handles.

Surfaces 1 and 2 **auto-start a local backend** if one isn't already listening (the same bundled binary the GUI/CLI spawn) — so a bare script works from a fresh shell without you starting a backend first: `ChlorosLocal` (and `process_folder()` / `process_lattice_capture()`), `connect_camera()`, `connect_array()`, `connect_daq_sensor()`, `discover_lattice_cameras()` and `discover_daq_sensors()`. `list_cameras()`, `list_arrays()`, `list_daq_sensors()`, `attach_array()` and `analyze_array_network()` never start one: they need a running backend. Pass `auto_start_backend=False` to opt out (e.g. when pointing at a remote backend, which is never spawned). See [Backend Auto-Start](#backend-auto-start). Surface 3 behaves differently: `open_project()` takes no `auto_start_backend` parameter, and `connect_all()` never spawns a backend — it probes `http://127.0.0.1:5000` once and, if nothing answers, falls back to direct (backend-free) `lattice_sdk` device control. That needs the Arena SDK runtime and OpenCV (`cv2`) importable in your Python, which the SDK wheel does not install; without them, each saved camera and array is reported as an error, with the reason. A project's light sensors have no backend-free path: with no backend running, each saved sensor is reported as an error, with the reason (see [`SensorHandle`](#sensorhandle)). Only `proj.process()` and `stream(..., overlays=True)` lazily construct a `ChlorosLocal()` (which does auto-start).

All three are auth-gated: run `chloros-cli login` once on the machine, or sign in via the desktop GUI. What a call without a valid session raises depends on the surface (see [Exceptions](#exceptions)): `ChlorosAuthenticationError` from `ChlorosLocal` (and `process_folder()` / `process_lattice_capture()`), `ChlorosConnectError` from the smart-connect calls and their sessions, `status: "error"` with an `error_code` from `analyze_array_network()`, and an entry under `errors` in the `connect_all()` report.

Requirements:

* Python 3.7+ (as declared by the package; developed/tested on 3.10)
* Chloros Desktop installed locally (the backend binary ships inside the installer)
* Active Chloros+ login on **any paid Chloros+ tier (Copper or higher)**; the free **Iron** tier has no SDK/CLI access. This is enforced **server-side**: every SDK/CLI-flagged request must carry both a live session and a paid plan. A plan below Copper gets `403` with `error_code: PLAN_UPGRADE_REQUIRED` (`ChlorosLicenseError` from `ChlorosLocal`, `ChlorosConnectError` from the smart-connect calls). A logged-out caller gets `401` / `AUTH_REQUIRED` instead (`ChlorosAuthenticationError` from `ChlorosLocal`, `ChlorosConnectError` from the smart-connect calls) — the two are distinct because re-running `chloros-cli login` fixes the `401` and cannot fix the `403`, which needs a plan upgrade.
* Offline use is supported within the plan's grace period: the tier is read from the server-validation cache (5 min) or the signed, machine-bound license cache (30 days for monthly plans, to subscription expiry for yearly). When that grace lapses the plan resolves to free and SDK/CLI access stops until the machine can reach the server once. `chloros-cli status` (`GET /api/license-status`) stays reachable on the free tier so the reason is visible.
* Windows 10/11 64-bit, **Ubuntu 22.04 LTS or newer**, or Jetson (JetPack 6). Ubuntu 20.04 is **not** supported: the `.deb`'s dependencies are derived from what the backend links against, including `libc6 (>= 2.35)`, and focal ships glibc 2.31.

***

## Installation

The Python SDK is a thin Python layer over the Chloros backend. Unless you drive a backend on another machine (see [Remote-Backend Mode](#remote-backend-mode-pip-only-host-via-tunnel)), you need the **Chloros desktop package installed locally** (Windows installer or Linux `.deb`), and that includes DAQ light sensors. The package provides the backend binary, the Arena SDK runtime for LATTICE cameras, and the calibration bundles.

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

### Step 1 — Install the Chloros platform package

#### Windows (.exe)

1. Download `Chloros Installer 1.3.0.exe` from the download page.
2. Run the installer and follow the wizard. Default install path is `C:\Program Files\Chloros\`.
3. Launch Chloros at least once and sign in with your Chloros+ account.

The installer lets the backend (`chloros-backend.exe`, nothing else) through Windows Firewall on every network profile: UDP in, for camera streams, PTP, mDNS and the DAQ-E stream, and TCP in from the local subnet only, for the connection a DAQ-E makes back to the computer during a firmware update ([`update_firmware()`](#daq-e-device-settings)). The uninstaller removes both rules. The backend's HTTP API stays on `127.0.0.1` either way.

The wizard's **System settings** group has two options, both checked by default:

| Option                                                           | What it does                                                                                                                                                                                                                                                                         | Silent-install opt-out             |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| **Enable Windows long paths**                                    | Lets project folders sit deeper than Windows' 260-character path limit. With long paths off (the Windows default), a project folder too deep for its products is refused before anything is processed — see [Troubleshooting](#troubleshooting-pointers).                            | `/MERGETASKS="!longpaths"`         |
| **Exclude the Chloros backend from Microsoft Defender scanning** | Stops Defender's real-time scan of every file a camera capture writes. At high capture rates the scan costs about 30 % of the rate: measured at ROI 512 on a 9-camera array, continuous raw capture ran 52.7 captures/s with scanning and 77.7 captures/s with the backend excluded. | `/MERGETASKS="!defenderexclusion"` |

A continuous capture reports Defender's load as `defender_cores` (see [`ContinuousHandle`](#continuoushandle)).

#### Linux amd64 (.deb)

```bash
sudo apt install ./chloros_1.3.0_amd64.deb
chloros-cli --version
chloros-cli login user@example.com 'YourPassword'
```

Install with `apt install ./…`, not `dpkg -i`: apt also installs the Python SDK's requirements, which the package recommends rather than requires (see [Step 2](#linux-deb)).

#### Linux arm64 — Jetson (JetPack 6)

```bash
sudo apt install ./chloros_1.3.0_arm64_jp6.deb
chloros-cli --version
chloros-cli login user@example.com 'YourPassword'
```

For Jetson Orin / Orin NX / Orin Nano on JetPack 6 (L4T R36). Its PyTorch is JetPack 6's CUDA build, so GPU processing runs on the Orin's GPU; it uses the CUDA and cuDNN libraries JetPack 6 installs (`sudo apt install nvidia-jetpack` on an image that lacks them).

#### Linux: receive buffers and the backend service

Both .debs raise the kernel's socket receive buffers that LATTICE camera streams need to 32 MB (`/etc/sysctl.d/60-chloros-gige.conf`). At the kernel default, camera packets are dropped in the kernel and an array loses frames and frame rate; `chloros-cli lattice network` reports the buffers when they are low. See the CLI reference's [Linux hosts — socket receive buffers](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#linux-hosts--socket-receive-buffers).

On a headless machine, run the backend as a service **as your user**, so that a script finds one running (`connect_all()` never starts a backend):

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

The backend then runs as you: the captures it writes are yours, and it uses your `chloros-cli login`. The root `chloros-backend.service` is still installed for machines that enabled it, but every file a root backend writes belongs to root. See the CLI reference's [Running the backend as a service](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#running-the-backend-as-a-service-headless).

A backend the service runs is shared, never stopped by a client: SDK scripts and `chloros-cli` use it as they find it (`ChlorosLocal.shutdown_backend()` stops only a backend that `ChlorosLocal` started itself), and `GET /api/status` names the unit as `service`. Restart it with `sudo systemctl restart chloros-backend@$USER.service`. Upgrading the package stops the backend services while it installs, so a running script loses its cameras and sensors, and then starts every enabled one again; removing the package stops them and disables the enabled ones. Only one backend runs at a time, so enable one unit: a second one refuses to start and stays `failed` (exit status 98, not restarted), and its `systemctl status` says why. To switch units, disable the one you do not use.

### Step 2 — Install the Python SDK

**The Chloros installer ships a matching SDK wheel.** Every Windows installer and Linux .deb places a `chloros_sdk-X.Y.Z-py3-none-any.whl` on disk that exactly matches the GUI / CLI / backend version. You don't have to chase PyPI to stay in sync.

#### Windows

The installer auto-runs `pip install` against the bundled wheel using your system Python (`py.exe` launcher preferred, falls back to `python -m pip`). No action required — `import chloros_sdk` works in your Python environment after a successful install. If no Python is on the box, the installer silently skips this step and the GUI + CLI keep working.

#### Linux (.deb)

Both .debs (x86\_64 and Jetson) install the SDK for the system `python3`, so `import chloros_sdk` works after the install, with no pip and no network. The packages (`chloros_sdk`, `lattice_sdk`, `lattice_cam`, `arena_api` and the project loaders) go into `/usr/lib/python3/dist-packages`, and the SDK's `chloros-mcp` command (the [MCP server](#mcp-server-ai-assistants)) into `/usr/bin`, all owned by the package: an upgrade replaces them and removing the package removes them.

The SDK's own requirements, `python3-numpy` and `python3-requests`, are **recommended, not required** (the GUI, CLI and backend are self-contained): `sudo apt install ./chloros_<version>_amd64.deb` (`…_arm64_jp6.deb` on a Jetson) installs them, `dpkg -i` does not. The install output reports the SDK version `python3` imports, any requirement that is missing, and a `chloros_sdk` elsewhere on `python3`'s path that shadows the package's copy (such as one installed earlier with `pip install --user`).

In a virtualenv, which does not see the system's packages, install the bundled wheel into it:

```bash
pip install /usr/lib/chloros/sdk/chloros_sdk-*.whl
```

For air-gapped Jetson deploys this is fully offline — the SDK and the wheel are already on disk.

#### Public PyPI

For pip-only hosts (no Chloros desktop package installed; the SDK then drives a backend on another machine, see [Remote-Backend Mode](#remote-backend-mode-pip-only-host-via-tunnel)):

```bash
pip install chloros-sdk
```

PyPI carries the latest stable release. Keep the SDK on the same version as the Chloros backend it drives (see [Versioning & Compatibility](#versioning--compatibility)). The DAQ-M helper `DLS` also needs `bleak`: `pip install "chloros-sdk[camera]"` (or `pip install bleak`).

#### Verify

```python
import chloros_sdk
print(chloros_sdk.__version__)
print("CAMERA_AVAILABLE =", chloros_sdk.CAMERA_AVAILABLE)
print("PROJECT_AVAILABLE =", chloros_sdk.PROJECT_AVAILABLE)
```

> **Chloros+ subscription required.** All SDK calls require an active Chloros+ login. Run `chloros-cli login user@example.com 'YourPassword'` once per machine; credentials are cached in `~/.chloros/`.

### Do I Need the Desktop Package?

The pip package alone is **not** enough for most workflows. Here's what each SDK surface needs:

| SDK Surface                                                                                              | Needs Desktop Package?                                        | Why                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChlorosLocal`, `process_folder`, `process_lattice_capture`                                              | **Yes** (to start one) **/ No** (a backend already reachable) | Use a running backend (the desktop app's, or one another script started); otherwise auto-start the installed one: `/usr/lib/chloros/chloros-backend` (Linux) or `<install folder>\backend\chloros-backend.exe` (Windows; `C:\Program Files\Chloros\backend\` by default, a custom install folder is read from the installer's record). Pass `backend_exe=` to name it yourself. |
| `chloros-mcp` ([MCP server](#mcp-server-ai-assistants))                                                  | **Yes** (to start one) **/ No** (a backend already reachable) | Built on `ChlorosLocal`, so the same as the row above.                                                                                                                                                                                                                                                                                                                          |
| `read_image_audit_tags`                                                                                  | **No**                                                        | Reads the processed image's own metadata (Python standard library only).                                                                                                                                                                                                                                                                                                        |
| `connect_camera`, `connect_array`, `connect_daq_sensor`, `analyze_array_network`, `list_*`, `discover_*` | **Yes** (local) **/ No** (remote)                             | Pure HTTP clients over the backend. Local backend → desktop package required. Remote backend → `backend_url=` **through a tunnel** (see Remote-Backend Mode — shipped backends bind loopback only).                                                                                                                                                                             |
| `ChlorosProject` / `open_project`                                                                        | **Yes**                                                       | Drives saved projects through the backend.                                                                                                                                                                                                                                                                                                                                      |
| Direct LATTICE classes (`LatticeCamera`, `CameraPool`, `Calibration`, `DLS`, …)                          | **Yes**                                                       | Need the Arena SDK runtime, which ships inside the desktop package, and OpenCV (`cv2`) in your Python, which neither the desktop package nor the SDK installs (`pip install opencv-python`). `CAMERA_AVAILABLE` is `False` at import otherwise. `DLS` also needs `bleak`.                                                                                                       |

### Remote-Backend Mode (pip-only host, via tunnel)

> **The installed backend is not reachable over the LAN.** It listens on loopback only (`127.0.0.1` / `::1`), so `backend_url="http://<lan-ip>:5000"` **cannot reach an installed Chloros**. To drive a backend on another machine, forward its loopback port yourself and point the SDK at the tunnel:

```bash
# on the pip-only host: forward local 5000 to the Chloros machine's loopback
ssh -N -L 5000:127.0.0.1:5000 user@chloros-host
```

```python
import chloros_sdk

BACKEND = "http://127.0.0.1:5000"     # the tunnel endpoint
serials = ["213800234", "214000533"]   # master first

# auto_start_backend=False: the tunnel URL looks local, so without it a tunnel
# that is down would start this machine's own backend, if one is installed.
arr = chloros_sdk.connect_array(serials, backend_url=BACKEND,
                                auto_start_backend=False)
daq = chloros_sdk.connect_daq_sensor(eth_host="daq-e-1.local",
                                     backend_url=BACKEND,
                                     auto_start_backend=False)

# The backend opens every path on ITS machine: pass absolute paths valid there.
# (A relative path would be made absolute against this machine's working folder.)
arr.capture("/home/chloros/captures/run1", processing="raw")
```

Headless / CI / robotics hosts can keep one machine with the full desktop install as the "Chloros server" and `pip install chloros-sdk` everywhere else — but the transport between them is the user-arranged tunnel above, not a direct LAN URL.

> **`ChlorosLocal` on a pip-only host.** `ChlorosLocal(backend_url=BACKEND)` connects to a backend it can reach without a desktop install: it looks for a local backend binary only when it must START one (nothing answering and `auto_start_backend=True`). Through 1.2.0 it looked for the binary first and raised `ChlorosBackendError` ("Chloros backend not found…") on a pip-only host even with a backend reachable. The folders you pass (`process_folder`, `import_images`) are checked on this machine and read by the backend, so with a remote backend they must name the same folder on both, such as a shared drive.

### DAQ-Only Workflow (pip-only host)

`pip install chloros-sdk` alone cannot drive a DAQ sensor: a DAQ sensor is always driven through a Chloros backend with `connect_daq_sensor()`:

* **Sensor on this machine:** install the Chloros desktop package here. `connect_daq_sensor()` starts its backend if none is running.
* **Sensor on another machine:** that machine needs the desktop package; reach its backend through the tunnel in [Remote-Backend Mode](#remote-backend-mode-pip-only-host-via-tunnel). The backend opens the sensor on its own machine, so a DAQ-U is plugged into that machine, a DAQ-M is in Bluetooth range of it, and a DAQ-E is on a network it can reach.

```python
import chloros_sdk

# http://127.0.0.1:5000 is the local desktop install's backend, or the tunnel.
with chloros_sdk.connect_daq_sensor() as daq:   # smart-detect USB / BLE / ETH
    print(daq.model, daq.transport, daq.address)
    for frame in daq.latest(n=5):
        print(frame["spectrum"][:10])
```

Either way the backend enforces the Chloros+ plan: log in on the machine that runs the backend (`chloros-cli login`, or the desktop app) with any paid tier (Copper or higher). A logged-out backend and a plan below Copper both raise `ChlorosConnectError` carrying the backend's reason (`AUTH_REQUIRED` / `PLAN_UPGRADE_REQUIRED`).

***

## Quickstart

```python
import chloros_sdk

# === Image processing ===
results = chloros_sdk.process_folder(
    "C:/DroneImages/Flight001",
    indices=["NDVI", "GNDVI", "OSAVI"],
)

# === Live LATTICE single-cam ===
with chloros_sdk.connect_camera("213800234") as cam:
    cam.set_settings(exposure_time=10000, gain=0.0)
    cam.capture("output/")

# === Live LATTICE synchronized array (GUI smart-prep flow) ===
with chloros_sdk.connect_array(
        ["213800234", "214000533", "214701288", "214701292"]) as arr:
    arr.capture("output/", processing="reflectance")

# === Live DAQ spectral sensor ===
with chloros_sdk.connect_daq_sensor() as daq:    # smart-detect USB / BLE / ETH
    for frame in daq.latest(n=5):
        print(frame["spectrum"][:10])

# === Drive a saved project end-to-end ===
proj = chloros_sdk.open_project("/path/to/project")
proj.connect_all()
proj.arrays["main_rig"].capture("output/", processing="reflectance")
proj.disconnect_all()
```

***

## Top-Level API Index

```python
import chloros_sdk

# === Image processing (full pipeline) ===
chloros_sdk.ChlorosLocal                          # class
chloros_sdk.process_folder(...)                   # one-shot helper
chloros_sdk.process_lattice_capture(...)          # LATTICE-friendly defaults
chloros_sdk.read_image_audit_tags(path)           # post-run audit

# === Live cameras (persistent backend pool) ===
chloros_sdk.connect_camera(serial, ...)           # → CameraSession
chloros_sdk.connect_array(serials, ...)           # → ArraySession (smart-prep)
chloros_sdk.attach_array(serials_or_id, ...)      # → ArraySession (attach without re-connecting)
chloros_sdk.list_cameras()
chloros_sdk.list_arrays()
chloros_sdk.discover_lattice_cameras()
chloros_sdk.analyze_array_network(...)            # network capability + recommendation
chloros_sdk.CaptureResult                         # list subclass returned by CameraSession.capture / ArraySession.capture
chloros_sdk.RecorderHandle                        # handle for an array record()/burst() job
chloros_sdk.ContinuousHandle                      # handle for an array continuous() capture
chloros_sdk.GrabResult                            # dict returned by grab() / yielded by frame_stream()
chloros_sdk.FrameFetchError                       # raised by grab()/frame_stream() on a refusal

# === Live DAQ sensors (persistent backend pool) ===
chloros_sdk.connect_daq_sensor(...)               # → DAQSensorSession
chloros_sdk.discover_daq_sensors()                # scan USB/BLE/ETH (finds a DAQ-M MAC)
chloros_sdk.list_daq_sensors()
chloros_sdk.daq_bindings() / set_daq_bindings(cameras=, arrays=)   # which DAQ feeds which camera
chloros_sdk.daq_band_presets(filter_code=None)    # band sets for Ambient + Object reflectance
chloros_sdk.light_sensor_reflectance(ambient_id, object_id, ...)   # two DAQs -> reflectance + indices
chloros_sdk.time_sync_status() / time_sync_peers() / time_sync_cameras()   # PTP grandmaster
chloros_sdk.restart_time_sync() / set_time_sync_priority(priority1=, priority2=)

# === Camera utilities (the CLI's lattice commands; by serial) ===
chloros_sdk.camera_color_profile(serial) / set_camera_color_profile(serial, ...)
chloros_sdk.camera_color_adjust(serial) / set_camera_color_adjust(serial, ...)
chloros_sdk.camera_highlights(serial) / set_camera_highlights(serial, value)
chloros_sdk.camera_white_balance_once(serial) / set_camera_white_balance(serial, ...)
chloros_sdk.camera_presets() / apply_camera_preset(serial, preset)
chloros_sdk.camera_filter_models() / camera_filter_model_info(name)
chloros_sdk.camera_firmware_status() / update_camera_firmware(serial)
chloros_sdk.camera_power_probe(serial) / sleep_camera(serial) / wake_camera(serial)
chloros_sdk.calibrate_camera_with_target(serial, ...)
chloros_sdk.network_adapters(...) / fix_network_settings()
chloros_sdk.apply_vignette_correction(input_dir, output_dir, ...)
chloros_sdk.read_dls(mac, ...) / probe_system(...) / system_info()

# === Transient cameras, alignment profiles, indices (cameras opened for one command) ===
chloros_sdk.start_camera_continuous(serial, ..., daq=None, daq_tolerance_ms=None)  # → CliJob; a DAQ bound to the camera records one .daq per frame (daq=False: none)
chloros_sdk.start_multi_camera_stream(serials, ...)   # → CliJob
chloros_sdk.capture_cameras_transient(serials, ...)
chloros_sdk.test_array_sync(serials, count, ptp_settle_s=None) / detect_array_master(line) / analyze_array_models(models)
chloros_sdk.calibrate_alignment_profile(serials, save_path, ...)
chloros_sdk.capture_aligned_multiband(profile_path, ...) / start_aligned_stream(profile_path, ...)  # → dict / CliJob
chloros_sdk.alignment_profile_info(path) / reorder_alignment_profile(path, ...)
chloros_sdk.index_catalog() / compute_index(input_path, ...) / capture_live_index(profile_path, ...)
chloros_sdk.CliJob                                # stats() / stop() / wait()

# === Project lifecycle ===
chloros_sdk.open_project(path, relink=None)       # → ChlorosProject
chloros_sdk.project_folder() / set_project_folder(path) / reset_project_folder()
chloros_sdk.run_project_recipe(recipe, project_path)  # `chloros-cli project run`
chloros_sdk.ChlorosProject                        # class
chloros_sdk.AlignmentSpec                         # dataclass
chloros_sdk.ArrayHandle, CameraHandle, SensorHandle

# === Direct-hardware (no-backend) classes (from lattice_sdk) ===
chloros_sdk.LatticeCamera, CameraSettings, PRESETS, CameraPool
chloros_sdk.Calibration, CalibrationCoefficients, FilterModel, list_filters
chloros_sdk.DLS, NetworkDiagnostics               # DLS: DAQ-M over Bluetooth; needs bleak

# === Exceptions ===
chloros_sdk.ChlorosError                          # base
chloros_sdk.ChlorosBackendError
chloros_sdk.ChlorosLicenseError
chloros_sdk.ChlorosConnectionError
chloros_sdk.ChlorosProcessingError
chloros_sdk.ChlorosProjectFilesMissingError      # a ChlorosProcessingError
chloros_sdk.ChlorosAuthenticationError
chloros_sdk.ChlorosConfigurationError
chloros_sdk.ChlorosConnectError                   # raised by smart-connect surface
chloros_sdk.LatticeError, CameraNotFoundError, ...  # from lattice_sdk

# === Availability flags ===
chloros_sdk.CAMERA_AVAILABLE     # True iff lattice_sdk imported cleanly
chloros_sdk.PROJECT_AVAILABLE    # True when chloros_sdk.project imported; open_project()
                                 # still raises ImportError without the project loaders
```

***

## Image Processing — `ChlorosLocal`

The headline pipeline class. Starts the backend when it is constructed (if none is answering and `auto_start_backend=True`), creates / configures projects, monitors progress, returns post-run summaries.

### Constructor

```python
ChlorosLocal(
    api_url="http://127.0.0.1:5000",   # backend URL (also: backend_url=)
    auto_start_backend=True,            # spawn backend if not running
    backend_exe=None,                   # override backend binary path
    timeout=30,                         # request timeout seconds
    backend_startup_timeout=60,         # backend boot timeout
    processing_timeout=14400,           # hard cap on process() (4 h)
    processing_stuck_timeout=1800,      # no-progress threshold (30 min)
)
```

### Methods

| Method                                                                                                                                                                                                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_project(project_name, camera=None)`                                                                                                                                                                                                                                                  | Create a new project (optionally with a camera template like `"Survey3N_RGN"`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `open_project(project_path, relink=None)`                                                                                                                                                                                                                                                    | Open a saved project (its folder, or its name in the projects folder) and make it the open project. A moved project's paths are re-pointed at the folder it is in now; `relink` names the folder its other missing files are in now. Returns the backend's answer with `source_files`; raises `ChlorosProjectFilesMissingError` when none can be found. See **A moved project** below.                                                                                                                                                                                                                              |
| `import_images(folder_path, recursive=False)`                                                                                                                                                                                                                                                | Import RAW/TIF/JPG/DNG images **and `.daq` light-sensor recordings**. Returns `count` (images) and `scan_count` (recordings). Warns only if the folder holds neither.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `export_light_sensor(daq=True, csv=True)`                                                                                                                                                                                                                                                    | Write calibrated `.daq` + `.csv` for every light-sensor recording on the project, into `<project>/Light Sensor/`. See [Light-Sensor Recordings](#light-sensor-recordings--calibrated-daq--csv).                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `configure(debayer=..., vignette_correction=..., reflectance_calibration=..., indices=[...], export_format=..., ppk=..., daq_log_path=..., input_level=..., radiometric_output=..., array_alignment=..., array_alignment_crop=..., array_alignment_interpolation=..., custom_settings=None)` | Set processing knobs. `indices` are preset names (`NDVI`, `GNDVI`, `OSAVI`, …), each added to the project for its camera's bands; a name that is not a preset, or that the bands cannot make (`NDRE` needs RE and NIR, which no single camera provides), gets a `UserWarning` naming it and no index image. `daq_log_path` names a light-sensor recording (a `.daq` or `.csv` file, or a folder of them) that every frame is matched against, LATTICE as well as Survey3, instead of the recordings imported with the images; a path that is missing or holds no recording is said, and the imported ones are used. |
| `process(mode="parallel", wait=True, progress_callback=None, poll_interval=2.0)`                                                                                                                                                                                                             | Run the pipeline. Returns `{"status": "complete", "async": False}`, plus a `summary` key when the backend provides one — see [Post-Run Summary & Hints](#post-run-summary--hints) — `export_check_failure` when the run's exports could not be verified, and `image_failure` when it lost an image. `wait=False` returns `{"status": "started", "async": True}` at once.                                                                                                                                                                                                                                            |
| `get_config()` / `get_status()` / `status()`                                                                                                                                                                                                                                                 | Inspect backend state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `logout()`                                                                                                                                                                                                                                                                                   | Log out: clears the cached credentials and releases this machine's device slot (`device_deregistration` in the result). A processing run in progress is not stopped: it finishes in the mode it started in (`run_in_progress: true` and `run_mode` in the result), and the next run uses standard processing.                                                                                                                                                                                                                                                                                                       |
| `shutdown_backend()`                                                                                                                                                                                                                                                                         | Stop the backend if this instance started it; a backend it found running is left alone. Leaving a `with` block or the instance being garbage-collected does not stop it: the backend keeps running for the next script and stops itself after 30 minutes with nothing using it. The backend is asked to shut down, so it releases its cameras and light sensors and finishes any recording first; it is terminated only if it is still running 10 s later.                                                                                                                                                          |
| `discover_cameras()`                                                                                                                                                                                                                                                                         | Discover LATTICE cameras **via this instance's backend** (`/api/camera/discover`). Returns a list of dicts (`serial`, `model`, `ip`, …) — same shape the GUI/CLI see. Empty list if none found or backend unreachable.                                                                                                                                                                                                                                                                                                                                                                                              |
| `camera_capture(output_dir, format="tiff", **settings)`                                                                                                                                                                                                                                      | Capture a single frame **through the backend** (auto-started by this handle) so it gets the same prep as the GUI/CLI (12-bit default, pool reuse, embedded cal metadata). Resolve the target with `serial=` or `device_index=`; pass `exposure`/`gain`/`pixel_format`/`preset` as `**settings`. Returns the legacy metadata dict (`filepath`, `width`, `height`, `pixel_format`, `exposure_time`, `gain`, `timestamp`).                                                                                                                                                                                             |
| `camera_stream(serial, *, fps=10.0, overlay=None, decode=True, connect_timeout=10.0, read_timeout=15.0)`                                                                                                                                                                                     | Yield overlay-composited preview frames from a pooled camera — thin MJPEG client over the backend's `/api/camera/<serial>/stream-annotated` route (zebra / grid / crosshair / histogram / peaking / spot drawn server-side). `decode=True` yields BGR arrays and needs OpenCV (`cv2`), which the SDK does not install; `False` yields raw JPEG bytes. Also reachable per-project as `ChlorosProject.stream(overlays=True)`.                                                                                                                                                                                         |

**A run in flight keeps its project.** While a processing run is in progress — this script's, the app's, `chloros-cli process`'s or `chloros-mcp`'s — the backend refuses to create, open, import into or change the processing settings of a project (HTTP 409 `PROCESSING_IN_PROGRESS`): `create_project()` and `import_images()` raise `ChlorosProcessingError`, and `configure()` raises `ChlorosConfigurationError`, and `process()` with another mode than the running one raises `ChlorosProcessingError` (a run keeps the mode it started in), each with the backend's message. A capture saved into the project then joins it when the run ends (its reply's `project_add` says so). Wait for the run to finish (`get_status()`), then go on.

**A moved project.** A project's `project.json` names each source file (every image and light-sensor recording) by its full path, so moving the project folder -- or the whole projects folder to another drive -- leaves them naming the old place. Every open 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 each path found there is re-pointed and saved (`project.json` is first backed up as `project.json.before-relink-<date>-<time>`). 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 -- are found only with `relink=<the folder they are in now>` (or any folder above it). `open_project()` returns `source_files`: `total`, `found`, `missing`, `missing_roots` (the folders the missing files were in), `missing_outside_project` and `relink` (what was re-pointed, from where to where). A project with some files missing opens with the rest; one with none found is not opened, and `open_project()` raises `ChlorosProjectFilesMissingError` (`.missing_roots`, `.audit`; HTTP 409 `PROJECT_SOURCES_MISSING`). The CLI's `project open --relink` and `chloros-mcp`'s `open_project` (`relink_folder`) do the same.

Use as a context manager for guaranteed cleanup:

```python
with chloros_sdk.ChlorosLocal() as cl:
    cl.create_project("FieldA_2026-05-26", camera="Survey3N_RGN")
    cl.import_images("C:/DroneImages/Flight001")
    cl.configure(
        vignette_correction=True,
        reflectance_calibration=True,
        indices=["NDVI", "GNDVI", "OSAVI"],
        export_format="TIFF (16-bit)",
    )
    results = cl.process(mode="parallel", wait=True)
print(results["summary"])
```

### Light-Sensor Recordings — calibrated `.daq` + `.csv`

A DAQ-U / DAQ-M / DAQ-E can be recorded **without** its calibration bundle. 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 on import.

Chloros writes the result back out as two products per recording, under `<project>/Light Sensor/`:

| Product                             | What it is                                                                                                                                                                                                  |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<name>_calibrated.daq`             | The reprocessable archive — same schema as a live recording, now declaring the bundle that produced it. Re-importing it does **not** calibrate it a second time.                                            |
| `<name>_calibrated.csv`             | Spectral irradiance in W/m²/nm on the sensor's own wavelength grid, one row per reading, plus photometric columns (total power, photopic/scotopic lux, PPFD and its blue/green/red split, peak wavelength). |
| `<name>_raw.daq` / `<name>_raw.csv` | **Bundle-less sensors only (DAQ-A).** Raw spectral sensor counts — *not* irradiance. See below.                                                                                                             |

`<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.

`process()` performs this export as one of its stages. It does **not** require imagery: a light sensor flown on its own is a first-class workflow, and such a project has zero images by construction.

**DAQ-A recordings export as raw counts.** The DAQ-A family predates the per-serial bundle system and has no bundle to fetch — it is calibrated in the field against a reflectance target instead, which is why it never needed one. Those recordings export under a `_raw` stem rather than `_calibrated`: 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 — exactly what target-based calibration uses them for — and not across sensors. The power-dependent photometric columns (total power, photopic/scotopic lux, PPFD) come back **NULL** rather than integrated from counts.

A DAQ-U / DAQ-M / DAQ-E whose bundle simply could not be fetched is still **skipped**, not written raw: there the bundle exists and "reconnect and reprocess" is real advice.

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.

```python
import chloros_sdk

with chloros_sdk.ChlorosLocal() as cl:
    cl.create_project("DAQ-U_2026-08-26")
    cl.import_images("C:/Flights/raw_daq")     # .daq only — no camera involved
    result = cl.export_light_sensor()          # or just cl.process()

for rec in result["exported"]:
    print(rec["csv"])
for rec in result["skipped"]:
    print("skipped", rec["source"], "--", rec["reason"])
```

A recording whose calibration bundle cannot be fetched (offline, or a sensor with no calibration on file) is reported under `skipped` **with the reason**. It is never written out as a "calibrated" file holding raw counts — connect to the internet and re-run, and the export completes.

### Progress Callbacks

```python
def show_progress(percent, message):
    print(f"[{percent:3d}%] {message}")

with chloros_sdk.ChlorosLocal() as cl:
    cl.create_project("FieldA")
    cl.import_images("C:/DroneImages/Flight001")
    cl.configure(indices=["NDVI"])
    cl.process(progress_callback=show_progress, poll_interval=1.0)
```

### Post-Run Summary & Hints

On completion, `process()` fetches `GET /api/processing-summary` and attaches the body as `result["summary"]`. The fetch is best-effort and never blocks a successful return — if the summary is unavailable, `process()` falls back to the plain `{"status": "complete", "async": False}` shape. Each entry in `summary["hints"]` — full sentences with the suggested remediation, e.g. why a run produced zero output — is also re-emitted as a Python `UserWarning`, so 0-output runs are self-diagnosing even if you never inspect the dict:

```python
result = cl.process()
for hint in result.get("summary", {}).get("hints", []):
    print("HINT:", hint)
# hints also arrive on the warnings channel:
#   python -W always::UserWarning your_script.py
```

`summary["totals"]` is the machine-readable half:

| Key                                                  | What it counts                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models`                                             | Camera groups in the run.                                                                                                                                                                                                                                                                    |
| `images_in_groups`                                   | Source images across those groups.                                                                                                                                                                                                                                                           |
| `targets_found`                                      | Reflectance targets detected.                                                                                                                                                                                                                                                                |
| `images_calibrated`                                  | Images the run wrote a reflectance product for.                                                                                                                                                                                                                                              |
| `images_failed`                                      | Images that failed and were not exported.                                                                                                                                                                                                                                                    |
| `exported_files`                                     | **Image product files the run wrote**: every product (debayered, preview, radiance, reflectance, index, target renders), in every format.                                                                                                                                                    |
| `reflectance_files`                                  | The reflectance products among them (`Reflectance_Calibrated_Images`), whether a target or the light sensor's (DAQ) irradiance calibrated them. A run with no target that still wrote reflectance says so in a hint; only a run that wrote none is told its reflectance outputs are missing. |
| `clamp_masks_written`                                | The [unmix clamp masks](#unmix-clamp-mask--which-pixels-a-band-was-clamped-on) written beside them — companions, not products, so not in `exported_files` (the CLI counts them apart the same way).                                                                                          |
| `captures_left_out`                                  | Raw frames in the project's `captures` folder that this run did not take. A run waits as it starts for what was captured before it, so this is 0 unless a capture was saved during the run or the wait ran out. `summary["captures_left_out_note"]` says what to do about them.              |
| `daq_recordings_exported` / `daq_recordings_skipped` | Light-sensor recordings, counted separately on purpose — they come from a different stage and exist for runs with no imagery at all, so folding them in would make a DAQ-only run look like it exported images.                                                                              |

Alongside them: `summary["output_dirs"]` (every directory written to), `summary["light_sensor_export"]`, `summary["stopped"]` (true when the user interrupted the run, so partial counts don't read as a completed run that under-produced), and `summary["groups"]` (the per-group breakdown).

`exported_files` is recorded by the pipeline **as it writes**, not scanned off the project's image objects afterwards. The parallel and GPU strategies build their own image objects (in worker subprocesses for the GPU paths), so the old scan reported `0 file(s) written` for every such run and then emitted the zero-exports hint — on runs where everything had worked. If you script against this number, a healthy parallel run now reports a non-zero count.

Light-sensor skips report the reason the reader actually established for each file — an unreadable schema, a missing bundle, a write error — **deduplicated**, so twenty files skipped for one cause read as one cause rather than twenty repetitions of it.

> **`process()` does not raise when a run produces no images.** This is one of the two places the SDK and the CLI deliberately differ: `chloros-cli process` treats "products were requested, none were written" as a failure and exits non-zero, whereas the SDK returns normally and reports the condition through `summary` / hints. If your pipeline should stop on an empty run, check it yourself — inspect `summary` (or count the files under the project folder) rather than relying on the absence of an exception. The usual causes are an input folder that wasn't recognised as a capture and products skipped as inapplicable for the cameras present (e.g. radiance from RGB-only cameras).
>
> `process()` does not raise when a run's exports could not be verified either: it warns and sets `result["export_check_failure"]`. The products are written. To stop on it, check that key. A run that lost an image is the same: it warns and sets `result["image_failure"]`, which `chloros-cli process` exits non-zero on.

### Convenience Functions

```python
# One-call process: project + import + configure + process
results = chloros_sdk.process_folder(
    folder_path="C:/DroneImages/Flight001",
    project_name="FieldA_2026-05-26",
    camera="Survey3N_RGN",
    indices=["NDVI", "GNDVI", "OSAVI"],
    vignette_correction=True,
    reflectance_calibration=True,
    export_format="TIFF (16-bit)",
    mode="parallel",
    debayer="High Quality (Faster)",      # or "Texture Aware (Slow, Highest Quality)"
    ppk=False,
    recursive=False,
    processing_timeout=14400,
)

# LATTICE-friendly defaults (no panel-target detection, standard debayer)
results = chloros_sdk.process_lattice_capture(
    folder_path="C:/Captures/2026-05-13_Field",
    indices=["NDVI"],
)

# process_folder() / process_lattice_capture() also take input_level=,
# array_alignment=, array_alignment_crop=, array_alignment_interpolation=,
# progress_callback=, poll_interval=, timeout=, processing_stuck_timeout=,
# backend_exe= and api_url= (NOT backend_url=). indices defaults to ["NDVI"].

# Audit which calibration sources were applied to a processed image
tags = chloros_sdk.read_image_audit_tags("output/Reflectance_Calibrated/x.tif")
print(tags["CalibrationSource"])   # 'per_serial' / 'legacy_lookup' / 'none'
print(tags["VignetteSource"])      # 'per_serial' / 'legacy_polynomial' / 'none'
```

Each runs inside its own `with ChlorosLocal(...)`; a backend it had to start keeps running when it returns, for the next call, and stops itself after 30 minutes with nothing using it. Neither takes `auto_start_backend`, `radiometric_output` or `daq_log_path`; use `ChlorosLocal` and `configure()` for those. `process_lattice_capture()` takes no `camera`, `debayer` or `ppk`: it skips panel detection and uses the standard debayer.

### Supported Values

```python
# export_format
"TIFF (16-bit)"           # default, recommended
"TIFF (32-bit, Percent)"  # reflectance percentage as float32
"TIFF (8-bit)"            # all-8-bit images are written as this; never raised
"PNG (8-bit)"
"JPG (8-bit)"

# debayer
"High Quality (Faster)"               # standard, default
"Texture Aware (Slow, Highest Quality)"  # neural debayer for Survey3 imagery, Chloros+ only.
                                         # Survey3 only: on a project holding LATTICE captures
                                         # (which always use the standard demosaic) configure()
                                         # or process() raises ChlorosConfigurationError; a
                                         # Texture Aware value the project saved earlier is set
                                         # to Standard with a UserWarning, as the app does. Needs a
                                         # CUDA GPU the backend's PyTorch can use (an NVIDIA
                                         # GPU, or a Jetson Orin's). Without one, process()
                                         # uses the standard debayer, and the backend prints
                                         # one "[DEBAYER] ... needs a CUDA GPU" line saying why.
"Standard (Fast, Medium Quality)"      # alias used internally for LATTICE

# input_level (LATTICE only; Survey3 .raw ignores)
"auto"        # default — infers from each file's XMP ProcessingLevel tag
"raw"         # force-treat as raw Bayer
"debayered"   # force-treat as Chloros's saved debayered (3-channel) product
"processed"   # force-treat as already-calibrated radiance

# array_alignment / array_alignment_crop (LATTICE arrays; None = keep saved setting)
True          # backend default — apply the module-to-module transform stamped
              # in each capture's Chloros:Alignment* XMP to every product
False         # export in native sensor geometry / skip the common-overlap crop

# array_alignment_interpolation (alignment warp resampling)
"bilinear"    # backend default
"nearest"     # preserves exact source DNs (no inter-pixel value mixing)
"cubic"
```

#### Radiometric Output (LATTICE multispectral pipeline)

The `process` pipeline's LATTICE multispectral (M3C/M3M) export level — `reflectance` (default), `radiance`, `sensor-response`, or `all` (every applicable mode per image) — sets the project's **"Export radiance"** and **"Export reflectance"** products: `radiance` exports radiance only, `reflectance` reflectance only, `sensor-response` neither (the debayered and preview products only), `all` both. The debayered and preview products are not the level's to change. `configure()` has a dedicated keyword for it:

```python
with chloros_sdk.ChlorosLocal() as cl:
    cl.create_project("Field_A")
    cl.import_images("C:/Captures/lattice_flight")
    cl.configure(
        radiometric_output="radiance",   # reflectance (default) / radiance / sensor-response / all
        export_format="TIFF (32-bit, Percent)",
    )
    cl.process()
```

The advanced escape hatch — writing the products through `custom_settings` — still works, but remember it replaces the whole settings block (see the warning below). Write the `"Export <product>"` keys: a project's own `"Export radiance"` / `"Export reflectance"` settings win over the older `"Radiometric output"` key, so that key alone changes nothing.

```python
cl.configure(custom_settings={
    "Project Settings": {
        "Processing": {"Export radiance": True, "Export reflectance": False},
        "Export": {"Calibrated image format": "TIFF (32-bit, Percent)"},
    }
})
```

`reflectance` (the default) divides camera radiance by the **timestamp-matched DAQ downwelling**, resolved automatically from a recorded `.daq` (DAQ-U/M/E) **or a DAQ-M native `.csv`** found alongside the imagery; any per-camera or DAQ calibration bundle missing locally is **auto-fetched from AWS** on first use. The CLI exposes this as per-type product toggles on `chloros-cli process`: `--radiance`/`--no-radiance`, `--reflectance`/`--no-reflectance`, `--debayered`, `--preview`.

**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 (single, synced and array captures; a raw burst names each member's reading in its manifest) — and is matched **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 (`chloros-cli daq pool-record`, or a recording started in the GUI), or any `.daq` without that sidecar (older captures included), still serves every camera.

**OCN cameras in sunlight.** Every OCN calibration pack is built under narrow-band light, one LED per band, while sunlight mixes the bands. Chloros 1.3.0 applies a fleet sun-basis correction after the band unmix, which improves OCN radiance, reflectance and index products in sunlight. It runs wherever the unmix does — `process()`, captures, `grab()` / `frame_stream()` and the live view — for OCN packs that support it; RGN cameras are unchanged. OCN images captured with an earlier version get it too when they are processed on a computer that holds the calibration they were taken with (Chloros keeps a camera's calibration once the camera has been connected); otherwise they are processed as before. OCN radiance, reflectance and index values therefore differ from 1.2.0's.

> `custom_settings` **replaces** the entire computed settings block (it bypasses `configure()`'s other keywords and validation by design). When you use it, include every `Project Settings` key you care about, as in the example above.

#### 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`) — for every radiance, reflectance and index product in which at least one pixel clamped. Single-band `uint8`, on the product's own pixel grid (orientation, ROI, binning and the array alignment warp 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).
* Capture results carry it as the frame's **`clamp_mask`** (the mask's path, or `None` when nothing clamped) — in `CameraSession.capture()` results, `ArraySession.capture()`'s `CaptureResult` frames and the HTTP capture responses. The offline build lists its masks as `clamp_masks`.
* A live index's multiband stack (`/api/camera/cli-array-index` with `save_multiband`) gets one mask per source camera, in the output folder's own `clamp_masks/` — see the CLI reference's `lattice index`. A video has no mask: the offline build's result reports each frame's clamp fraction instead.

Because no product folder holds a mask, at any depth, a product folder can be handed to photogrammetry software as it is — subfolders included — and it takes in images only. Hand it the product folder, not the folder above it. Chloros' own import skips the masks.

```python
import os, numpy as np, tifffile

mask = tifffile.imread(
    "clamp_masks/radiance/capture_<ts>_SN<serial>-<filter>_radiance_clampmask.tif")
# or, from the image: os.path.join(os.path.dirname(image_path), tag), with
# tag = the image's Chloros:UnmixClampMask
r_clamped = (mask & 1) != 0      # the band Chloros:BandRName names
g_clamped = (mask & 2) != 0
b_clamped = (mask & 4) != 0
```

***

## Smart-Connect for LATTICE Cameras

Persistent backend sessions for live hardware. Same endpoints the GUI uses, so behaviour is identical across SDK / CLI / GUI.

### Single Camera — `CameraSession`

```python
import chloros_sdk

# Open by serial; reuses existing pool entry if one exists
with chloros_sdk.connect_camera("213800234") as cam:
    # cam is a CameraSession; supports context manager + manual disconnect
    cam.set_settings(
        exposure_time=10000,    # microseconds
        gain=0.0,               # dB
        pixel_format="BayerRG12",
        target_brightness=80,
        ae_damping=8.0,
    )
    cam.capture("output/", ext=".tiff")
```

The exposure, gain and target set here are held as yours: Chloros's automatic exposure control (including the DAQ-metered exposure) leaves them alone. `cam.set_settings(exposure_auto="Continuous")` (or `gain_auto=`) hands exposure (gain) back, and `cam.set_settings(target_brightness_auto=True)` hands the target back to Chloros's automatic target.

#### `connect_camera()` Signature

```python
connect_camera(
    serial,
    *,
    preset=None,                       # "default" | "high_quality" | "high_speed" | "triggered"
    settings=None,                     # dict overlaid on the preset
    backend_url="http://127.0.0.1:5000",  # deliberately not 'localhost' (::1-first on Windows ≈ 2 s/request)
    timeout=60.0,
    auto_start_backend=True,           # spawn a local backend if none is running
) -> CameraSession
```

* **It returns with the stream started.** The backend waits, bounded (about 15 s for the stream to start, then 10 s for its first complete buffer — not for the first preview frame, which follows about 1.5 s later), so a `status()` right after it says `streaming`. The session's `connect_stream` is the reply's `stream` block: `state` `streaming`, `no_frames` (the stream started and delivered nothing — the `note` says so and, for a camera at jumbo packets, to reconnect with a 1500-byte packet size), `starting` or `start_failed`, with `waited_s`. `None` for a camera that was already connected. A preview (`get_camera_preview`, `/api/camera/jpeg/<serial>`) asked for right after waits, bounded (4 s), for the camera's first preview frame instead of answering "No frame available yet"; a camera whose stream has delivered nothing (`no_frames`, or armed for a hardware trigger) still answers at once.
* **The packet size is yours to pin.** `settings={"gev_packet_size": 1500, "gev_packet_size_auto": False}` opens the camera at 1500-byte packets, not probed (`chloros-cli lattice cam-connect --packet-size standard` sends the same).
* **One connect at a time holds the camera pool**: the open, the packet-size probe, a first calibration download (about 70 s for a camera new to this computer), the stream start. A request that needs a camera meanwhile (`read_nodes`, `set_settings`, a capture, a second connect) waits for it at most 5 s, then fails with HTTP 503 `CAMERA_POOL_BUSY`, naming the camera connecting (`ChlorosConnectError`); ask again in a moment. The listings never wait: `list_cameras()` (`GET /api/camera/pool`), `list_arrays()` and `CameraSession.status()` answer at once. A camera mid-connect is listed under the pool reply's `connecting` (`serial`, `phase` — `opening the camera`, `rebalancing the pool bandwidth`, `loading its calibration`, `starting its stream`, `waiting for its stream` — and `elapsed_s`), and its `status()` says `connecting: True` with its `phase`; the other cameras are read live when the pool is free, else answered from their last read (`live: False`).

#### `CameraSession` Methods

| Method                                                                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status(timeout=15.0)`                                                                                                                                                   | The camera's live state, as `chloros-cli lattice status` reads it: `streaming`, `stream_state` (`starting`, `no_frames`, `streaming`, `start_failed` or `stopped`), `device` (model, serial, firmware, temperature, `is_mono`) and its current settings.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `read_nodes(names, enum_names=(), timeout=30.0)`                                                                                                                         | Read GenICam nodes; returns `{nodes, errors, enums, device, was_in_pool, in_array_id}`, plus `frame_values` and `notes` while auto exposure runs (see below).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `set_settings(**kwargs)`                                                                                                                                                 | Write nodes by friendly name (`exposure_time`, `gain`, `pixel_format`, `width`, `height`, `target_brightness`, `target_brightness_auto`, `ae_damping`, `ae_upper_limit`, `trigger_mode`, `trigger_source`, …). An `exposure_time` (`gain`) is a manual exposure (gain): written without `exposure_auto` (`gain_auto`), that auto mode is switched Off first, so the value is not refused by a running auto. The result's `applied` holds what the camera took; a write the camera refuses is in `errors` and is not held. The error names the range the camera accepts now (an `ExposureTime` maximum follows the camera's frame rate), and an auto mode that was switched Off only for the refused value is put back; `restored` lists it (e.g. `{"ExposureAuto": "Continuous"}`).                           |
| `capture(output_dir="output", ext=".tiff", jpeg_quality=95, processing=None, levels=None, force_daq=None, daq=None, daq_tolerance_ms=None, settings=None, timeout=None)` | Capture a **single** frame. Returns a `CaptureResult`: a list of frame metadata dicts (one per level saved), with `.skipped`, `.failed`, `.daq_files` and `.daq_matches`. (Burst/multi-frame capture was removed — call `capture()` in a loop if you need a series.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `capture_repeated(output_dir="output", *, count=None, duration_s=None, interval_s=0.0, on_capture=None, **capture_kwargs)`                                               | Back-to-back (`interval_s=0`) or interval captures from this camera, for `count` captures and/or `duration_s` (at least one, so it ends), as `ArraySession.capture_repeated()` does for an array. Returns the list of `CaptureResult`s; it stops after a capture that reports a full drive. `on_capture(i, result)` runs after each; other keywords go to `capture()`.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `disconnect(keep_settings=False, clear_settings=False)`                                                                                                                  | Release from the pool, the camera put back as it was found at connect (trigger wiring, PTP, settings); `keep_settings=True` saves its settings into its own memory instead, `clear_settings=True` resets that memory (see [Camera memory](#camera-memory--keep_settings--clear_settings)); returns `camera_memory` when either is asked for. A camera that is an array member releases the whole array. No-op if we attached to an already-open session. Returns once the backend confirms the release, or when there is nothing to release (the camera is already gone, or no backend is running); a release that timed out or that the backend refused raises `ChlorosConnectError`, because the camera may still be held and the next connect would collide with it. The `with` block's exit never raises. |

Attributes: `serial`, `device` (the camera's discovery record) and `backend_url`.

`capture()` export controls (same model as the array + GUI):

* `processing` / `levels` — `processing="all"` saves every applicable export type; `levels=["raw","radiance"]` saves just those (overrides `processing`). Omit both for the backend default.
* `daq` — the DAQ reading the capture used is saved as a `.daq` sidecar by default, a raw-only grab included, so the frame can be reprocessed into reflectance/index later. `daq=False` skips it when no level uses it. `force_daq=True` is the older spelling of the default. No DAQ, no `.daq`.
* `daq_tolerance_ms` — how far from the exposure the reading may be and still be in tolerance (default 500). Only the verdict changes.

#### `read_nodes()` under auto exposure — `frame_values` and `notes`

While `ExposureAuto` (`GainAuto`) runs, the `ExposureTime` (`Gain`) node reads back the **last value written**, not what the camera is doing. `nodes` still holds that node value. When you ask for `ExposureTime` or `Gain` on a connected camera whose auto mode is not `Off`, the reply adds:

* `frame_values` — the value the camera's newest frame carried, under the node's name (`ExposureTime` in µs, `Gain` in dB);
* `notes` — one sentence per such node saying both values.

```python
r = cam.read_nodes(["ExposureTime", "Gain"])
print(r["nodes"]["ExposureTime"])                  # last value written, e.g. 2000.448
print(r.get("frame_values", {}).get("ExposureTime"))  # what the newest frame used, e.g. 19600.0
for name, note in r.get("notes", {}).items():
    print(note)
# ExposureAuto is Continuous: ExposureTime holds the last value written (2000.448);
# the camera's newest frame was at 19600 us.
```

Both keys are absent when the auto mode is `Off` (the node is then the camera's real value) and for a camera that is not connected to the backend. For an array, `ArraySession.status()["member_ae"]` gives every member's frame values at once.

#### DAQ-metered exposure ceiling (HTTP)

With a DAQ light sensor linked, Chloros bounds a camera's exposure × gain from the measured daylight so a white reference panel does not clip. The ceiling applies only while a calibration target is in that camera's view (seen in its frame within the last 10 s); with no target in view, the camera's ordinary automatic exposure, with its own highlight protection, runs instead, so the rest of a scene is not held darker than it needs to be. There is no SDK wrapper; read or switch it per camera with `GET` / `POST /api/camera/<serial>/daq-exposure-cap` (POST body `{"enabled": false}` turns it off for that camera). The reply carries `enabled`, `cap_us` (the live ceiling, `None` while inactive, including while no calibration target is in view), `k_exp_g` (the constant the ceiling is computed with) and:

| Field            | Meaning                                                                                                                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `k_exp_g_source` | Whose constant is in use: `camera` — this camera's own, computed from the lab point in its calibration pack (RGB cameras); `fleet` — the fleet constant, used where the pack has no lab point; `override` — a field override set on the backend. |
| `k_exp_g_fleet`  | The fleet constant, for comparison.                                                                                                                                                                                                              |

### Synchronized Array — `ArraySession` (Smart-Prep)

`connect_array` is **the recommended entry point** for multi-camera setups. It runs the full GUI smart-prep flow under the hood:

1. **Network analysis** (`/api/camera/array/recommend`) — sets the **full sensor** (no binning, no ROI crop) and lets the frame rate fall to what this host and network deliver, projected with the pixel formats and packing connect will use. Frames are never shrunk to keep the rate up: pass a smaller `width` / `height` or `binning=2` / `4` to trade resolution for frame rate (the endpoint's `alternatives` list those options with their projected fps).
2. **Tier auto-pick** — `sim-capture-sim-emit` (every camera exposes on the same trigger, emit paced to share the wire, frame rate falling as the share shrinks) on any network the cameras can be paced to share; `slip-emit-and-capture` (cameras take turns on the wire, not exposed simultaneously) only when they cannot.
3. **PTP enabled** by default — cross-camera timestamps land on one shared clock to **\~1 ms**, the backend's [PTP grandmaster](#ptp-grandmaster--time_sync_status). Simultaneous exposure comes from the M8 hardware trigger (**< 100 µs** inter-module), not from PTP: PTP aligns *timestamps*, not exposures.
4. **Per-cam pixel-format auto-pick** — mono → `Mono12`, colour → `BayerRG12`.
5. **AE seeding** — snapshots each cam's current AE state so connect doesn't reset exposure mid-flight.
6. **GPIO trigger config** — `connect_array` arms every camera (`TriggerMode=On`, `TriggerSource=Line2`) so the master's pulse drives the slaves over the M8 cable. This is an array-only step: a single camera opened with `LatticeCamera` free-runs instead. Releasing the array (`disconnect()` / `force_disconnect()`, `chloros-cli lattice array-disconnect`) sets every camera back to free-running (`TriggerMode=Off`), with everything else as the connect found it: the trigger and sync-line settings (`TriggerSource`, `TriggerActivation`, `TriggerOverlap`, `TriggerDelay`, `LineMode` / `LineSource`; the master's sync line back to an input), PTP, and the camera settings the session changed — unless `keep_settings=True` / `clear_settings=True` (see [Camera memory](#camera-memory--keep_settings--clear_settings)).

```python
import chloros_sdk

# First serial is the MASTER (fires the trigger pulse); rest are slaves.
with chloros_sdk.connect_array(
        ["213800234", "214000533", "214701288", "214701292"]) as arr:
    print(arr.array_id, arr.sync_mode, arr.ptp_enabled)
    arr.capture("output/", processing="reflectance")
```

Attributes: `array_id`, `master_serial`, `slave_serials`, `ptp_enabled`, `sync_mode`, `packed_transport` and `packed_reason` (the last four are `None` on a handle from `attach_array`), `connect_stream` and `backend_url`. `connect_stream` is the connect reply's `stream` block, the single connect's shape plus `members` (`{serial: {state, why?}}`): `streaming` once the array's first synced group arrived (the backend waits for it, bounded, about 10 s), or `no_frames` with each member's last fetch failure as its `why` and, for jumbo packets, the 1500-byte fallback in the `note`. `None` on an `attach_array` handle.

#### `connect_array()` Signature

```python
connect_array(
    serials,                              # list[str]; serials[0] = master
    *,
    line="Line2",                         # GPIO sync line: Line0 | Line2 | Line3
    target_fps=None,                      # pin the master trigger rate (auto if None); see set_target_fps
    force_tier=None,                      # override tier picker; see below
    wire_ceiling_mbps=None,               # host sustained wire budget, MB/s (auto if None)
    width=None,                           # explicit frame size; skips network analysis
    height=None,
    pixel_format=None,
    binning=None,
    recommend=True,                       # set False to skip the recommend step
    ptp_enable=True,                      # set False to disable PTP
    packed="auto",                        # packed 12-bit transport: "auto" | "on" | "off"
    backend_url="http://127.0.0.1:5000",  # same IPv6-avoidance default as connect_camera
    timeout=600.0,                        # s; also the backend's deadline (see below)
    auto_start_backend=True,              # spawn a local backend if none is running
) -> ArraySession
```

`timeout` is how long the call waits for the connect, and it is sent to the backend as its deadline. A connect not done by then is undone: every camera it opened is put back as it was found and closed, no array is connected, and the call raises `ChlorosConnectError` (HTTP 504 `CLIENT_DEADLINE_PASSED`, naming the step the connect had reached). So a call that raised never leaves an array connected behind it. A 9-camera array connects in about a minute; right after the cameras power on it can take several. An array that is up but has no synchronized frame group yet is returned, with `connect_stream["state"]` `no_frames`. The backend's log has one timing line per connect step (`[array-connect <id>] <step>: <s> s …`) and a last line naming the slowest.

`force_tier` values:

* `"sim-capture-sim-emit"` — true simultaneous (all cams fire on the same clock edge).
* `"sim-capture-ftd-stagger"` — flexible time-domain stagger (cams emit at slightly offset times so packets serialize on the wire).
* `"slip-emit-and-capture"` — sequential per-cam capture (no temporal sync). Picked automatically only when the cameras cannot be paced slowly enough to share the wire simultaneously.

`wire_ceiling_mbps` overrides the **host's sustained wire budget** in MB/s — the single number the whole array allocation hangs off. Leave it `None` to use the auto-detected value. 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 — and the over-estimate surfaces as corrupt frames rather than as a visibly slow link. The value is persisted in the project's array capture block, so a reopen or a later `connect_array` restores it like any other array setting. See [Array Health](#array-health--which-subsystem-is-losing-frames).

#### 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 the host, 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.

* `packed="auto"` (default) packs only when it helps **and** the host can afford the unpack: at connect the backend measures its own unpack speed, CPU count, current load and network budget. A desktop with cores to spare packs at full sensor; a busy or low-power host (single-board computers, embedded controllers) streams unpacked. Small ROIs and binned frames gain little.
* `packed="off"` (or `False`) never packs — to rule it out while diagnosing, or on a host that must keep its CPU for other work.
* `packed="on"` (or `True`) always packs 12-bit formats.
* Any other value raises `ValueError`. 8-bit and 16-bit formats are never packed.

`analyze_array_network(..., packed="auto")` projects with the same decision, so its fps is the rate the array will run at (the response carries `packed_transport` and `packed_reason`); its `pixel_format` defaults to what connect applies (Mono12 / BayerRG12) rather than 8-bit.

The decision and its reason are on the session:

```python
arr = chloros_sdk.connect_array(serials)          # packed="auto"
print(arr.packed_transport, arr.packed_reason)
# True  auto: projected 11.0 -> 14.4 fps, unpack 0.16 of 1.50 budgeted cores

arr = chloros_sdk.connect_array(serials, packed="off")
```

`ChlorosProject.connect_all(packed=...)` applies the same override to every array in a project (default `None`, which means `"auto"`: a project saves no packed setting per array). For a machine-wide default, set `CHLOROS_ARRAY_PACKED12=off` (or `on`) in the backend's environment; an explicit `packed="on"` / `"off"` still wins. `/api/camera/array/status` reports `packed_transport` and `packed_decision`.

#### Expected Frame Rates

Measured array frame rates (hardware-synced, 12-bit; full sensor = 2048 × 1536). Use them to sanity-check `status()["actual_fps"]`; `analyze_array_network()` projects the rate for your own host and network.

| Setup                                                                              | Array frame rate |
| ---------------------------------------------------------------------------------- | ---------------- |
| Full sensor, PCIe 10 GbE host NIC, packed transport (`packed="auto"` on a desktop) | \~14 fps         |
| Full sensor, PCIe 10 GbE host NIC, unpacked (`packed="off"`)                       | \~10.5 fps       |
| Full sensor, 8 cameras on a USB 10 GbE adapter                                     | \~3.8 fps        |
| Full sensor, 1 GbE host link                                                       | 1.2–1.7 fps      |
| 2 × 2 binning (`binning=2`), 10 GbE host NIC                                       | \~30–33 fps      |

* On a PCIe 10 GbE link the **cameras** are the limit at full sensor, not the network: 4 and 8 cameras run at the same rate.
* **`target_fps` is the trigger rate, and the array never runs faster.** `target_fps=1` runs the array at 1 fps; `None` (the default) runs it at the highest rate the host and network carry. A pin above that rate is lowered to it (see [`set_target_fps`](#interval-capture-for-drone-surveys)).
* **`link_speed_mbps` of `4294` in `status()` is not a link rate.** It means Windows could not read the adapter's speed (the driver reported the largest 32-bit value), which is typical of USB Ethernet adapters. A USB adapter's usable rate on Windows is capped at 200 MB/s regardless (see [Array Health](#array-health--which-subsystem-is-losing-frames)); for tuning one, see the CLI reference's "USB 10GbE adapters" section under [Host NIC Setup & Tuning](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#host-nic-setup--tuning-lattice-arrays).
* **A USB cap applies on Linux too: 400 MB/s on x86\_64, 200 MB/s on NVIDIA Jetson.** The adapter is identified from sysfs (falling back to `ethtool -i`), so a USB 5 GbE or 10 GbE adapter is budgeted at the cap rather than its 500 / \~1060 MB/s nameplate. The x86\_64 figure was measured on Linux: the same adapter that corrupts frames above 200 MB/s on Windows ran a 4-camera array clean at every ceiling up to 480 MB/s. On NVIDIA Jetson the same adapter was clean only at 200 MB/s and lost frames intermittently above it. If your host absorbs more without `gvsp_corrupt` frames, raise it with `wire_ceiling_mbps`. On Linux an adapter on a USB 2.0 port is budgeted 30 MB/s; plug it into a USB 3 port.

#### Over-Subscription (the per-cam floor)

An array works on any network; the frame rate is what gives. Sim-emit pacing allocates each camera an even share of the collision-safe wire budget and all of them still expose on the same trigger, so on a slow wire the share — and the frame rate — is small: 8 full-res 12-bit cameras on 1 GbE without jumbo frames get 6.5 MB/s each, about **1 fps** (about 1.3 fps packed). The share is floored at the slowest rate the cameras can be paced to (`per_cam_floor_bps`: read from each camera's GevSCPD range at connect, and never below 1 MB/s). If the wire needs them slower than that, connect falls back to **serial** emit (`slip-emit-and-capture`): the cameras take turns at full link rate, so every frame arrives but the members are **not exposed simultaneously** — the response's tier and blockers (`SERIAL: ...`) say so; pass `force_tier="sim-capture-sim-emit"` to refuse the fallback. Frame size does not enter the sharing, so **binning and ROI raise the frame rate but do not change whether an array fits**. Only a wire that cannot carry the array at any pacing, simultaneously or in turn, **over-subscribes** — the failure mode is GVSP packet loss, not a lower frame rate. Remedies: fewer cams, jumbo frames end-to-end, or a faster NIC.

* The `analyze_array_network()` and `/api/camera/array/connect` responses carry `oversubscribed`, `aggregate_demand_bps`, `collision_safe_ceiling_bps`, `max_cams_collision_safe`, and `per_cam_floor_bps`. When `oversubscribed` is true, the projection **zeroes the fps fields** (`achievable_fps_max` / `fps_bright` / `fps_dark`) rather than reporting a misleading slow-but-working rate.
* `POST /api/camera/array/connect` accepts a `pin_resolution` body param (**HTTP-only — not an SDK kwarg**; `connect_array` doesn't expose it). It is strict mode: an over-subscribed connect with `pin_resolution` set is **hard-refused** with an error naming every remedy. Without it, connect proceeds with a warning that the array will lose packets. Either way connect keeps the requested frame size — it never bins or crops on its own.
* For testing only: set `CHLOROS_ARRAY_ALLOW_OVERSUBSCRIBED=1` in the backend's environment to downgrade the refusal to a loud warning — you connect anyway and accept the packet loss.

#### Array Health — which subsystem is losing frames

`ArraySession.capability()` (`GET /api/camera/array/<array_id>/capability`) carries a live `health` block on a connected array, re-evaluated on a rolling **10-second** window. It splits frame loss into the two causes that need opposite fixes, instead of 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` | 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 %.                                | —                                                    |

Alongside `health`, 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; …)` or `user override 120 MB/s (auto said 200)`. |
| `wire_ceiling_is_user_set` | `true` when `wire_ceiling_mbps=` set it.                                                                                                  |
| `nic_is_usb`               | `true` for a USB Ethernet adapter.                                                                                                        |

```python
import chloros_sdk

serials = ["213800234", "214000533"]           # master first
arr = chloros_sdk.attach_array(serials)
h = arr.capability()

health = h.get("health", {})
print("wire ceiling:", h["wire_ceiling_mbps"], "MB/s", h["wire_ceiling_source"])
print("corrupt (network) :", health.get("worst_gvsp_corrupt_pct"), "%")
print("absent  (trigger) :", health.get("worst_never_arrived_pct"), "%")

if (health.get("worst_gvsp_corrupt_pct") or 0) > 1.0:
    # Network path. Reconnect with a lower budget -- NOT a lower target_fps.
    # force_disconnect(), not disconnect(): this handle came from attach_array,
    # and disconnect() never tears down an array the session only attached to.
    # It returns only once the backend confirms the release; a teardown that
    # timed out or was refused raises ChlorosConnectError instead, so the
    # reconnect below never races a half-released array.
    arr.force_disconnect()
    arr = chloros_sdk.connect_array(serials, wire_ceiling_mbps=120)
```

**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, while 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 re-plans against the new ceiling.

A **USB Ethernet adapter is capped at 200 MB/s** by the probe regardless of its nameplate: the efficiency table that turns a link rate into a sustained figure is PCIe-derived, and a USB NIC advertises its Ethernet link rate while being bounded by the USB bus and its driver. The cap is an absolute, not a fraction — a USB 1 GbE adapter derives \~80 MB/s and is unaffected. It applies on Windows and Linux (Jetson included); see [Expected Frame Rates](#expected-frame-rates) for where it was measured.

#### `ArraySession` Methods

| Method                                                                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status(timeout=10.0)`                                                                                                                                                                                                                                | Live state of the running array: `target_fps` / `target_fps_auto` (the trigger rate and whether the rate controller owns it), `target_fps_clamped_reason` (why a pinned rate is held lower, else `None`), `actual_fps` (measured; 0 once the grab loop has given up or stalled), `recommended_fps`, `streaming` (False once the grab loop has given up — check this, not just `last_error`; stays True through a settings restart, which `restarting` flags), `stalled` (True while the grab loop runs but has published no frame group for about ten frame periods, 2–30 s; `last_error` says so only after 60 s), `last_frame_age_s`, `last_error`, `serials`, `ptp_enabled` (`True` only when the array was connected with PTP **and** every member last read `PtpEnable` on; not the same as locked, which `ptp_epoch` measures), `ptp_configured` (what the connect asked for), `ptp_off_members` / `ptp_unread_members` (members that last read `PtpEnable` off / did not answer), `member_recovery` (`None`, or a member that lost power or its link: `state` `waiting` while it does not answer, `reopening`, then `recovered`, with `members` and `why` — the array re-opens it when it answers again and gives it back its connect-time PTP, trigger and sync-line wiring, pacing and camera settings, then streams again with no new `connect_array`), and `ptp_epoch` (measured), `sync_mode` / `sync_tier`, `packed_transport` / `packed_decision`, `per_cam_emit_mbps`, `link_speed_mbps` (`4294` means Windows could not read the adapter's speed — see [Expected Frame Rates](#expected-frame-rates)), `trigger_pipeline` / `pipeline_tune`, `radiometric_chain` (whether the per-band radiance chain is usable, and which member broke it), and `band_clamp` — while a live view renders the array: the share of lit pixels the unmix clamped to 0, per member (`members`: `{serial: [band0, band1, band2]}` in the camera's R, G, B band order) and per band the composite shows (`composite`: `{band name: share}`), with `warn`, the share the GUI flags as "Low-confidence band data" (measured about once a second; `None` when no live view is running), and `member_ae` — per member, the exposure (`exposure_us`) and gain (`gain_db`) its last published frame carried, from the frame itself (`read_nodes` of `ExposureTime` / `Gain` returns the last value written while auto exposure runs, not what it is doing). |
| `set_member_settings(serial, **kwargs)`                                                                                                                                                                                                               | Write one member camera's settings, as `CameraSession.set_settings()` takes them (exposure, gain, target brightness, ...); the member stays in the array. Raises `ChlorosConnectError` for a serial that is not a member. See [Exposure on Array Members](#exposure-on-array-members).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `capability(timeout=10.0)`                                                                                                                                                                                                                            | What the smart-prep settled on (the capture tier, frame size, `pixel_format`), the live `health` block and the host's wire budget. See [Array Health](#array-health--which-subsystem-is-losing-frames).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `set_target_fps(fps, timeout=10.0)`                                                                                                                                                                                                                   | Change the trigger rate while the array runs, without reconnecting. A number pins it (the rate controller leaves it alone); `None` returns it to auto. Returns `{requested, target_fps, target_fps_auto, clamped}` — `clamped` is True when the rate was lowered to what the host and network can carry. See [Interval Capture for Drone Surveys](#interval-capture-for-drone-surveys).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `grab(processing="debayered", with_metadata=False, apply_calibration=True, apply_white_balance=True, apply_index=False, index_expression=None, bit_depth=None, band=None, align=False, refl_max=None)`                                                | One frame from every camera, **all from one trigger**, as numpy arrays (no files written). Returns a `GrabResult` (a `dict`): `{serial: array}`, or `{serial: (array, metadata)}` with `with_metadata=True`. `.group_id` is the trigger the frames share; `.errors` maps each camera left out to the reason (a camera that cannot be served at that trigger is omitted, never filled from another one). `processing` is `raw` / `debayered` / `radiance` / `reflectance` / `display`. The same read as the project API's [`ArrayHandle.grab()`](#one-trigger-per-read--group_id) — one shared implementation — so every keyword there (`band`, `align`, `bit_depth`, `refl_max`) works here. Needs `numpy`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `frame_stream(*, processing="debayered", fps=5.0, duration=None, count=None, apply_calibration=True, apply_white_balance=True, apply_index=False, index_expression=None, with_metadata=False, bit_depth=None, band=None, align=False, refl_max=None)` | Iterator yielding one `grab()` result per tick (keyword arguments only), paced to `fps`, bounded by `duration` (seconds) and/or `count` (`None` = unbounded). **Each yielded set is a new trigger:** a tick whose newest trigger is the set it already yielded waits for the next trigger instead of repeating it, so the stream runs at the slower of `fps` and the array's own frame rate. Raises `FrameFetchError` rather than going silent: at once when every camera refuses for a reason the next tick would repeat, after 60 s of ticks with no frame, and after 60 s with no new trigger ("no new trigger for 60 s"). Same implementation as `ArrayHandle.frame_stream()`. See [Live Frames in Your Own Pipeline](#live-frames-in-your-own-pipeline).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `continuous(output_dir="output", *, format="tiff", processing="debayered", levels=None, aligned=None, render_index=None, force_daq=None, orient=None, max_captures=None, duration_s=None, daq=None, daq_tolerance_ms=None, timeout=30.0)`             | Start the backend's own continuous capture (the GUI's Continuous mode) → [`ContinuousHandle`](#continuoushandle). Saves **every** synced group the array publishes, as `capture()` would save it (same export controls), until stopped or until `max_captures` / `duration_s` (`None` = until stopped). Raises `ChlorosConnectError` if one is already running for this array.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `capture(output_dir="output", format="tiff", processing="debayered", levels=None, aligned=None, render_index=None, force_daq=None, orient=None, smart=False, after_seq=None, daq=None, daq_tolerance_ms=None, timeout=300.0)`                         | One synced capture group. Returns a `CaptureResult` (list of frame dicts + `.skipped` + `.failed` + `.group_seq` + `.daq_files` + `.daq_matches` + `.alignment` + `.oriented`). Pass a previous result's `group_seq` as `after_seq` to get the next synced group after it rather than waiting for a new one. Export controls below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `capture(..., smart=True)`                                                                                                                                                                                                                            | **Smart capture** — waits for AE to settle across all cams, then triggers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `capture_fastest(output_dir="output", force_daq=True, render_index=True, orient=None, timeout=120.0)`                                                                                                                                                 | Fastest capture: raw-only + the assigned DAQ reading (+ the free combined index). Mirrors the GUI "Fastest Capture" button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `capture_repeated(output_dir="output", count=None, duration_s=None, interval_s=0.0, on_capture=None, **capture_kwargs)`                                                                                                                               | Single / Continuous / Interval in one bounded loop. Returns `list[CaptureResult]`. **Requires `count` and/or `duration_s`** so it terminates (the SDK has no Ctrl+C). Also ends early, after the pass, when a pass reports a full drive (a `.failed` entry with `disk_full`); that pass is the last result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `record(output_dir="output", fps=10.0, duration_s=None, video=True, gif=False, expr=None, timeout=30.0)`                                                                                                                                              | Start recording the live combined-index view to video/GIF → `RecorderHandle`. The video is a Motion-JPEG `.avi` (no ffmpeg needed). With no GUI view open the backend renders it: `expr` (an index expression in the array's band names, e.g. `"(NIR_850_RGN-Red_660_RGN)/(NIR_850_RGN+Red_660_RGN)"`), or the array's NDVI by default. One composite recorder per array.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `burst(output_dir="output", duration_s=None, max_frames=None, index_config=None, serial_index_config=None, orient=None, timeout=30.0)`                                                                                                                | Start a high-fps raw-Bayer burst → `RecorderHandle`. Reprocess offline with `build_video()`. `orient=True`: the products `build_video()` makes are turned by the camera orientation (per-camera products by their own camera's, the combined index by the master's); the raw frames stay native and the burst manifest records every member's orientation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `build_video(burst_dir, products=None, fps=10.0, video=True, gif=False, save_tiffs=False, wait=True, poll_s=2.0, timeout=1800.0)`                                                                                                                     | Offline-reprocess a saved raw burst into calibrated video(s). Blocks until done (`wait=True`) and returns the build result: `{success, outputs, errors, skipped, substitutions, notes, degraded, combined}` — see [the build result](#the-build_video-result) below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `build_video_status(job_id, timeout=15.0)`                                                                                                                                                                                                            | Poll an offline build job: `{running, result, error, burst_dir}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `disconnect(keep_settings=False, clear_settings=False)`                                                                                                                                                                                               | Release the whole array — **if this session opened it** (`connect_array`): it is then `force_disconnect()`, and raises `ChlorosConnectError` when the release is not confirmed (the `with` block's exit never raises). On a handle from `attach_array` it leaves the array running and prints one line to stderr saying so: the array may belong to the GUI or another script. Each camera is left free-running and otherwise as the connect found it; `keep_settings=True` saves its settings into the camera's own memory, `clear_settings=True` resets that memory to the factory settings (see [Camera memory](#camera-memory--keep_settings--clear_settings)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `force_disconnect(timeout=60.0, keep_settings=False, clear_settings=False)`                                                                                                                                                                           | Release the whole array regardless of who opened it. Use it on an attached handle when ending the array is what you mean (e.g. to reconnect it with different settings). Returns once the backend confirms the release, or when there is nothing to release (the array is already gone, or no backend is running); a teardown that timed out or that the backend refused raises `ChlorosConnectError`. With either flag it returns what each camera's memory got (`camera_memory`), else `None`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

`capture()` export controls (same endpoint the GUI/CLI use):

* `processing` / `levels` — `processing="all"` (or `levels=["raw","radiance",…]`) saves every applicable export type per cam; a single `processing` value saves just that level.
* `aligned` — **on by default (`None`), as the Chloros app's capture of the same array is** (its per-array **Aligned** Capture Setting). Every member's non-raw export is warped into the master camera's frame by the array's [alignment profile](#array-alignment) 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 (under an ROI the transform is re-based onto the window); `XMP-mapir:AlignmentJSON` says `"applied": true` with its `crop_roi`. Raw stays unwarped at the native size but carries the transform in metadata. `aligned=False` saves every file at the native size, unwarped; `aligned=True` is the default spelled out. `continuous()`, `capture(smart=True)`, `capture_repeated()` and the project-level `ArrayHandle.capture()` / `capture_smart()` take the same default. 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 result says so: `result.alignment` is `{"requested": True, "applied": False, "warnings": [...]}`, one warning per reason the warp could not be applied (no profile, members at different resolutions, an array not cable-synced, a frame the profile cannot be mapped onto). `applied` is `True` only when every export that asked for the warp got it. The array's auto-alignment makes the profile once its exposure settles; `ArrayHandle.calibrate_alignment()` / the CLI's `align-calibrate` make one on demand. `result.oriented` says whether `orient=True` turned the products.
* `render_index=False` — skip the per-cam vegetation-index overlay; default renders it where configured.
* `daq` / `daq_tolerance_ms` — the DAQ reading is saved as a `.daq` sidecar by default, even when no chosen level needs it; `daq=False` skips it then, and `daq_tolerance_ms` sets the match tolerance (default 500). `force_daq=True` is the older spelling of the default. See [The DAQ reading a capture saves](#the-daq-reading-a-capture-saves--daq_files-and-daq_matches).
* `orient=True` — turn each member's **products** (`display`, `radiance`, `reflectance`, the per-cam index and the composite) by the camera orientation, after the alignment warp: by the **master's** orientation when they were warped into its frame (the `aligned` default — the members stay co-registered), else by their own camera's. **Default: every member file native**, as array captures always have; `raw` and `debayered` stay native either way. Every file records the orientation of the frame its pixels are in (`XMP-Camera:ChlorosRotation` / `ChlorosFlip*` / `ChlorosOrientationApplied` — a raw, its own camera's), and the `Alignment*` XMP stays the native-frame transform, applied before the orientation; a raw carrying that transform also records `ChlorosAligned*` (the master's), the orientation of a product warped into the master's frame. Processing turns each product by the one that belongs to its pixels: the aligned one when it warps the raw (Array alignment on), the camera's own when it does not. `capture_repeated()` and `capture_fastest()` pass it through; the project-level `ArrayHandle.capture()` / `capture_smart()` take it too.

**TIFF compression (HTTP-only knob):** `ArraySession.capture()` sends no `compression` key, so the backend default applies — `POST /api/camera/array/capture` reads a `compression` body param, `"none"` by default: uncompressed, the sensor's pixels exactly as read (\~6.3 MB per full-res frame). `"deflate"` (lossless zlib L1 + horizontal predictor, \~4.1 MB/frame) writes smaller files more slowly — both are lossless and read identically on import. The SDK exposes no kwarg for it; the escape hatch is `chloros-cli lattice array-capture --compression deflate` or raw HTTP. DEFLATE holds the Python GIL, so compressed writes don't parallelize across the per-cam writer threads — sustained full-res capture at sensor rate needs the uncompressed default. Details: [CLI Reference → array-capture](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md).

**Consecutive groups (HTTP):** the endpoint returns `group_seq`; a loop that sends it back as `after_seq` on its next request gets the next synced group — including one published while the previous capture was saving — instead of waiting for a group published after the request, and `skipped_groups` reports any the loop missed. `capture_repeated`, the CLI's `--continuous` and the GUI's Continuous mode all do this; interval passes stay fresh at each scheduled moment.

**Per-member export overrides (HTTP-only):** the same endpoint also accepts `exclude_serials` (list — drop members from the saved set; the array still triggers as one synced group and excluded members are returned in `excluded`), `serial_levels` (`{serial: [level tokens]}` per-cam level overrides), and `serial_index` (`{serial: bool}` per-cam index-overlay overrides). These are GUI-parity body params and **not SDK kwargs yet**; members absent from the maps fall back to the array-wide `levels` / `render_index`.

**Inspecting Skipped Cams — `CaptureResult.skipped`**

`ArraySession.capture()` returns a `CaptureResult`, which is a `list` subclass: iterate it, index it, `len()` it — every existing pattern keeps working. New code can inspect the `.skipped` attribute to see which cams were excluded and why. The most common case is RGB cams in a mixed-filter array when you ask for `processing="radiance"` or `"reflectance"` — per-Bayer radiance is meaningless for a broadband sensor, so the backend skips those cams rather than producing nonsense.

```python
with chloros_sdk.connect_array(serials) as arr:
    result = arr.capture("output/", processing="reflectance")

    # Back-compat: iterate as a plain list
    for frame in result:
        print(frame["filepath"], frame["serial"])

    # New: see why N-1 cams were saved
    for skip in result.skipped:
        print(f"skipped SN:{skip['serial']} reason={skip['reason']}")
        # e.g. {'serial': '214701292', 'level': 'reflectance',
        #       'reason': 'reflectance-not-applicable-to-rgb-cam',
        #       'filter': 'RGB'}
```

Reason tokens follow the pattern `<level>-not-applicable-to-rgb-cam` (one entry per skipped level, each carrying `level`). 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`. The other reflectance-specific skips are `reflectance-skipped-no-fresh-dls` (no fresh downwelling reading available), `reflectance-skipped-bound-daq-unavailable (…)` (the bound DAQ could not be reached), and `dls-uncalibrated-band-<nm>` — the band lies mostly outside the DAQ light sensor's radiometrically calibrated range (\~374–974 nm), so the absolute DAQ-based reflectance divide is refused and the frame demotes loudly to sensor-response. Among shipping SKUs only F988 triggers it; that camera's supported path is the reflectance-panel workflow.

**Files That Could Not Be Written — `CaptureResult.failed`**

A capture that could write only some of its files still returns: the list holds every file that **was** written, and `.failed` lists the rest, one dict per file with `serial` (`None` for the combined composite and an array's `.daq` sidecar), `level` (`raw`, `radiance`, …, `index`, `composite`, `daq`, or `match` — the `.daq`'s `.match.json` provenance, when the `.daq` was written but its sidecar was not) and `error`. On a full drive the entry also carries `disk_full: True`; every later capture to that drive would fail the same way, which is why `capture_repeated()` stops there. No exception is raised for a partial capture, and a file in `.failed` was not left on disk half-written. `.failed` is empty on a clean capture.

```python
result = arr.capture("output/", processing="all")
for f in result.failed:
    print(f"SN:{f['serial']} {f['level']} not written: {f['error']}")
if any(f.get("disk_full") for f in result.failed):
    raise SystemExit("drive full -- free space and capture again")
```

**The DAQ reading a capture saves — `.daq_files` and `.daq_matches`**

Whenever a DAQ is bound to the camera or array, or pooled, every capture saves the downwelling reading it used: a `.daq` in the capture folder's `daq/` subfolder, with its `.match.json` and its `.cameras.json` (whose reading it is). That holds for a raw or debayered capture too, and it is the same file whether the capture came from the GUI, the CLI or the SDK. `daq=False` skips it for a capture whose levels do not use the DAQ (a `radiance`, `reflectance` or `display` level still writes it); `daq_tolerance_ms` moves the in-tolerance line for that capture and never the reading used. Which DAQ: the one bound to the camera or array (the GUI's light-sensor selection, a project's binding, or `chloros-cli daq pool-bind`), else the freshest the backend has. The CLI spells the controls `--no-daq` and `--daq-tolerance-ms` ([CLI Reference](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#the-daq-reading-a-capture-saves)).

```python
r = cam.capture("out", levels=["raw"])      # a CameraSession; ArraySession results match
for m in r.daq_matches:                      # one per .daq in r.daq_files
    print(m["daq_file"], m["gap_ms"], m["in_tolerance"])
```

A capture saves the light-sensor reading it used as a `.daq` with a `<file>.daq.match.json` beside it, saying how the reading was tied to the exposure: `method`, `gap_ms` (from the exposure to the nearest DAQ reading) and `in_tolerance` (within 500 ms, or the capture's `daq_tolerance_ms`). The reflectance file's XMP carries the same verdict as `Chloros:DlsMatchMethod`, `Chloros:DlsMatchGapS` and `Chloros:DlsInTolerance`.

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 `capture()` returns up to about one and a half of those intervals later; the exposure itself is not delayed. 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 to that middle, and the `.match.json`'s `bracket_stamps_ns` gives the readings' own timestamps. `ArraySession.continuous()` waits without slowing the capture. `capture_repeated()`'s back-to-back passes do not wait, so they keep their rate, and are matched to the nearest reading before the exposure.

A reading never expires, so no frame is lost to a late one — it is labelled instead:

* **The DAQ's stream stalled** — its newest reading is used, and `gap_ms` says how old it is (`in_tolerance: false` past 500 ms).
* **No DAQ to read** — disconnected (`disconnect()`, `chloros-cli daq pool-disconnect`), or the bound DAQ cannot be reached — the camera's last reading is reused and described against **this** exposure: `method` `retained`, `gap_ms` from this exposure, `in_tolerance` recomputed, and `retained_from_epoch_ns` naming the exposure it was first matched to. A camera that never had a reading still gets no reflectance, and the result says why (`reflectance-skipped-no-fresh-dls` / `reflectance-skipped-bound-daq-unavailable (…)`, or the capture's refusal).

Files a capture saves inside the folder of the project open in Chloros join that project's file list, as a capture in the app does (files saved elsewhere are left alone): `CameraSession.capture()`, `ArraySession.capture()` (`smart=True` too) and `capture_cameras_transient()`. The result says so in `.project_add` (`capture_cameras_transient()`: the dict's `project_add`) -- `held`, `files` and the backend's `message`; `held` is `True` while a processing run is in flight, and the files join once it ends. `None` when no file landed in the project.

`CameraSession.capture()` and `ArraySession.capture()` return them as the result's `.daq_files` and `.daq_matches`, as the HTTP capture responses (`/api/camera/<serial>/cli-capture`, `/api/camera/capture`, `/api/camera/capture-all-synced`, `/api/camera/array/capture`) carry `daq_files` and `daq_matches`, one per `.daq`: `daq_file`, `cameras`, `method`, `gap_ms`, `in_tolerance`, `tolerance_ms`, and `stream_fault` — the DAQ's own stream fault, looked up only for a reading out of tolerance. Before relying on reflectance from a capture, check `in_tolerance` in its `.match.json` or XMP, or the DAQ's [`status()`](#daqsensorsession-methods).

`processing` levels:

| Level                         | Output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"raw"`                       | Single-channel Bayer (mono cams: the single band) straight from the sensor.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `"debayered"` *(SDK default)* | 3-channel colour: 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 saved TIFF is in **RGB** channel order (photometric RGB, so any image viewer shows true colour); the in-memory arrays `grab()` / `frame_stream()` return are in OpenCV's **BGR** order — reverse the channels (`frame[..., ::-1]`) to compare one with a saved file. `chloros-cli process` writes the same product as `Debayered_Images`. |
| `"radiance"`                  | float32 W/m²/sr/nm via the full radiometric chain. Multispectral only — RGB cams are skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `"reflectance"`               | uint16 0..32768 (Pix4D-ready); requires a live DAQ pairing for absolute reference. Multispectral only.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `"display"`                   | Full chain matching the GUI preview (CCM + WB + gamma per the cam's profile).                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `"all"`                       | **One file per applicable level** for each cam (matching the GUI "Capture All" / CLI default). The returned `CaptureResult` then holds one frame dict per `(cam, level)`, with the level in each dict; inapplicable levels appear in `.skipped`. The DAQ reading the capture used is saved as a `.daq` sidecar.                                                                                                                                                                                                                          |

> **Note — default differs from the CLI.** `ArraySession.capture()` defaults to `processing="debayered"`; the `chloros-cli lattice array-capture` command defaults to `processing="all"`. Pass `processing="all"` explicitly from the SDK to mirror the CLI/GUI multi-level save.

**Array capture file names**

Every level is saved in its own subfolder of `output_dir` (`raw/`, `debayered/`, `radiance/`, `reflectance/`, `preview/` for `display`, `index/`, `composite/`). Each file names its camera as `SN<serial>-<filter>`: the serial, then the filter part of the camera's model — `SN214000533-FOCN` for an `M3C-L87-FOCN`, `SN261902142-F450` for an `M3M-L87-F450` — joined with `-`, so a name has the same `_`-separated fields as before. A camera whose model cannot be read is `SN<serial>` alone, and captures from earlier releases have no filter in the name. The file name depends on how many levels a member was asked for:

| Member asked for                                                             | File name                                                                                                                   | Example (`reflectance`, default `format="tiff"`)          |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **One level** (`processing="reflectance"`, or a one-item `levels`)           | `sync_<timestamp>_SN<serial>-<filter>.<format>` — no level suffix, as in earlier releases, so existing scripts keep working | `reflectance/sync_<ts>_SN214000533-FOCN.tiff`             |
| **Several levels** (`processing="all"`, or `levels` with more than one item) | `sync_<timestamp>_SN<serial>-<filter>_<level>.<format>`                                                                     | `reflectance/sync_<ts>_SN214000533-FOCN_reflectance.tiff` |

The [clamp mask](#unmix-clamp-mask--which-pixels-a-band-was-clamped-on) follows the product's name, `clamp_masks/<product folder>/<product name>_clampmask.tif`: a single-level reflectance capture writes `clamp_masks/reflectance/sync_<ts>_SN<serial>-<filter>_clampmask.tif`, while `processing="all"` writes `clamp_masks/reflectance/sync_<ts>_SN<serial>-<filter>_reflectance_clampmask.tif`. The suffix rule is decided per member from the levels it was asked for, so a skipped level (e.g. reflectance on an RGB camera) does not change it. Read the paths from the returned frames rather than building them. A single-camera capture (`CameraSession.capture()`) always adds the level: `capture_<ts>_SN<serial>-<filter>_<level>.tiff`.

**PNG / JPEG take the display and index products only**

A PNG or JPEG holds 8 bits per channel. Asking for one with a level it cannot hold is refused before anything is captured, with a message naming the level and TIFF as the format that holds it:

* **`radiance`** (float32) and **`reflectance`** (uint16, `32768` = 1.0) — and so `processing="all"`, which includes them. The SDK checks this on the arguments: `capture()` raises **`ValueError`** without a request (`CameraSession`, `ArraySession`, `CameraHandle`, `ArrayHandle`, `capture_smart`).
* **`raw` / `debayered` from a camera streaming more than 8 bits** (12-bit M3C, Mono12 M3M) — the backend refuses these, knowing each camera's bit depth: HTTP 400 with `error_code` `FORMAT_CANNOT_HOLD_LEVEL`, raised as `ChlorosConnectError` (`CameraSession` / `ArraySession`) or `RuntimeError` (`CameraHandle` / `ArrayHandle`). The single-level `debayered` capture of one camera grabs an 8-bit frame for PNG/JPEG and is not refused.

Save radiometric data as `format="tiff"` (`ext=".tiff"`); use PNG/JPEG for `display` and index renders.

#### 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.

#### Exposure on Array Members

A LATTICE camera caps `ExposureTime` at one period of its frame rate. While an array streams, Chloros runs every member with `AcquisitionFrameRateEnable` on, at a rate just above the trigger rate, so a member's exposure ceiling sits a little under the trigger period, **at any ROI**:

* A member's frame period is the trigger period less a slack of 15 % of the period (at least 3 ms, at most half the period), and its exposure ceiling is that frame period less about 0.1 ms. Example: a 10 fps trigger (100 ms) gives a member rate of about 11.8 fps and an exposure ceiling of about 85 ms.
* **A manual `ExposureTime` longer than that ceiling slows the trigger to fit it.** Chloros first opens that member's ceiling for the value and lets the slower rate run a few trigger periods (the write can take a few seconds longer), then writes it, and the trigger 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 now in the error, and the member's auto exposure is put back if it was switched Off only for that write. Before 1.3.0 a small ROI capped every member at the sensor's own free-run period, whatever the trigger rate: 4.9 ms at 768 × 304, so no member could be brightened.
* Chloros never shortens a manual exposure to fit a faster trigger. An auto rate stays within what the manual exposures allow; a pinned rate faster than an exposure allows leaves that member a ceiling long enough for it, and it takes triggers no faster than its exposure allows. Lower the exposure, or the pin, when every member must make every trigger.
* **Read-back:** reading a member's nodes shows `AcquisitionFrameRateEnable` True and `AcquisitionFrameRate` at the member's rate; the enable goes back off when the array stops.
* **The array owns those two nodes. Do not write `AcquisitionFrameRateEnable` or `AcquisitionFrameRate` on an array member** — set the array's rate with `target_fps` / `set_target_fps()` instead.

Write a member's exposure with `arr.set_member_settings(serial, exposure_time=20000)` (the keywords of `CameraSession.set_settings()`; `chloros-cli lattice exposure --serial` does the same). The member stays in the array. Do not open an array member with `connect_camera()`: connect refuses a camera that is already in an array, and the `CameraSession` it would return removes the camera from its array when it disconnects. `ArraySession.status()["member_ae"]` reports every member's exposure and gain from its newest frame.

### 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 — through a `ChlorosProject` (`open_project()`), which names its own folder to the backend (`project_path`). A camera, array or light sensor the project does not hold yet is added to its files when it connects (`connect_camera()`, `connect_array()`, the light-sensor connect, the CLI, the app, `chloros-mcp`), with its settings. A change from any mode (`set_settings()`, `ArraySession.set_member_settings()`, `set_target_fps()`, the array settings, `set_cap()`, the CLI, 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 — `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 — `ChlorosProject.process()` (which opens its project on the backend), `chloros-cli 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).

  * `ArraySession.record()` and `ArraySession.burst()`: the video, or the burst folder with every frame, moves there whole when the recording stops. The stop's result reports the new path (`out_dir`, `video_path`), and a build of the burst works from it. A move the drive refuses leaves the recording where it was written, and the result says so (`relocation_error`). A stopped burst's raw frames and `.daq` join the file list of the project it ends up in; a video is not added to a project's file list.
  * `ArraySession.continuous()`: every capture after the change is saved into the new project; the ones saved before stay where they are.
  * `DAQSensorSession.record_start()` (and the app's own light-sensor recording): the `.daq` moves into the new project's `light_sensor` folder when the recording stops; `record_stop()` returns the new path, and the file joins that project's file list.

  A recording into a folder outside the open project stays where it is, and `start_camera_continuous()` / multi-stream jobs 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 SDK call 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 camera 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.`

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 — `ArraySession.disconnect()` / `force_disconnect()`, the end of a transient function, the stop of `start_camera_continuous()` — it puts each one back the way it was found before the connect: its trigger and sync-line wiring, PTP and camera settings — `ExposureAuto` / `GainAuto` (and a manual `ExposureTime` / `Gain`), `TargetBrightness` and the AE limits and damping, white balance, black level, `PixelFormat`, binning and the ROI, the colour pipeline (`GammaEnable` / `Gamma`, `LUTEnable`, `ColorTransformationEnable`), `ReverseX` / `ReverseY`, `UserSetSelector`, PTP's `PtpSlaveOnly` / `PtpDomainNumber`, the packet size (`GevSCPSPacketSize` / `DeviceStreamChannelPacketSize`), the pacing (`DeviceLinkThroughputLimitMode` / `DeviceLinkThroughputLimit`, `GevSCPD`, `GevSCFTD`), the chunk data (`ChunkModeActive`, each `ChunkEnable` under its `ChunkSelector`), the trigger-input deglitch an array gives a slave's sync line (`LineFilterSelector` / `LineFilterWidth`) and the acquisition frame rate (`AcquisitionFrameRate` only where its enable was on: with it off the rate reads the most the pacing allows, 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.

For using the cameras outside a project, two arguments write the camera's **own memory** — what it powers up with, in any software (on `disconnect()` / `force_disconnect()`, every transient function, `start_camera_continuous()` and `ChlorosProject.disconnect_all()`; MCP: the same arguments of `disconnect_device` and the transient tools; CLI: `--keep-settings` / `--clear-settings`):

* **`keep_settings=True`** 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=True`** 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.
* Not both (`ValueError`; the backend answers 400). The reply carries `camera_memory`, per camera `{"saved_to": "UserSet2" | "UserSet1" | None, "errors": [...]}` or `{"cleared": bool, "errors": [...]}` — `force_disconnect()` returns it; for a job it comes with `stop()`.

The app does not offer these.

**Every way out puts the cameras back.** The as-found put-back runs on each exit path: `CameraSession.disconnect()` (the app's camera **X**), the app's **X** on an array or any array member (the whole array is released), closing the app (the backend gets up to 20 s to put every camera, array and running continuous recording back; a transient function or one-shot call still running stops at its next safe point, puts its cameras back first, for up to 8 s, and answers HTTP 503 `SHUTTING_DOWN`; a `connect_array()` still running stops before its next camera and puts back the cameras it has opened, for up to 10 s, and raises `ChlorosConnectError` (HTTP 503 `SHUTTING_DOWN`); and one that arrives during the shutdown opens nothing: HTTP 503 `SHUTTING_DOWN`), and a `chloros-cli` command that is killed or whose terminal closes (its job is stopped and its cameras put back first). A backend that crashes or is force-killed cannot put anything back; a power cycle returns each camera to its memory.

**A project sets its cameras itself.** When an array connects through a project — the app's open project, or a `ChlorosProject`, which names itself to the backend (`project_path`) — 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.

### Capture Modes & Recorders

The array surface mirrors the GUI capture panel: Single / Continuous / Interval / Fastest shutter modes, plus two recorders (live-composite video and raw burst → offline reprocess).

```python
import time, chloros_sdk

with chloros_sdk.connect_array(serials) as arr:
    # Single (default) — one synced group
    arr.capture("out/", processing="reflectance")

    # Fastest — raw + .daq + combined index now, calibrate later
    arr.capture_fastest("flightline/")

    # Interval — one reflectance pass every 2 s, 5 passes (bounded so it ends)
    arr.capture_repeated("timelapse/", count=5, interval_s=2.0,
                         processing="reflectance",
                         on_capture=lambda i, r: print(f"pass {i}: {len(r)} frames"))

    # Continuous — every synced group for 60 s, saved by the backend itself
    with arr.continuous("run1/", processing="raw", duration_s=60) as run:
        run.wait()
    print(run.result["captures"], run.result["captures_per_s"],
          run.result["stop_reason"])

    # Combined-index video/GIF recorder: the GUI's combined view, or with no
    # GUI open the array's NDVI (pass expr="..." for another index)
    with arr.record("monitoring/", fps=10, gif=True) as rec:
        time.sleep(30)
    if rec.result and rec.result.get("error"):   # leaving the block does not raise
        print("recording failed:", rec.result["error"])
    else:
        print(rec.result["video_path"])

    # Raw-Bayer burst → offline reprocess into calibrated video(s)
    with arr.burst("capture/", duration_s=5) as b:
        pass
    out = arr.build_video(b.result["out_dir"], products=[
        {"kind": "per_cam", "level": "reflectance"},
        {"kind": "combined", "level": "index"}])
    print(out["outputs"])
```

* **`capture_repeated`** is the SDK's Continuous/Interval loop. Because there's no `Ctrl+C` to break it from a script, you **must** pass `count` and/or `duration_s` (it stops when either is reached). `interval_s` is measured from the start of each pass (matching the GUI). Continuous passes (`interval_s=0`) chain `group_seq` → `after_seq`, so they are consecutive synced groups at the array's rate. Remaining kwargs pass straight through to `capture()`.
* **`continuous`** is the backend's own continuous capture — the GUI's Continuous mode. **Use it rather than `capture_repeated()` when you want every trigger on disk at a high frame rate:** `capture_repeated()` makes one HTTP request per group from your script, while `continuous()` keeps two captures in flight inside the backend with no round trip between groups. Measured at ROI 512 on a 9-camera array: 73–77 captures/s, against an array publishing about 78. Keep `capture_repeated()` for interval capture (`interval_s`) and for passes you inspect one by one. On Windows, exclude the backend from Microsoft Defender for high rates (see [Step 1](#step-1--install-the-chloros-platform-package)).
* **`record`** is *monitoring-grade*: it records the rendered live combined-index composite. With the GUI's combined view open it records that view as displayed. With none open, the backend renders the view itself: `expr` if you pass one, otherwise the array's NDVI (the red and NIR bands nearest 660 nm and 850 nm, as the live view picks them), once the array is aligned. Name bands in `expr` as the array names them: `<band>_<filter>` for an M3C camera (`NIR_850_RGN`, `Red_660_RGN`, `Orange_615_OCN`), `Mono_<filter>` for an M3M (`Mono_850`); a short colour name (`NIR`, `Red`) works only when one band of the array has it. A GUI view opened during the recording is recorded while it stays open. A recording that writes no frame fails with `error` `"no-frames: …"` (the array may still be aligning or settling its exposure), and `stop()` raises (see [`RecorderHandle`](#recorderhandle)). One composite recorder per array (raises if one is already running).
* **`burst` → `build_video`** is *analysis-grade*: `burst` writes raw frames + a per-frame manifest + one `.daq` per distinct DLS reading under `<output>/bursts/<base>/` at the grab loop's full rate (no chain, no exiftool, no live view). `build_video` time-matches each frame to the nearest `.daq` and re-runs the import pipeline's radiance/reflectance/index chain. `products` is a list of `{"kind": "per_cam"|"combined", "level": "radiance"|"reflectance"|"index"}` (default: the combined index). `burst().stop()` also auto-kicks a best-effort combined-index build, returned as `build_job` in the stop result.

**The `build_video` result**

| Key               | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`         | `True` only when every requested product was built as requested: at least one output, nothing in `skipped`, and not `degraded`.                                                                                                                                                                                                                                                                                                                            |
| `outputs`         | Paths of the videos (and GIFs) written.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `errors`          | Problems, as text.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `skipped`         | One `{"serial", "level", "reason"}` per requested product that produced **no** video — a camera's (no calibration bundle for that camera, no DLS reading for reflectance, the processing chain failing) or the combined index's, which carries `"kind": "combined"` and `serial` `None` (no red/NIR band pair among the cameras, no group with radiance for both bands). Any entry makes `success` `False`; the other videos are still written and listed. |
| `substitutions`   | Cameras rendered at a different level than requested, and why — an RGB camera asked for radiance/reflectance gets its display video, white-balanced when the camera's calibration bundle is available. Not a failure.                                                                                                                                                                                                                                      |
| `notes`           | Informational text, not problems — e.g. a camera with no per-camera index expression has no index video, or an RGB camera's display video is not white-balanced (no calibration bundle, or one without a factory white balance), naming the camera. Not a failure.                                                                                                                                                                                         |
| `degraded`        | `True` when a product was written but is not the one requested: the offline combined index is the built-in red/NIR normalized difference, so a configured index expression is not evaluated. Makes `success` `False`.                                                                                                                                                                                                                                      |
| `combined`        | Summary of the combined index: the bands used, the LUT range, frames built.                                                                                                                                                                                                                                                                                                                                                                                |
| `clamp_masks`     | Paths of the [unmix clamp masks](#unmix-clamp-mask--which-pixels-a-band-was-clamped-on) of the per-frame calibrated TIFFs (`save_tiffs=True`), in `clamp_masks/<level>/` beside the TIFFs' `<level>/` folder, one per TIFF in which a pixel clamped. A video carries none.                                                                                                                                                                                 |
| `clamp_fractions` | What a video says instead of a mask: one `{"kind", "serial", "level", "frames"}` per video product (`kind` `"combined"` for the combined index's member cameras), `frames` a list of `[frame, R, G, B]` — that frame's share of pixels the unmix clamped in the band its R / G / B channel holds (`Chloros:Band{R,G,B}UnmixClampFraction`).                                                                                                                |

#### `RecorderHandle`

Returned by `ArraySession.record()` and `ArraySession.burst()`. Use it as a context manager to auto-stop on scope exit, or drive it manually.

| Member                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_id`              | Backend job id (str).                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `kind`                | `"composite"` (from `record`) or `"raw"` (from `burst`).                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `start_stats`         | The dict returned by the `start` call.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `result`              | `None` while running; the final stop-result dict once stopped.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `stats(timeout=10.0)` | Live job stats (frames written, realized fps, elapsed).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `stop(timeout=60.0)`  | Stop the recorder; returns + caches the final result (`.result` stays `None` if the stop request itself failed). For a `record()` recording that failed — one that wrote no frame included (`error` `"no-frames: …"`) — it caches the result on `.result`, then raises `ChlorosConnectError`. Idempotent (a second call returns the cached result, without raising). Leaving a `with` block stops the recorder without raising, so check `rec.result.get("error")` after it. |

```python
rec = arr.burst("capture/")
# ... drive manually ...
print(rec.stats()["frames"])
result = rec.stop()
print(result["out_dir"], result.get("build_job"))
```

#### `ContinuousHandle`

Returned by `ArraySession.continuous()`. Use it as a context manager — leaving the `with` block stops the capture if it is still running — or drive it with `status()` / `wait()` / `stop()`. One continuous capture runs per array at a time.

| Member                           | Description                                                                                                                                                                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_status`                   | The status dict returned by the start call.                                                                                                                                                                                                                           |
| `result`                         | `None` while running; the final status dict once the capture has ended (set by `stop()`, or by a `status()` / `wait()` that saw it end).                                                                                                                              |
| `status(timeout=10.0)`           | Live status dict (fields below).                                                                                                                                                                                                                                      |
| `wait(timeout=None, poll_s=0.5)` | Block until the capture ends by itself — `max_captures` or `duration_s` reached, the array gone, a full drive, an error — and return the final status. With `timeout`, return the latest status after that many seconds even if it is still running: check `running`. |
| `stop(timeout=30.0)`             | Stop the capture and return its final status. Idempotent (a second call returns the cached result).                                                                                                                                                                   |

Status fields:

| Field                         | Meaning                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `running`                     | True while the capture runs.                                                                                                                                                                                                                                                                      |
| `captures`                    | Synced groups saved.                                                                                                                                                                                                                                                                              |
| `files`                       | Files written.                                                                                                                                                                                                                                                                                    |
| `failed_files`                | Files that could not be written (as in [`CaptureResult.failed`](#files-that-could-not-be-written--captureresultfailed)).                                                                                                                                                                          |
| `failed_captures`             | Capture attempts that failed as a whole, including ones the capture retried (an HTTP 503 while the array had no new group in time).                                                                                                                                                               |
| `skipped_groups`              | Groups the array published that were not saved (the capture fell behind).                                                                                                                                                                                                                         |
| `captures_per_s`              | Average save rate since the start.                                                                                                                                                                                                                                                                |
| `elapsed_s` / `started_at`    | Seconds run so far; start time (Unix epoch seconds).                                                                                                                                                                                                                                              |
| `last_group_seq`              | The newest synced group saved.                                                                                                                                                                                                                                                                    |
| `last_error`                  | The latest error, or `None`.                                                                                                                                                                                                                                                                      |
| `stop_reason`                 | Once ended: `count` (`max_captures` reached), `duration` (`duration_s` reached), `stopped` (`stop()` called), `array_gone` (the array was disconnected), `error` (20 failures in a row, or a request the backend rejected), `disk_full` (a file the drive had no room for). `None` while running. |
| `max_captures` / `duration_s` | The bounds it was started with (`0` = none).                                                                                                                                                                                                                                                      |
| `defender_cores`              | CPU cores Microsoft Defender used over the last 10 s window; `None` until one is measured, and always `None` on a host without Defender.                                                                                                                                                          |
| `defender_warned`             | True once the capture has logged that Defender is slowing it (at 1 core or more). Exclude the backend from Defender scanning — see [Step 1](#step-1--install-the-chloros-platform-package).                                                                                                       |

```python
run = arr.continuous("captures/run1", processing="raw", max_captures=5000)
try:
    while True:
        st = run.wait(timeout=5)              # returns every 5 s while running
        print(f"{st['captures']} captures, {st['captures_per_s']:.1f}/s, "
              f"{st['skipped_groups']} skipped")
        if not st["running"]:
            break
finally:
    final = run.stop()                        # no-op once it has ended
if final["failed_files"] or final["stop_reason"] in ("disk_full", "error"):
    raise SystemExit(f"continuous capture: {final['stop_reason']}: "
                     f"{final['last_error']}")
```

### Live Frames in Your Own Pipeline

To feed synchronized frames into your own code — machine learning, a custom viewer, your own recorder — use `ArraySession.frame_stream()`. Each tick yields a `GrabResult`: `{serial: numpy array}` for every camera, **all from one trigger**, with that trigger's id on `.group_id`. It is the same implementation as the project API's `ArrayHandle.frame_stream()`, so everything under [One trigger per read](#one-trigger-per-read--group_id), [`band`](#exporting-a-single-band--band), [`align`](#aligning-the-streams--align) and [`bit_depth`](#bit_depth--trading-precision-for-bandwidth) applies to both.

```python
import chloros_sdk
from chloros_sdk import FrameFetchError

serials = ["213800234", "214000533", "214701288", "214701292"]   # master first

with chloros_sdk.connect_array(serials) as arr:
    try:
        for frames in arr.frame_stream(processing="raw", fps=10, duration=300,
                                       with_metadata=True):
            if not frames:              # no camera answered this tick
                continue
            if frames.errors:           # cameras missing from this trigger
                print("left out:", {s: str(e) for s, e in frames.errors.items()})
            for serial, (img, hdr) in frames.items():
                # img: numpy array (raw: one Bayer or mono plane)
                # hdr: group_id, frame_id, timestamp_ns, exposure_us, gain_db, ...
                my_pipeline(frames.group_id, serial, img, hdr["timestamp_ns"])
    except FrameFetchError as exc:      # the stream cannot continue
        print("stream ended:", exc.status, exc)
```

* **Every yielded set is a new trigger.** `frames.group_id` never repeats within a stream; when you ask for more `fps` than the array runs at, the stream waits for the next trigger, so it runs at the slower of the two.
* **Missing cameras are named, not back-filled.** A camera that could not be served at that trigger is absent from the dict and listed in `frames.errors`.
* **It ends loudly.** `FrameFetchError` on a refusal the next tick would repeat, after 60 s with no frame, or after 60 s with no new trigger.

**What it delivers.** `frame_stream()` moves whole numpy frames over the local HTTP connection and tops out near **170 MB/s**. That is enough for live processing of raw frames, or of a binned or ROI array, but not for every trigger at full resolution — to keep **every** trigger, save to disk with [`continuous()`](#continuoushandle). Measured on a four-camera array (FOCN, FRGN, FRGB, F450) with packed transport; every tick was a complete one-trigger set:

|                                        | Full sensor (array 14.2–14.4 fps)             | 2 × 2 binning (array \~33 fps)                     |
| -------------------------------------- | --------------------------------------------- | -------------------------------------------------- |
| `frame_stream(processing="raw")`       | 6.7 sets/s                                    | 22.2 sets/s                                        |
| `frame_stream(processing="debayered")` | 2.3 sets/s                                    | 9.3 sets/s                                         |
| `frame_stream(processing="display")`   | 0.8 sets/s                                    | 3.0 sets/s                                         |
| Per-camera MJPEG, 4 streams at 720p    | 13.5 fps each; every frame matched by trigger | \~25 fps each; \~45 % of triggers present on all 4 |

Use `processing="raw"` for throughput and demosaic on your side; the `debayered` level also takes the calibration pack's dark offset off, which a demosaic of `raw` does not.

#### Per-camera MJPEG streams (no RTSP)

**RTSP is not supported.** The streaming interface is MJPEG over HTTP (`multipart/x-mixed-replace`, one JPEG per part, each part with a `Content-Length`), one URL per camera:

| URL                                           | What it serves                                                                                                                                                |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/camera/stream/<serial>`             | 8-bit preview, up to \~30 fps. For an array member, `max_h` (default 720, 64–2160) and `jpeg_q` (default 80) set the size and quality.                        |
| `GET /api/camera/<serial>/stream-annotated`   | The same preview with the GUI overlays drawn on it (zebra, grid, crosshair, histogram, peaking, spot meter). `ChlorosLocal.camera_stream()` reads it for you. |
| `GET /api/camera/<serial>/stream-reflectance` | 8-bit per-band reflectance — see [Live reflectance stream](#live-reflectance-stream-mjpeg).                                                                   |

* **Trigger headers.** For an array member, every part of all three streams carries `X-Chloros-Group-Id`, `X-Chloros-Frame-Id` and `X-Chloros-Timestamp-Ns`. Parts from different cameras with the same `X-Chloros-Group-Id` are the same trigger: collect parts and group on that header to reassemble a set. A standalone camera has no group: its preview parts carry none of these headers (its reflectance parts carry an empty `X-Chloros-Group-Id`).
* **The preview stream drops frames under load.** It serves the newest frame and skips any it could not send in time, so at high array rates not every trigger reaches every camera's stream (see the table above). For every trigger, use `frame_stream()` or `continuous()`.
* **`/api/camera/stream/<serial>` pauses while the array's combined live stream is open** (`/api/camera/array/stream/<array_id>` — the GUI's array view opens it). Each member's stream then sends one "Paused (array stream active)" placeholder frame, with no `X-Chloros-*` headers, and nothing more until the combined stream closes; it then resumes by itself. `stream-annotated` and `stream-reflectance` do not pause. Close the GUI's array view when a script reads the per-camera preview streams.
* **For numbers, not pictures, use `frame_stream()`.** JPEG is lossy and 8-bit; `frame_stream()` returns the same products with no codec in the path.

### Interval Capture for Drone Surveys

A survey flight needs one synced image group every few metres of travel, not every frame the array can produce. Two settings control this: **`target_fps`** sets how often the cameras take a frame, and **`capture_repeated(interval_s=…)`** sets how often a frame is saved.

**The cameras keep streaming between saves.** Each interval saves the newest synced group; the frames in between are not written. Auto-exposure adjusts on every frame, so exposure has already settled when the save happens. There is no mode in which the cameras stop between shots and are woken for each one: every shot would then have to wait for the stream to start and exposure to settle.

**Pin the frame rate to what the interval needs.** Left on auto, an array runs at the highest rate the host and network carry. Pinning it lower cuts camera heat, network load and host CPU without changing what is saved. Pick a rate that gives **2–4 frames per interval**:

* Each save waits for the next frame after it is requested, so a saved group lands up to one frame period after its scheduled moment. A higher rate keeps that gap small.
* Auto-exposure adjusts once per frame, so a very low rate slows how quickly exposure follows a passing cloud.

**Work the interval out from the flight plan:**

```
spacing    = along-track footprint × (1 − forward overlap)
interval_s = spacing / ground speed
```

For example, a 60 m footprint at 80 % forward overlap is a 12 m spacing; at 10 m/s that is `interval_s=1.2`, and a pinned `target_fps=3` gives between 3 and 4 frames per interval. Capture is time-based: the SDK has no distance- or GPS-triggered mode, so hold a steady ground speed on survey lines.

**Save raw on the aircraft and calibrate later.** `interval_s` is measured from the start of each save, so a save that takes longer than the interval makes the next one start late and the spacing drifts. Saving raw plus the light-sensor reading (`processing="raw"`; the reading is saved by default) keeps each save short and keeps every frame convertible to reflectance afterwards.

```python
import chloros_sdk

INTERVAL_S = 1.2      # from the flight plan
FLIGHT_S = 20 * 60    # bounds the loop; it also stops at count= if given

with chloros_sdk.connect_array(serials, target_fps=3.0) as arr:
    groups = arr.capture_repeated(
        "survey/", interval_s=INTERVAL_S, duration_s=FLIGHT_S,
        processing="raw", render_index=False,
        on_capture=lambda i, r: print(f"group {i}: {len(r)} frames"))
```

* **`connect_array(target_fps=…)`** pins the rate from the start; **`arr.set_target_fps(fps)`** changes it mid-flight without reconnecting, and **`arr.set_target_fps(None)`** returns it to auto. A rate above what the host and network can carry is lowered to that ceiling — check `clamped` in the result — and the lowest rate is 0.1 fps.
* **Don't use `burst()` to thin frames.** It writes every frame the array produces; it does follow a pinned `target_fps`, so it is the right tool only when every frame is wanted.
* **`target_fps` does not fix corrupt frames.** Lowering it reduces how many frames are produced, not how fast each one is sent; for GVSP-corrupt frames lower `wire_ceiling_mbps` instead (see [Array Health](#array-health--which-subsystem-is-losing-frames)).

```python
r = arr.set_target_fps(5.0)
if r["clamped"]:
    print(f"asked for {r['requested']} fps, running at {r['target_fps']}")
```

### Attaching to an Already-Connected Array — `attach_array`

If the array is already up (the GUI opened it, or a previous SDK session called `connect_array`), use `attach_array` to grab a handle to it instead of re-connecting. `connect_array` always errors with `Camera <sn> is already in array <id>` in that situation, because POSTing `/array/connect` for a member-in-pool is not idempotent; `attach_array` reads `/api/camera/array/list` and matches by either array\_id or serials.

```python
import chloros_sdk

# By serials (matches if every serial is a member of one existing array)
arr = chloros_sdk.attach_array(
    ["213800234", "214000533", "214701288", "214701292"])

# By array_id (when you've already noted it down)
arr = chloros_sdk.attach_array("array-1779862544497")

# attach_array returns the same ArraySession as connect_array
arr.capture("output/", processing="reflectance")
```

Pattern: SDK scripts that co-tenant with the desktop GUI should try `attach_array` first and fall back to `connect_array` if no array is in the pool yet.

```python
import chloros_sdk

try:
    arr = chloros_sdk.attach_array(serials)
except chloros_sdk.ChlorosConnectError:
    arr = chloros_sdk.connect_array(serials)
```

> **An attached array is borrowed, not owned.** A handle from `attach_array` never tears the array down: neither the `with` block's exit nor an explicit `disconnect()` releases it (the explicit call prints one line to stderr saying it left the array running). Same rule as `CameraSession` / `DAQSensorSession`. So co-tenanting with the GUI is safe with or without `with`:
>
> ```python
> with chloros_sdk.attach_array(serials) as arr:
>     arr.capture("output/", processing="reflectance")
> # … the array stays up for the GUI
> ```
>
> When you do mean to end it — to reconnect with a different `wire_ceiling_mbps`, say — call `arr.force_disconnect()`. Reconnecting after a plain `disconnect()` on an attached handle fails with `Camera <sn> is already in array <id>`, because nothing was released.

### Network-Analysis Helper

Useful before opening the array — projects whether your proposed settings will fit:

```python
result = chloros_sdk.analyze_array_network(
    master_serial="214701288",
    slave_serials=["213800234", "214000533", "214701162"],
    width=2048, height=1536,
    pixel_format="BayerRG12",
    binning=1,
)

if result["status"] == "ok":
    print("Use the requested settings.")
elif result["status"] == "auto_capped_fps":
    r = result["recommended"]
    print(f"Keep the resolution; cap the trigger rate at {r['recommended_target_fps']} fps")
elif result["status"] == "auto_shrunk":
    r = result["recommended"]
    # width / height are sensor pixels BEFORE binning (what connect_array
    # takes with binning=); out_width / out_height is what is streamed.
    print(f"Connect with width={r['width']} height={r['height']} "
          f"binning={r['binning']} ({r['out_width']}x{r['out_height']} streamed)")
elif result["status"] == "needs_force_slip":
    print("Sim-sync impossible on this wire; force_tier='slip-emit-and-capture' required")
```

```python
analyze_array_network(
    master_serial,
    slave_serials=None,
    width=2048, height=1536,              # sensor pixels before binning
    pixel_format=None,                    # None = what connect applies (Mono12 / BayerRG12)
    binning=1,                            # 1 | 2 | 4
    force_tier=None,
    packed="auto",                        # "auto" | "on" | "off"
    backend_url="http://127.0.0.1:5000",
    timeout=30.0,
) -> dict
```

It never starts a backend: one that does not answer raises `ChlorosConnectError`, while a refused request comes back as a result. A bad `packed` raises `ValueError`.

`status` is one of `ok` / `auto_capped_fps` / `auto_shrunk` / `needs_force_slip` (else `error` — including a refused request: not logged in, `error_code: AUTH_REQUIRED`, or a plan below the SDK floor, `PLAN_UPGRADE_REQUIRED`). `auto_capped_fps` means the requested resolution fits the RX ring only at a capped trigger rate — keep the resolution and pass `target_fps=result["recommended"]["recommended_target_fps"]` to `connect_array` (see [Example 6](#6-capability-probe-before-connecting-a-4-cam-array)). `auto_shrunk` appears only when the requested frame cannot be delivered at any frame rate; connect never shrinks frames on its own, so apply `recommended` yourself.

**How to read the projection** (same model as the GUI Array Settings panel):

* **Burst (`frame_bytes_total`) is summed per-camera at each cam's real pixel format.** Mono **M3M** cams stream Mono12 (2 B/px), or with a `pixel_format` the Mono format of its depth (`"BayerRG8"` is `Mono8`, 1 B/px), so with none a 4-cam full-res frame is **\~25 MB** with three mono cams, not the \~12.6 MB an all-8-bit assumption gives. The backend resolves each cam's format from its model.
* **Admittance (`burst_fits_nic_ring`) is drain-aware**, not whole-burst-vs-ring: sim-emit fits when the host drains the RX ring faster than the cams fill it. A 10G host + 1 GbE cams **admits** full-res even when the burst exceeds the ring; a 1 GbE host blocks (`needs_force_slip` / `auto_shrunk`).
* **`achievable_fps_max` is a conservative serial-retrieve ceiling** — `max(readout+emit, N×emit)` with per-cam emit clamped to the 1 GbE camera link, exposure-independent. E.g. \~2.8 fps for a 4-cam full-res 12-bit array (matches the runtime's measured \~2.7–3.0). Full model: [CLI Reference → Array fps & burst model](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#array-fps--burst-model).
* **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, `connect_array()`'s analysis and the Array Settings panel quote that rate when it is below the model's, with what limited it in `cycle_limiter`: `"clock"` (the array ran at the rate it settled on, the grab loop waiting on its trigger clock), `"loop"` (the grab loop had no time left), `"capture"` (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.
* **Over-subscription (`oversubscribed: true`) means the wire cannot carry the array at any pacing the cameras reach** — the fps fields (`achievable_fps_max` / `fps_bright` / `fps_dark`) read 0, and binning cannot fix it (it lowers bytes per frame, not paced bytes per second). A slow wire alone does not do this: the frame rate falls instead, and if the cameras cannot be paced slowly enough the tier becomes `slip-emit-and-capture` (serial). Remedies are fewer cams, jumbo frames, or a faster NIC; `max_cams_collision_safe` reports the ceiling for your wire and cameras. The response also carries `aggregate_demand_bps`, `collision_safe_ceiling_bps`, and `per_cam_floor_bps`. See [Over-Subscription](#over-subscription-the-per-cam-floor).

### Discovery & Listing

```python
chloros_sdk.discover_lattice_cameras()   # list all cams visible to the backend
chloros_sdk.list_cameras()               # cams currently in the pool
chloros_sdk.list_arrays()                # active arrays in the pool
```

Each takes keyword-only `backend_url=` and `timeout=30.0`, and returns a list of dicts. `discover_lattice_cameras()` (`serial`, `ip`, `mac`, `model`, `lattice_model`, `vendor`, `connected`, `array_id`, …) also takes `auto_start_backend=True`; the `list_*` calls never start a backend.

***

## 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. **Smart-capture** is the packaged convenience: it polls each cam's exposure, waits until the array is stable across a window, then triggers the capture. It is GUI-equivalent: the desktop app's "smart" capture button calls the same backend endpoint.

```python
import chloros_sdk

with chloros_sdk.connect_array([
        "213800234", "214000533", "214701288", "214701292"]) as arr:
    # Initial pose
    arr.capture("pose_a/", processing="reflectance", smart=True)
    input("Move the rig, then press Enter...")
    # New pose — smart-capture waits for AE to re-settle automatically
    arr.capture("pose_b/", processing="reflectance", smart=True)
```

When driving via `ChlorosProject` (next section) you get more knobs:

```python
proj.arrays["main_rig"].capture_smart(
    output_dir="out/",
    processing="reflectance",
    settle_timeout_s=5.0,           # max wait
    stability_window_s=1.5,         # exposure must hold steady this long
    exposure_tolerance_pct=5.0,     # %-spread allowed within the window
)
```

The smart-AE policy is conservative by default. Tighten `exposure_tolerance_pct` for picky radiometric work; widen for fast-changing scenes where you just want "close enough."

***

## DAQ Sensor Sessions

Persistent backend pool for spectral sensors (DAQ-U over USB, DAQ-M over BLE, DAQ-E over Ethernet). Mirrors the camera surface: smart-detect, pool reuse, idempotent attach.

### Smart-Detect (Zero-Config)

```python
import chloros_sdk

with chloros_sdk.connect_daq_sensor() as daq:
    print(daq.model, daq.transport, daq.address)
    for frame in daq.latest(n=10):
        spectrum = frame["spectrum"]   # list[float] (W/m²/nm if calibrated)
        is_sat = frame["is_saturated"]
        x, y, z = frame["x"], frame["y"], frame["z"]
        print(len(spectrum), is_sat)
```

Precedence: Ethernet → BLE → USB. Pass any one explicit hint to pin the transport.

### Pinned Transport

```python
# DAQ-U on a specific serial port
daq = chloros_sdk.connect_daq_sensor(transport="usb", port="COM3")

# DAQ-M over BLE by MAC (implies transport="ble")
daq = chloros_sdk.connect_daq_sensor(mac="AA:BB:CC:DD:EE:FF")

# DAQ-E over Ethernet by hostname (implies transport="eth")
daq = chloros_sdk.connect_daq_sensor(eth_host="daq-e-xxx.local")

# A specific sensor by id (as list_daq_sensors() shows it; ':' or '-' alike)
daq = chloros_sdk.connect_daq_sensor(sensor_id="CB-7C-A7-5A-73")

# Tuning knobs
daq = chloros_sdk.connect_daq_sensor(
    port="COM3",
    integration_time=64,      # ms
    frame_avg=20,
    enable_ae=True,
    start_streaming=True,
)
```

`sensor_id=` names one sensor, and only that sensor is ever opened. It is matched against the sensors already open, then a DAQ-E's hostname or IP (a DAQ-E the network scan sees only by IP is asked, read-only, for its name, MAC and serial, so any of those finds it too), a DAQ-M's BLE MAC, and the id a DAQ-U or DAQ-M reports once opened (any other one opened to check is closed again). If it is not found, `connect_daq_sensor` raises `ChlorosConnectError` listing what was found; with an address as well (`port=` / `mac=` / `eth_host=`) that holds a different sensor, it raises too. It never falls back to whichever sensor is visible — that is what the zero-flag call is for.

### `connect_daq_sensor()` Signature

```python
connect_daq_sensor(
    *,                                    # every argument is keyword-only
    sensor_id=None,                       # one named sensor (see above)
    transport=None,                       # "usb" | "ble" | "eth"; None = smart-detect
    port=None,                            # DAQ-U serial port ("COM3", "/dev/ttyUSB0")
    mac=None,                             # DAQ-M BLE MAC (implies transport="ble")
    eth_host=None,                        # DAQ-E hostname or IP (implies transport="eth")
    integration_time=None,                # ms; None = the sensor's own
    frame_avg=None,
    enable_ae=None,
    cap_id=None,                          # cap correction: "sunshine_cosine", "fov_30", ..., "none" (bare)
    start_streaming=True,
    backend_url="http://127.0.0.1:5000",
    timeout=60.0,
    auto_start_backend=True,              # spawn a local backend if none is running
) -> DAQSensorSession
```

A sensor that is already in the pool is returned as it is (borrowed): `integration_time`, `frame_avg` and `enable_ae` are not applied to it. Disconnect it first to open it with your settings. `cap_id` is the exception: on a borrowed sensor it is set with `set_cap()`. Left out, the backend's default stands (see the note under the methods table).

### `DAQSensorSession` Methods

| Method                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status(timeout=10.0)`                                                                                           | Pool entry summary (streaming/recording state, wavelength range, calibration sha, integration time, frame\_avg, AE state). For a DAQ-E whose stream went silent: `reconnect` (where the backend's automatic reconnect stands: `state`, `attempts`, `next_attempt_in_s`, `last_error`; `None` while it streams), `stream_lost_s`, `reconnects` and `last_reconnect`, and `record_gaps` for the recording in progress; `rx_stream_fault` says the reconnect state until the first spectrum arrives.                                                                                                                                                                                                                          |
| `latest(*, n=1, timeout=10.0)`                                                                                   | Return up to N most-recent spectrum frames (each `ts_ns`, `spectrum`, `is_saturated`, `integration_time`, `x`, `y`, `z`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `stream_start()` / `stream_stop()`                                                                               | Resume / pause streaming (handle stays open).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `record_start(*, output_dir=None, device_name=None, timeout=15.0)`                                               | Start recording a .daq file. Returns the filepath. Refuses for DAQ-U/M without an AWS calibration bundle (DAQ-E is exempt).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `record_stop()`                                                                                                  | Stop recording. Returns `{path, rows, warning, gaps}`; `warning` is `None` for a clean recording, otherwise the backend's diagnosis (for example an empty file or a gap in the stream), which is also printed to stderr. `gaps` lists each stretch the stream delivered nothing: `start_utc`, `end_utc` (`None`: still lost at the stop), `duration_s`, `reconnected`, `marked_in_file`. It is empty for a continuous recording.                                                                                                                                                                                                                                                                                           |
| `set_cap(cap_id, timeout=15.0)`                                                                                  | Set the cap-correction profile applied to the readings from the next one on: `"sunshine_cosine"`, `"fov_15"` ... `"fov_90"`, or `"none"` (or `None`) for a bare sensor. Returns the sensor's summary, whose `cap_id` reads it back. A DAQ-E-S keeps `as_recorded` whatever is asked (its diffuser is built in). Raises `ChlorosConnectError` for a profile that does not load. CLI: `chloros-cli daq pool-set-cap`.                                                                                                                                                                                                                                                                                                        |
| `enable_ptp(timeout=15.0)`                                                                                       | DAQ-E only: switch PTP back on for a unit whose PTP is off (`status()["rx_ptp_enabled"]` is `False`; the setting is saved on the unit, so it stays off until switched back on). Returns the refreshed status. Raises `ChlorosConnectError` for a DAQ-U / DAQ-M, or when the unit does not confirm. Chloros never switches a unit back on by itself, because off can be deliberate. CLI: `chloros-cli daq pool-enable-ptp`.                                                                                                                                                                                                                                                                                                 |
| `device_info(timeout=15.0)`                                                                                      | DAQ-E only: the unit's own settings. `firmware` (`running`, `bundled`, `update_available`), `ip` and `ip_mode` (`dhcp` / `linklocal` / `static`: what it runs now), `network` (the saved setting: `mode`, plus `ip` / `mask` / `gateway` when static), `network_change_pending` (true until the unit runs the saved setting, one saved with `set_network(..., reboot=False)` included), `auto_stream`, `ptp`. `firmware["update_available"]` is `None` when the unit's version could not be read. While the unit's stream is not reaching this computer it is read on a fresh connection and the dict adds `stream_silent` (`True`), `stream_fault` and `reconnect`; a unit that does not answer raises. CLI: `pool-info`. |
| `set_network(mode="auto", *, ip=None, mask=None, gateway=None, reboot=True, force=False, comeback_timeout=45.0)` | DAQ-E only: DHCP (`"auto"`) or a static address. Restarts the unit to apply it and reconnects it; this session keeps working and `address` follows the unit. `reboot=False` only saves it. See [DAQ-E Device Settings](#daq-e-device-settings). CLI: `pool-set-network`.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `set_auto_stream(enabled, timeout=15.0)`                                                                         | DAQ-E only: stream at power-on with no software connected (saved on the unit). Returns the confirmed setting. CLI: `pool-set-auto-stream`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `reboot(*, comeback_timeout=45.0)`                                                                               | DAQ-E only: restart the unit and reconnect it with the settings it had. CLI: `pool-reboot`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `update_firmware(*, comeback_timeout=45.0)`                                                                      | DAQ-E only: flash the firmware included with this Chloros release onto a unit running an older version, then reconnect it (about a minute; do not power it off). Returns `updated`, `fw_before`, `fw_after`, `bundled`, and a `warning` when the unit was slow to come back or came back on another version; `updated` is `False` for a unit already current. Raises `ChlorosConnectError` for a unit whose version cannot be read. CLI: `pool-update-firmware`.                                                                                                                                                                                                                                                           |
| `disconnect()`                                                                                                   | Release from the pool. No-op for attached-not-owned handles. On a sensor this session opened it is `force_disconnect()`, and raises `ChlorosConnectError` when the release is not confirmed (the `with` block's exit never raises).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `force_disconnect(timeout=30.0)`                                                                                 | Release the sensor regardless of who opened it — for example a sensor a crashed script left in the pool, which a new script reaches only as an attached handle whose `disconnect()` does nothing. Ending another client's sensor finishes any recording it is making. Returns once the backend confirms the release, or when there is nothing to release (the sensor is not in the pool, or no backend is running); a release that timed out or that the backend refused raises `ChlorosConnectError`. CLI: `chloros-cli daq pool-disconnect --sensor-id ID`.                                                                                                                                                              |

Attributes: `sensor_id`, `model`, `transport`, `address` (follows a DAQ-E that `set_network()` readdressed), `info` and `backend_url`.

> **Name the cap.** DAQ-U, DAQ-M and DAQ-E ship with no cap, and Chloros cannot see whether one is fitted: a sensor connected without `cap_id` gets `sunshine_cosine`, an assumption its recordings say they made (`cap_id_source=auto_default`). A bare DAQ-U under that correction reads about 30x high, so pass `cap_id="none"` for a bare sensor (or `set_cap("none")`), and the profile of the cap you fitted otherwise.

### 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.                                                                                          |

`DAQSensorSession.latest()` returns them under each frame's `imu` key (`None` 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 reports on its own fields in `status()` (`rx_imu_stream_fault`, `rx_imu_stream_faults`, `rx_last_imu_stream_fault`), kept apart from the spectral ones so an accelerometer outage is never read as a gap in the recording. `discover_daq_sensors()` and the session's `model` say `DAQ-E-S`.

### DAQ-E Device Settings

```python
with chloros_sdk.connect_daq_sensor(eth_host="daq-e-def330.local") as daq:
    info = daq.device_info()
    print(info["ip"], info["ip_mode"], info["firmware"])

    # A fixed address on the network this computer is on
    daq.set_network("static", ip="192.168.1.50", gateway="192.168.1.1")
    print(daq.address)              # 192.168.1.50: the session follows it

    if info["firmware"]["update_available"]:
        daq.update_firmware()
```

* **A static address must be on this computer's network.** `set_network` raises `ChlorosConnectError` for 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=True` only when this computer will be readdressed, or routed, to the new subnet.
* **`set_network`, `reboot` and `update_firmware` restart the sensor**, and raise `ChlorosConnectError` while it records, and when it does not come back within `comeback_timeout` seconds. The sensor ID and the `daq-e-<id>.local` hostname never change.
* **A recording started just before the restart is closed by it, and named.** When the sensor comes back, the returned dict carries `recording_closed` (the file's path) and a `warning` saying so. When it does not come back, or the firmware transfer fails, the `ChlorosConnectError` says so instead: its message ends with the warning, and `e.recording_closed` / `e.warning` are set (both `None` when no recording was closed). Start the recording again once the sensor is back.
* **Only the sensor itself is reconnected.** After the restart the unit must answer where it was -- and after `set_network("auto")` also under its `.local` name -- with its name, hostname and model, from the network adapter (MAC) it had; `address` becomes the IP that answered. An answer under the name counts only with that MAC, so from a computer that reaches the sensor through a router, or from WSL2's default NAT networking, a sensor that DHCP moved is not reconnected (`ChlorosConnectError`; connect it again at its new address).
* **A firmware update needs the sensor to connect back.** `update_firmware()` invites the unit, and the unit opens a TCP connection back to this computer for the image, on a port the OS picks. The backend listens on the adapter that reaches the unit (on every adapter only when it cannot tell which) and serves only that unit: any other connection is refused (`[DAQ-FW] … refused a firmware connection from <ip>` in the backend's output) while it keeps waiting. A firewall that blocks the connection fails the update with `device never connected back on TCP <port>`. The Windows installer adds the rule for it (see [Step 1](#windows-exe)); on another firewall, allow inbound TCP to the backend from the sensor's subnet.
* **Under WSL2, use mirrored networking** (`networkingMode=mirrored` in `.wslconfig`): in the default NAT mode every static address is refused (WSL's own address is not on the sensor's network), the stream does not reach WSL, and a firmware update cannot complete.
* The GUI keeps its own connection to a sensor: a restart from a script ends the GUI's session with it. The GUI has the same settings (Light Sensors tab, the sensor's settings, Network).

### Discovery — finding an address to connect with

`discover_daq_sensors()` scans USB / BLE / ETH for sensors you *could* open. It is the DAQ counterpart to `discover_lattice_cameras()`, and the only way to obtain a **DAQ-M's BLE MAC** — a DAQ-E has a hostname and a DAQ-U a COM port, but a MAC is neither printed on the device nor listed by the OS.

```python
for s in chloros_sdk.discover_daq_sensors():
    print(s["transport"], s["address"], s["model"], s["extra"])
# ble  C3:D8:85:E0:0A:19  DAQ-M  {'name': 'NSP32_SPECTRUM'}
# usb  COM3               DAQ-U  {'vid': '0403', 'pid': '6001', 'manufacturer': 'FTDI'}

# `address` is exactly what connect_daq_sensor wants:
for s in chloros_sdk.discover_daq_sensors(transports=["ble"]):
    if s["model"] == "DAQ-M":
        daq = chloros_sdk.connect_daq_sensor(mac=s["address"])
```

| Field       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transport` | `usb` \| `ble` \| `eth`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `address`   | COM port / BLE MAC / hostname — pass to `connect_daq_sensor` as `port=` / `mac=` / `eth_host=`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `display`   | Human-readable label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `model`     | `DAQ-U` \| `DAQ-M` \| `DAQ-E` \| `DAQ-E-S`, or `None`. An Ethernet sensor is `DAQ-E-S` or `DAQ-E` as it reports itself when asked, read-only, during the scan (`DAQ-E` when it does not answer in time). A USB serial port reads `DAQ-U` when its bridge chip is one a DAQ-U uses (FTDI, CH340, CP210x, Prolific) — a hint from the port's description, not a probe — and `None` for any other USB device, which is still listed so you can pass it as `port=`. A serial port with no USB vendor id and no such bridge chip (a motherboard UART such as Linux's `/dev/ttyS*`, a Bluetooth serial link, Intel AMT) cannot be a DAQ-U and is not listed. |
| `extra`     | Per-transport details (BLE advertised name; USB `vid`, `pid`, `manufacturer`, `serial_number`; DAQ-E ip/fw/…). Empty values are omitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

| Parameter            | Default   | Description                                                                                                  |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `transports`         | all three | Sequence (or csv string) limiting the scan. Worth passing when you know what you want — BLE is the slow leg. |
| `scan_timeout`       | 5         | Per-transport scan window in seconds; the backend clamps to 1–20.                                            |
| `timeout`            | 60.0      | HTTP ceiling for the whole call (as elsewhere in the SDK).                                                   |
| `auto_start_backend` | `True`    | Spawn a local backend if none is running. Never spawns for a remote `backend_url`.                           |

> **Sensors already open in the pool do not appear.** A connected BLE peripheral stops advertising and an open COM port can't be probed, so discovery lists what is *available to connect*. An empty result right after you connected something is expected — use `list_daq_sensors()` for what you already hold. Transports whose scan can't run (no bleak / zeroconf installed) are skipped rather than raising, so a machine without Bluetooth still gets its USB and ETH answers.

### Listing

```python
for s in chloros_sdk.list_daq_sensors():
    print(s["sensor_id"], s["model"], s["transport"], s["wavelength_range"])
```

### Which DAQ Feeds Which Camera — `daq_bindings()`

A capture's reflectance, and the `.daq` it saves, use the DAQ bound to that camera or array, else the freshest DAQ the backend has. The GUI's light-sensor selection and `chloros-cli daq pool-bind` set it; so does:

```python
chloros_sdk.set_daq_bindings(cameras={"214701281": "COM7"},          # a sensor id or an address
                             arrays={"array-1779862544497": "daq-e-def330"})
chloros_sdk.set_daq_bindings(cameras={"214701281": None})            # None clears it
for serial, b in chloros_sdk.daq_bindings()["cameras"].items():
    print(serial, b["binding"], b["source"], b["resolved"]["in_pool"])
```

`daq_bindings()` returns `{"cameras": {serial: b}, "arrays": {array_id: b}}`: each `b` holds `binding` (the value set), `source` (`project`, from the project's `sensors.json`, or `runtime`), `known` / `known_as` (whether the camera or array key names one Chloros knows, and how: `connected`, `project` — the open project's `cameras.json` — or, for a camera, `seen`: opened on this computer before; `known: False` for a key that names nothing) and `resolved` (the pool sensor it maps to now: `in_pool`, `sensor_id`, `address`, `model`, `streaming`). A runtime binding beats the project's for the session; the project file is not changed. Disconnecting a camera, an array or a DAQ drops every binding of that hardware, whoever set it (an array's members' with the array's).

`set_daq_bindings()` binds only a camera that is connected, in the open project or opened on this computer before, and an array that is connected or in the open project (or a key already bound). Any other key raises `ChlorosConnectError` naming it (`400`, `code` `UNKNOWN_BINDING_TARGET`, with the `unknown` keys), and **nothing** in that call is bound. `None` clears any key.

### Ambient + Object Reflectance — `light_sensor_reflectance()`

Two pooled DAQs, one looking up at the sky (ambient) and one down at the target (object), give the target's reflectance and vegetation indices from their latest readings: the GUI's Ambient + Object pair, and `chloros-cli daq reflectance` without opening the sensors a second time. Both must be connected and streaming.

```python
r = chloros_sdk.light_sensor_reflectance("daq-e-def330", "daq-e-54b774")
print(r["reflectance_type"])                       # "Apparent Reflectance" when both are calibrated
for name, band in r["bands"].items():
    print(name, band["rho"] if band["valid"] else band["reason"])
for idx in r["indices"]:
    print(idx["name"], idx["value"])
```

```python
light_sensor_reflectance(
    ambient_sensor_id, object_sensor_id, *,
    bands=None,          # [{"name", "center_nm", "fwhm_nm", "role"}]; role blue / green / red / nir
    preset=None,         # a preset id from daq_band_presets(); default: the suggested one, else "GENERIC"
    expressions=None,    # custom indices: [{"name": "MyNDVI", "expr": "(NIR_850 - Red_660) / (NIR_850 + Red_660)"}]
    builtins=True,       # include the built-in indices
    backend_url="http://127.0.0.1:5000", timeout=30.0,
) -> dict
```

* **Bands.** Each band's reflectance is the object's band-integrated irradiance over the ambient's. `daq_band_presets(filter_code=None)` lists the band sets: one per LATTICE M3C filter (`RGN`, `OCN`, `NGB`, the camera's own band model, so a DAQ NDVI and a camera NDVI are the same quantity) and `GENERIC` broadband. Its `suggested` is the preset matching `filter_code`, else the first connected camera's filter (`suggested_from` says which).
* **Returns** `bands` (per band `rho`, `valid`, `reason`, `e_ambient`, `e_object`), `indices` (the built-ins), `custom` (each with `value`, or `valid: False` and the `error`), `invalid_bands`, `reflectance_type`, `preset` and the two readings' `timestamps` (`ts_ns`). A band the ambient sensor could not measure (outside its range, at its noise floor) is invalid, with the reason, and every index that needs it is left out, never computed against zero.
* **Apparent or relative.** The scale-dependent indices (SAVI, OSAVI, EVI, MSAVI2, RDVI, TDVI, LAI, NLI, MNLI, FCI, GEMI) need an absolute ratio, so they come only when both sensors are power-calibrated (each has a `calibration_bundle_sha`): `"Apparent Reflectance"`. Otherwise the result is `"Relative Reflectance"`, with the scale-invariant indices only.
* **Two different wavelength grids** are compared on their overlap: the ambient sensor's points inside the object's range, the object's spectrum interpolated onto them.
* **Two sensors, never one.** Naming one sensor as both (the same id, in any spelling the pool accepts) raises `ChlorosConnectError`: a sensor's reading over itself is 1.0 on every band, which measures nothing. The backend refuses it too (`POST /api/daq/indices` answers `400`, `code` `SAME_SENSOR`, when the `ambient_sensor_id` and `object_sensor_id` the SDK sends are one pooled sensor, e.g. its id and its port).

### Co-Tenancy with the CLI and Other Scripts

The backend's DAQ sensor pool is shared by every CLI and SDK client on the machine. If a sensor is already in the pool — opened by `chloros-cli daq pool-connect` or by another script — calling `connect_daq_sensor(port="COM3")` from Python returns a borrowed handle: its `disconnect()` is a no-op, so your script doesn't tear the sensor out from under the client that opened it on scope exit. The same holds for `sensor_id=` (typed with `:` or `-`, either matches), for a DAQ-E named by its IP when it was opened by hostname (or the other way round), and for the zero-flag smart-detect when the backend answers with a sensor it already held — a `with` block only ever releases a sensor it opened itself.

The Chloros GUI is **not** part of this pool: its DAQ panel runs its own connection to the sensor, so `connect_daq_sensor` never borrows a sensor the GUI has open. Do not use the same sensor from the GUI and from a script at the same time. A DAQ-U or DAQ-M the GUI holds normally just fails to open, but a DAQ-E accepts a second session: the script's connect changes the unit's acquisition settings under the GUI, and its `disconnect()` stops the unit's stream, which ends the GUI's live view and any recording it is making. Close the sensor in the GUI first.

### PTP Grandmaster — `time_sync_status()`

The backend runs the PTP grandmaster that LATTICE cameras and DAQ-E units take their timestamps from. It starts on demand: `connect_camera()`, `connect_array()`, `connect_daq_sensor()` and `connect_all()` start it if it is not running — including a connect that then fails, such as `connect_all()` trying a DAQ-E that is not there — and so do `test_array_sync()` and every call that opens cameras for one command (`capture_cameras_transient()`, `start_multi_camera_stream()`, the alignment calls, `capture_live_index()`).

* **Where it announces.** On the wired network adapters that face the cameras (a `169.254.x.x` link-local address included), else on the adapter of the default route if that one is wired. Never on Wi-Fi or a virtual adapter (Tailscale, WSL): no camera or DAQ-E is behind one. With no such adapter up, it runs announcing on nothing (`health` `NO_SOCKETS`) and binds the adapter the next camera or DAQ connect brings up.
* **After a link drop.** When the camera adapter loses its link and gets it back (a cable pull, a switch replaced, a USB adapter re-enumerated), the grandmaster rebuilds its sockets by itself, with no restart, and re-checks every connected DAQ-E, re-arming one the gap left stuck. It also rebuilds when every camera and DAQ-E it was serving goes quiet for 15 s.
* **Is it reaching the wire?** Read `time_sync_status()` (`GET /api/time-sync/status`). `state` only says the grandmaster thread runs; `health` says whether its packets leave: `OK` (no fault seen), `STOPPED`, `NO_SOCKETS`, `SENDS_FAILING`, `DEGRADED` (some adapters failing) or `PEERS_SILENT` (the cameras and DAQ-Es it was serving stopped answering), with a sentence in `health_detail`. `announce_sent` / `sync_sent` / `delay_resps_sent` count only messages that left; `announce_send_errors`, `sync_send_errors`, `follow_up_send_errors`, `delay_resp_send_errors`, `last_send_error`, `failing_interfaces` and `last_delay_req_age_s` describe the ones that did not, and `rebinds` / `last_rebind` the rebuilds. `sync_sends_slow` counts the Syncs whose send ran past 200 us and `sync_send_max_us` is the longest; each Follow\_Up's origin time counts at most 200 us of its send. The grandmaster runs in a process of its own (`own_process`, `process_pid`), at high priority on Windows (`process_priority`), so a busy backend cannot delay the times it stamps and move every camera's clock at once; if that process cannot be started it runs inside the backend as before (`own_process` false).

```python
st = chloros_sdk.time_sync_status()
if st.get("health") not in (None, "OK", "STOPPED"):
    print("PTP:", st["health"], "-", st.get("health_detail"))
    chloros_sdk.restart_time_sync()
```

| Function                                                 | What it does                                                                                                                                                                        |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time_sync_status()`                                     | The grandmaster's state, health, clock identity, priorities and message counters (above). `chloros-cli time-sync status`.                                                           |
| `time_sync_peers()`                                      | The PTP slaves it hears (cameras, DAQ-Es): `peers`, each `port_identity`, `last_seen_ip`, `last_delay_req_age_ms`, `delay_req_count`. `time-sync peers`.                            |
| `time_sync_cameras()`                                    | Each connected array camera's `PtpStatus`, `PtpOffsetFromMaster` and `PtpMeanPathDelay` (a camera whose firmware has no PTP nodes has its serial only). `time-sync cameras`.        |
| `restart_time_sync()`                                    | Stop and restart the grandmaster; every pooled DAQ-E's PTP is re-checked after (`daq_ptp_rechecked`). Raises `ChlorosConnectError` when it does not come back. `time-sync restart`. |
| `set_time_sync_priority(priority1=None, priority2=None)` | Its PTP priorities (0-255, lower wins the best-master election), for a network with another PTP master. Needs it running. `time-sync set-priority`.                                 |

Each takes `backend_url=` and `timeout=` and starts a local backend that is not running.

***

## Camera Utilities

What `chloros-cli lattice` does beyond connecting and capturing, as plain functions in `chloros_sdk` (module `chloros_sdk.camera_utils`). Each calls the backend route the CLI command uses, with the CLI's rules, so the two behave alike. They take a camera **serial**, not a session, and the same `backend_url=` / `timeout=` keywords as the smart-connect calls; a backend that is not running is started, as `connect_camera()` does. A refusal raises `ChlorosConnectError` with the backend's reason.

```python
import chloros_sdk as c

c.set_camera_color_profile("214701281", profile="natural")
c.set_camera_highlights("214701281", -40)
print(c.camera_firmware_status()["cameras"])
st = c.network_adapters(estimate=True, cameras=4, pixel_format="BayerRG12")
```

| Function                                                                                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `camera_color_profile(serial)` / `set_camera_color_profile(serial, profile=, custom_cct_k=)`           | The display colour profile: `raw`, `linear`, `natural`, `enhanced` or `custom_temp`, and its colour temperature (clamped to 2000-10000 K; read when the profile is `custom_temp`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `camera_color_adjust(serial)` / `set_camera_color_adjust(serial, saturation=, contrast=, reset=False)` | Display saturation and contrast, 0-200 % each (100 = unchanged); `reset=True` puts both back to 100.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `camera_highlights(serial)` / `set_camera_highlights(serial, value)`                                   | Pull the brightest, whitest pixels of the display render down: -100..0 (truncated toward zero, then clamped; 0 = off).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `camera_white_balance_once(serial, settle_s=None)`                                                     | One-shot white balance: the camera streams briefly, converges, and returns `red_ratio` / `blue_ratio` (`ratios_read` False when it cannot report them). It keeps the white balance it solved; every other setting its open wrote goes back as found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `set_camera_white_balance(serial, mode=None, red=None, blue=None)`                                     | `mode="auto"` (continuous) or `"off"`; or fixed `red` / `blue` balance ratios, which turn auto off first. A ratio the camera refuses is named under `errors`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `camera_presets()` / `apply_camera_preset(serial, preset)`                                             | The camera presets, and applying one: the camera keeps the settings the preset names (the reply's `settings`, as the camera reads them after, e.g. the frame rate it runs at; `None` for a field the preset does not name), and every other setting its open wrote goes back as found. `"default"` resets the camera to its factory defaults (its factory settings with free-running auto exposure, the link throughput limit and defect correction off, an RGB camera's calibrated white balance kept), not saved to its memory: the reply has `factory_defaults: True` and every field of `settings`. In `camera_presets()`, `default` is `{factory_defaults: True, description}`.                                                                                                                            |
| `camera_filter_models()` / `camera_filter_model_info(name)`                                            | The filter models, and one model's details (bands, spectral-response condition number). A camera's filter model is read from its model string; it is not set by hand.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `camera_firmware_status(serial=None)`                                                                  | Each camera's firmware: `current_version`, `available_version`, `update_offered`, `needs_minimum_update`, and `minimum_firmware`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `update_camera_firmware(serial, force=False)`                                                          | Flash this Chloros build's firmware onto one camera: factory reset, flash, reboot, the Chloros baseline settings re-written; the camera's calibration is kept. Several minutes; the camera must stay powered. `force=True` re-flashes a current camera.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `camera_power_probe(serial)`                                                                           | The camera's power and thermal nodes and its temperature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sleep_camera(serial)` / `wake_camera(serial)`                                                         | The camera's low-power idle (it stays asleep until woken: its link throughput limit turned on (`DeviceLinkThroughputLimitMode` `On`) at its floor, the power-saving mode on where the camera has one), with the temperature before / after; 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 from a later backend 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. Only the power state is kept; every other setting their open wrote goes back as found. |
| `calibrate_camera_with_target(serial, filter=None, attempts=30, settings=None)`                        | Capture frames until a MAPIR calibration target is in view, and fit the per-channel coefficients from its panels: `target_id`, `panel_dns`, `coefficients`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `network_adapters(estimate=False, cameras=1, pixel_format="BayerRG8")`                                 | This computer's Ethernet adapters for GigE Vision (MTU, link speed, jumbo frames) and any `issues`; `estimate=True` adds the frame rate and bandwidth `cameras` cameras would get.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `fix_network_settings()`                                                                               | Apply the GigE Vision adapter settings to this computer's camera adapter. It changes the adapter's settings and works only when Chloros runs as Administrator; otherwise it raises with the log of what it found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `apply_vignette_correction(input_dir, output_dir, lens_model=None)`                                    | Vignette-correct the images in a folder, each with its own lens's flat-field map: `processed`, `lens_models` (the lens each file was corrected for), `skipped` (with reasons). Without `lens_model`, each file's lens comes from its EXIF Model; a `lens_model` applies to files whose Model names no camera, and a file whose Model contradicts it is skipped. Files only.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `read_dls(mac, filter=None, camera_serial=None)`                                                       | One reading from a DLS (Bluetooth downwelling light sensor): spectrum, per-band irradiance, and band magnitudes through the camera's own response when `camera_serial` is given. `discover_daq_sensors(transports=["ble"])` finds the MAC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `probe_system(pixel_format="BayerRG12", discover=True)` / `system_info()`                              | The host's hardware for cameras and the configuration it recommends (`report_text`), and the system's CPU / GPU / PyTorch runtime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

* **Some need the camera to themselves.** `camera_white_balance_once()`, `apply_camera_preset()`, `sleep_camera()` / `wake_camera()`, `calibrate_camera_with_target()` and `update_camera_firmware()` open the camera. While Chloros holds it (connected in the app, with `connect_camera()`, as an array member, or in use by another command right now, such as an array test or capture opening its cameras) the backend refuses with HTTP 409 `CAMERA_HELD` (in both `code` and `error_code`), naming how to release it. The colour settings, highlights, `camera_power_probe()` and the reads work on a connected camera.
* **Colour, highlights and white balance are for RGB cameras.** On a single-band mono (M3M) camera the setters change nothing and return `{"skipped": True, "reason": ...}`, as the CLI does. They are display settings: the live view and display-level captures, never radiance or reflectance.

***

## Transient Arrays, Alignment Profiles & Indices

What `chloros-cli lattice` does without a persistent connection, as functions in `chloros_sdk` (module `chloros_sdk.array_utils`): `continuous`, `multi-capture`, `multi-stream`, `multi-test`, `multi-detect`, `analyze-array`, `align-calibrate`, `align-apply`, `align-stream`, `align-info`, `align-reorder` and `index`. Each sends the request the CLI command sends, with the CLI's defaults.

```python
import chloros_sdk as c

prof = c.calibrate_alignment_profile(["214000535", "214000551", "214000556"],
                                     "D:/rig/alignment_profile.json", method="orb", model="rigid")
print({sn: t["reprojection_error"] for sn, t in prof["transforms"].items()})

c.capture_aligned_multiband("D:/rig/alignment_profile.json", "D:/rig/out")
idx = c.capture_live_index("D:/rig/alignment_profile.json", preset="NDVI",
                           output_dir="D:/rig/ndvi", capture_level="reflectance")

with c.start_multi_camera_stream(["214000535", "214000551"], "D:/rig/stream", fps=5, count=50) as job:
    print(job.wait()["final_stats"])          # waits for the 50 groups, then closes the cameras
```

* **They open the cameras themselves.** Each command opens its cameras, does its work and closes them, so it needs cameras Chloros is not holding (connected in the app, with `connect_camera()`, or as an array member); the backend refuses with HTTP 409 `CAMERA_HELD` and says how to release one. A transient open takes a while (about 40 s for a few cameras). For repeated captures, `connect_array()` once is the fast path, and it saves every export type where a transient capture saves a debayered image. `calibrate_alignment_profile()` is the exception: on a connected array of those cameras it solves from the array's own frames (`used_live_array`).
* **`serials`** are the cameras to open, the first firing the trigger; `None` opens every camera on the network.
* **`settings`** is a dict of camera-setting overrides, the fields the CLI's flags set: `exposure_time` (µs), `gain` (dB), `pixel_format`, `width`, `height`, `target_brightness`, `ae_damping`, `ae_upper_limit`, `frame_rate`, `gev_packet_size`, and `preset` (a camera preset by name). An exposure or gain given turns that auto control off, as the flags do.
* **`gpu`**: `True` forces the GPU warp, `False` the CPU (`--gpu` / `--no-gpu`); `None` lets the backend choose.
* **`keep_settings`** / **`clear_settings`** (every function that opens cameras, default `False`): at the end each camera is put back as it was found; `keep_settings=True` saves the run's settings into the camera's own memory instead (free-running), `clear_settings=True` resets that memory to the factory settings — see [Camera memory](#camera-memory--keep_settings--clear_settings). The reply (for a job, `stop()`'s) carries `camera_memory`.
* **Paths are the backend's**: relative ones are made absolute against your working directory when the backend is on this machine. The alignment-profile file functions (`alignment_profile_info()`, `reorder_alignment_profile()`) read the file on this computer, as the CLI does.

| Function                                                                                                                                                                                                                                                                                                             | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start_camera_continuous(serial, output_dir="output", *, format="tiff", jpeg_quality=95, queue_depth=64, settings=None)`                                                                                                                                                                                             | Record one camera continuously until stopped. Returns a `CliJob`. A `tiff` run's frames are the `raw` file an array capture writes of that camera (one mosaic plane at the sensor's own values, uncompressed); `png` and `jpg` hold 8 bits, so those runs are demosaiced frames for viewing. A bound or pooled DAQ writes one `.daq` per frame in the run's `daq/` folder (`daq_files` in its stats). Each frame is written once with its full metadata (Model, capture time, lens, bands, calibration on a raw frame); `stop()` returns once every frame already grabbed is written (up to 25 s), and only then is the camera closed. A camera left armed for a hardware trigger (`TriggerMode` `On`) is set to free-run for the run (the start reply's `trigger` says what was found). At the stop the camera is put back as it was found — its trigger settings and every setting the run changed — unless `keep_settings=True`, which saves the run's settings into the camera's own memory (free-running), or `clear_settings=True`, which resets that memory. A run that records no frame ends itself after 10 s with `stop_reason` `no_frames` and the reason in `last_error`, and its `stop()` returns that reason as `error`. Frames dropped because the writers could not keep up are counted, with `drop_reason` saying why. For a camera Chloros holds, use `CameraSession.capture_repeated()`. `lattice continuous`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `start_multi_camera_stream(serials=None, output_dir="output", *, fps=3.0, count=None, format="tiff", jpeg_quality=95, settings=None)`                                                                                                                                                                                | Stream synchronized frame groups at `fps`, for `count` groups or until stopped. Returns a `CliJob` (its `start_reply` has `n_cams` and the wire `pacing`); its final stats count the groups grabbed, written and dropped, the files the writer could not write and the groups a camera delivered nothing for. `lattice multi-stream`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `capture_cameras_transient(serials=None, output_dir="output", *, format="tiff", jpeg_quality=95, settings=None)`                                                                                                                                                                                                     | One synchronized capture, a debayered image per camera: `results` (`filepath`, `serial`, `frame_id`) and `pacing`. A group missing a camera raises, naming how many files were saved first. `lattice multi-capture` with no array connected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `test_array_sync(serials=None, count=10, ptp_settle_s=None, timeout=None)`                                                                                                                                                                                                                                           | `count` synced grabs at a fixed exposure: `sync_groups`, the `master`, one `group_timestamps` row per trigger (a camera that missed one is absent from its row) and `sync`: every other camera's offset from the master, trigger by trigger (`offsets_us`: per camera `mean_us`, `min_us`, `max_us`, `jitter_us`, `groups`), on ONE clock (`clock_domain`: `ptp`, or `device` — PTP off, each camera's own uptime clock, so its offset is when it booted and only the jitter measures the sync). A trigger whose stamps mix the device clock and PTP (PTP off or still locking) is left out and counted (`groups_mixed_domain`), as is one where a PTP clock is still more than `agree_within_us` from the master (`groups_clocks_disagree`); `notes` say so. `clock_offset_mean_us` / `clock_offset_jitter_us` are the largest per-camera mean and jitter. `success` is false, with `error`, when a trigger was missed, when fewer than two triggers have every camera on one clock, or when the clocks never agree (`sync.problems`); the rows are returned either way. It starts the PTP grandmaster if it is not running (`time_sync` says `grandmaster_running` and `grandmaster_started_by_this_test`), turns every camera's PTP on (as `connect_array()` does), 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_s` (0-600; `0` for no settle wait) sets the settle time for the run; another value is refused (HTTP 400). The wait is bounded at the settle time plus 90 s (210 s by default, at least 90 s), and the call waits for the backend `timeout` s: by default 240 plus the settle time (360 s), as `chloros-mcp`'s `test_array_sync` does. `ptp_lock` has `converged`, `waited_s`, `timeout_s`, `settle_s`, `locked_s` (how long every camera has been locked and steady together), `found_settled` (the cameras already locked for the settle time when found) and, per camera, `status`, `offsets_ns`, `slave_s` (how long it has been locked; None: not locked) and `remaining_s` (None when no camera's PTP would turn on). The backend's log has a line every 5 s with each camera's state, how long it has been locked and how long it has left. 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 (`ExposureAuto` / `GainAuto`, and a manual `ExposureTime` / `Gain`), and the rest, unless `keep_settings=True` — so a camera left with PTP on (`PtpEnable=True`, or a run with `keep_settings=True`) 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, `success` is false before any trigger, and `error` says what to do: a camera that never locked (`not_slave`) means the grandmaster is not reaching it (`time_sync_status()`); one that kept dropping out is named with how long it had been locked (`remaining_s`); clocks still converging (`far`): check `time_sync_status()`, and to have them locked before the test, turn PTP on and leave it on (`PtpEnable=True` on each camera, or `keep_settings=True`; the test puts back what it found, so it stays on), then run it. `lattice multi-test`. |
| `detect_array_master(line=None)`                                                                                                                                                                                                                                                                                     | The cameras on the sync line and a default master: `master_serial`, `slave_serials`, the `line` probed. `lattice multi-detect`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `analyze_array_models(camera_models=None, *, width=2048, height=1536, n_active=None, force_tier=None, binning=1, packed="auto", pixel_format=None)`                                                                                                                                                                  | What an array of these camera models (product names, `"LATT-M3C-L87-FOCN"`) would get on this computer's network: `tier`, `achievable_fps_max`, the wire budget (`max_cams_collision_safe`, `oversubscribed`), `cam_caps` and `fix_suggestions`. By default the discovered cameras' models; no camera is opened. For cameras you have, with the settings a connect would use, see [`analyze_array_network()`](#network-analysis-helper). `lattice analyze-array`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `calibrate_alignment_profile(serials=None, save_path="alignment_profile.json", *, frames=3, method="orb", model="rigid", reference_serial=None, checkerboard=None, control_points=None, preview=False, vignette=False, roi=None, mask_path=None, rms_threshold_px=None, per_cam_overrides=None, settings=None, ...)` | Solve an alignment profile from live frames and save it. `method`: `orb`, `akaze`, `phase`, `checkerboard` (with `checkerboard="9x6"`, the inner corners) or `manual` (with `control_points={serial: [[x, y], ...]}`, the reference camera's too). `model`: `translation`, `rigid`, `affine` or `homography`. The finer options are the CLI's flags: `max_features`, `ratio_threshold`, `matcher` (`bf` / `flann`), `knn_k`, `prefilter` (`none` / `gradient` / `clahe` / `blur` / `hist_match`), `ransac_threshold_px`, `ransac_max_iters`, `ransac_confidence`, `averaging`, `lock_rotation`, `lock_scale`, `lock_axis`; `per_cam_overrides` is `{serial: {option: value}}`. `rms_threshold_px` refuses to save a worse solve. Returns `save_path`, `output_width` / `output_height`, `crop_roi`, `reference_serial`, `transforms` (per camera `reprojection_error`, `num_matches`) and `preview_path`. `lattice align-calibrate`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `capture_aligned_multiband(profile_path, output_dir="output", *, serials=None, format="tiff", bit_depth=None, gpu=None, no_crop=False, bands=None, order=None, vignette=False, per_band=False, per_camera=False, interpolation="linear", border_mode="constant", border_value=0, settings=None)`                     | One aligned multi-band image through the profile: `files` (the multi-band TIFF with its `bands` and size, plus one per band with `per_band` and one per camera with `per_camera`) and `vignette_corrected`. `bands` picks and `order` orders the bands by name (a list or a comma string). `lattice align-apply`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `start_aligned_stream(profile_path, output_dir="output", *, serials=None, fps=3.0, count=None, ...)`                                                                                                                                                                                                                 | Stream aligned multi-band images (the same warp options as `capture_aligned_multiband()`), for `count` or until stopped. Returns a `CliJob`; its final stats count `frames_written` and any `frame_groups_incomplete`. `lattice align-stream`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `alignment_profile_info(path)`                                                                                                                                                                                                                                                                                       | A profile file summarized as `align-info` prints it: `name`, `created`, `method`, `reference_serial`, `sensor_resolution`, `output_width` / `output_height`, `crop_roi`, `camera_serials`, `transforms` (per camera `model`, `reprojection_error`, `num_matches`, `reference`), `camera_models`, `layer_order` (per camera `band_names`, `wavelengths_nm`, `enabled`); `profile` is the whole file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `reorder_alignment_profile(path, order=None, enable=None, disable=None)`                                                                                                                                                                                                                                             | Change the profile file in place: `order` is band names (each moves its camera's layer up, in that order), `enable` / `disable` are serials. Returns the new `layer_order`. `lattice align-reorder`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `index_catalog()`                                                                                                                                                                                                                                                                                                    | The index presets (`presets`: each `name`, `channels`, `formula`) and colour `gradients`. `lattice index --list-presets` / `--list-gradients`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `compute_index(input_path, *, preset=None, formula=None, channel_map=None, output=None, capture_level="unknown", output_format="all", colorize=False, gradient="RdYlGn", vmin=None, vmax=None, percentile=None, bg_mode="clip")`                                                                                     | An index over an aligned multi-band TIFF: a `preset` (`NDVI`, `NDRE`, ...) or a `formula` over the symbols `channel_map` maps to bands (`{"NIR": "NIR_850", "Red": 0}`, by name or index). A preset's symbol `channel_map` leaves out takes the one band of the file whose name starts with it (`red` -> `Red_660`, `nir` -> `NIR_850_RGN`), named by the file itself (its band list, or a Chloros capture's / product's `Chloros:Band{R,G,B}Name`), so NDVI on a Chloros reflectance capture needs no `channel_map`; two bands answering to one symbol are refused, not guessed. `capture_level` says what the bands hold: `reflectance` or `radiance` make the values quantitative; an uncalibrated stack (`align-apply`'s) gives qualitative values; `"unknown"` reads it from the file, a Chloros file's `Chloros:ProcessingLevel` included. Returns `stats` (shape, the 1-99 percentile range, the LUT range, the `capture_level` used) and the `files` written beside the input (`<input stem>_<preset>.tif`, `..._LUT.png`) or at `output`, a path: with an image extension the files are named from its stem (`output="D:/out/ndvi_FRGN.png"` writes `ndvi_FRGN.tif` and `ndvi_FRGN_LUT.png`), without one it is a prefix (`D:/out/ndvi` -> `ndvi.tif`, `ndvi_LUT.png`); read the paths from `files`. They carry the input's camera record (Make / Model / serial, GPS, lens, capture time in UTC, the calibration identity but never its raw-DN calibration), `Chloros:ProcessingLevel=index`, and the index as their one band (`XMP-Camera:BandName`, the TIFF and the LUT PNG alike). Files only; no camera. `lattice index --input`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `capture_live_index(profile_path, *, preset=None, formula=None, channel_map=None, serials=None, output_dir="output", output_prefix="index", capture_level="reflectance", save_multiband=False, ...)`                                                                                                                 | Capture, calibrate (`reflectance` or `radiance`; `raw` skips it), align and compute an index in one step; `save_multiband=True` keeps the calibrated stack, which `compute_index()` can take later. Returns `stats` (with the `serials` whose bands it used) and the `files`. It opens `serials` (the first fires the trigger), else the profile's cameras whose `layer_order` entry is enabled, the reference first (opened even with its bands disabled); a camera whose bands are disabled is never calibrated. `channel_map` is needed only for a symbol the stack cannot answer, as in `compute_index()`: a preset's symbol takes the one enabled band whose name starts with it, checked before any camera opens (none or several answering is refused, naming them); a custom `formula` needs every symbol. `index.tif` and the LUT carry the stack's camera, capture time (the reference camera's exposure, UTC) and lens, and both name the index as their one band (`XMP-Camera:BandName`, e.g. `NDVI`: the colour PNG names the index, not its colour channels). `lattice index --live`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

### `CliJob`

The handle the three streams return. The job runs on the backend, which owns its cameras until it is stopped.

| Member                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stats(timeout=10.0)`                                    | `running`, `state`, `stats` (frames saved / written, dropped, `fps`, `elapsed`, write failures, `stop_reason`; a continuous job also `frames_grabbed` and `frames_queued` -- every grabbed frame is written, queued, dropped or failed -- and `drop_reason`, `writers` and `write_ms`, the mean time one frame's write took) and `output_dir`. `state` is `running`, `ended` (it stopped itself and has not been stopped yet), `stopping` (a stop is writing out its queue: live stats, and `stopped_by`) or `finished` (its final stats, the stop's `error` and `stopped_by`). A stopped job's record is kept for 10 minutes (the last 32 at most), for every client: another script or `chloros-mcp` reads the same state and final stats. A job `chloros-cli` started (`lattice continuous`, `multi-stream`, `align-stream`) is stopped by the backend when the CLI stops checking in for 30 s — killed, its machine asleep — with `stop_reason` `client_gone` and `stopped_by` the backend; reading its stats from here does not keep it alive. A job started from the SDK runs until it is stopped. Each start sends its `timeout` as the backend's deadline (`client_deadline_s`): a camera that opens after it (one still booting) is put back and closed and no job is started, and the call raises `ChlorosConnectError` (`CLIENT_DEADLINE_PASSED`). A camera a job holds is refused to every other open (`connect_camera()`, another start, a transient capture) with HTTP 409 `CAMERA_HELD`, naming the job and who started it. |
| `stop(timeout=30.0)`                                     | Stop it and close its cameras: `final_stats`, `output_dir`, and `error` when the stop did not go cleanly. A second call returns the same answer, and so does a stop from another client: one sent while the first is still writing out its queue waits for it (up to 25 s; past that it raises, and the final stats follow on `stats()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `wait(timeout=None, poll_s=0.5)`                         | Wait until it ends by itself (its `count` reached, a full drive, an error), then `stop()` it to collect the final counts. `timeout` raises `TimeoutError` with it still running; a job with no `count` ends only when stopped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `job_id`, `kind`, `output_dir`, `start_reply`, `stopped` | Its id and kind (`continuous`, `multi-stream`, `align-stream`), where it writes, the start route's reply, and whether `stop()` has run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

Use it as a context manager to stop it on scope exit.

***

## Project Folder & Recipes

**The project folder** is the folder new projects are made in, shared by the Chloros app, the CLI and the SDK (module `chloros_sdk.system_utils`; `chloros-cli project-folder`):

```python
print(chloros_sdk.project_folder())                # the configured folder, else the default
chloros_sdk.set_project_folder("D:/Flights")       # created if missing
chloros_sdk.reset_project_folder()                 # -> {"path": <default>, "was_set": True}
```

A configured folder that no longer exists falls back to the default (`Documents/MAPIR/Chloros Projects`), as the app does. A relative path given to `set_project_folder()` is taken from your working directory when the backend is on this machine.

**A recipe** is the YAML / JSON action list `chloros-cli project run PATH RECIPE` runs against a saved project. `run_project_recipe()` runs it with the CLI's own runner (installed with the SDK), so one recipe behaves the same from either:

```python
r = chloros_sdk.run_project_recipe("D:/campaign/morning.yaml", "D:/Projects/Field_A")
print(r["ok"], r["actions"])
print(r["log"])                                    # what the CLI would have printed

chloros_sdk.run_project_recipe({"actions": [{"apply": {"name": "FrontLeft", "settings": {"exposure_us": 5000}}},
                                            {"wait": "2s"},
                                            {"capture": {"name": "FrontLeft", "output": "pose_a/", "format": "tiff"}}]},
                               "D:/Projects/Field_A")
```

```python
run_project_recipe(recipe, project_path, *, dry_run=False, echo=False,
                   backend_url="http://127.0.0.1:5000") -> dict
```

* **`recipe`** is a `.yaml` / `.yml` / `.json` file or the recipe itself: a dict with `actions` (`apply`, `capture`, `burst`, `stream`, `sensor`, `wait`), and optionally `overrides` and `stop_on_error` (default true: the run stops at the first action that fails). The actions are the CLI reference's [Recipe DSL](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#recipe-dsl); a relative `output` is resolved against your script's working directory.
* **Returns** `ok` (every action succeeded), `actions` (how many), `log` (the runner's output; `echo=True` also prints it as it runs) and `validation`. A recipe file that is missing or does not parse raises `ChlorosConnectError`.
* **Checked before it runs.** `validation` is `{"ok", "errors", "warnings", "steps"}`: every action must be exactly one known verb as its key (`{"capture": {"name": ...}}`, not `{"action": "capture"}` or `{"type": "capture"}`) naming a camera, array or sensor the project has, of the right kind. A recipe with an error runs **no** action (`ok` false, the errors in `log`), whatever `stop_on_error` says. Unused keys, and every array or light sensor the recipe drives that is not connected now, are `warnings`. A recipe does not connect devices: connect the project's first (`ChlorosProject.connect_all()`, `chloros-cli project connect`, or the MCP tool `connect_project_devices`). `dry_run=True` runs nothing and returns `{"recipe": ..., "validation": ...}`.
* One recipe runs at a time in a process. A YAML recipe needs PyYAML.

***

## Project Automation — `ChlorosProject`

A saved Chloros project is a folder containing `cameras.json` + `sensors.json` + `project.json`. `open_project(path, relink=None)` loads the manifest (`relink`: the folder a moved project's missing source files are in now, used when the backend loads it -- `process()` -- see **A moved project** under `ChlorosLocal`), and `connect_all` brings every saved camera, array and light sensor online with its saved settings — same hardware state the GUI would produce. Light sensors connect through the backend's [DAQ sensor pool](#daq-sensor-sessions), so they need a running backend (see [`SensorHandle`](#sensorhandle)).

### Minimal Example

```python
import chloros_sdk

proj = chloros_sdk.open_project("/home/user/Chloros Projects/Field_A")
report = proj.connect_all(verbose=True)
print(report)  # {'cameras': {...}, 'arrays': {...}, 'sensors': {...}}

# Cameras and arrays are addressable by name OR serial / array_id
cam = proj.cameras["FrontLeft"]
cam.capture("./out", format="tiff", processing="reflectance")

arr = proj.arrays["main_rig"]
arr.capture("./out", format="tiff", processing="reflectance")

# Light sensors are addressable by name OR slot_id
reading = proj.sensors["Sky"].read()   # (spectrum, is_saturated, ...) or None

# One frame from every camera and array, one spectrum from every sensor
proj.capture_all("./out")

proj.disconnect_all()
```

Or as a context manager:

```python
with chloros_sdk.open_project("/path/to/proj") as proj:
    proj.connect_all()
    proj.arrays["main_rig"].capture("./out", processing="reflectance")
```

### `ChlorosProject` Methods

| Method                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect_all(*, cameras=True, arrays=True, sensors=True, verbose=False, align=None, packed=None)` | Discover + connect every saved camera, array and light sensor. Returns a per-class connect report (`{"cameras": {...}, "arrays": {...}, "sensors": {...}}`, each with `connected`, `missing` and `errors`; `arrays` also carries `alignment`). With a backend listening on `127.0.0.1:5000`, the saved cameras and arrays are found and connected through it. With none, this process finds and drives them itself through `lattice_sdk`, which needs the Arena SDK runtime and OpenCV (`cv2`) — the SDK wheel installs neither; when it cannot, every saved camera and array is listed under `errors` with the reason, and `missing` stays empty. A backend that is running but refuses the SDK (logged out: HTTP 401; a plan below Copper: 403) is not "no backend": every saved camera, array and light sensor is listed under `errors` with the backend's reason, and nothing is opened in this process. Each call checks the backend again, so `connect_all()` after logging in, or after starting Chloros, connects on the same project object. A saved array already up in the backend with the same cameras (the GUI's, or `chloros-cli project connect`'s) is attached as it is, without re-applying its saved settings, and `disconnect_all()` leaves it running. Light sensors always go through the backend (see [`SensorHandle`](#sensorhandle)). It never spawns a backend. |
| `disconnect_all()`                                                                                | Tear down everything. Every device is released first; then, if the backend did not confirm the release of a camera, array or light sensor (the teardown timed out, or was refused), one `ChlorosConnectError` names each. A device already gone, or no backend running, is silent. An array or light sensor another client had open is left running. The project's `with` exit never raises.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `capture_all(output_dir=".")`                                                                     | One frame from every connected cam + array, and one spectrum (`SensorHandle.read()`) from every connected light sensor, taken in turn (cameras, then arrays, then sensors), not at one instant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `stream(camera, overlays=False, fps=10.0)`                                                        | Generator yielding BGR `numpy` frames from a named cam (or array). `overlays=False` reads frames with the handle's `grab()` at the `debayered` level: through the backend when the project connected through one, else a direct `lattice_sdk` grab loop (arrays yield `{serial: frame}` dicts). `overlays=True` routes through `ChlorosLocal.camera_stream()` → the backend's `/api/camera/<serial>/stream-annotated` MJPEG feed, with the cam's saved `ui.overlay` block passed through as query params. Requires backend mode, OpenCV (`cv2`) and a **standalone camera**: a direct-mode cam raises `RuntimeError` (the backend can't grab a cam this process owns) and an array raises `NotImplementedError` (overlays composite per camera — stream a member by name). One-shot equivalent: `CameraHandle.capture(annotated=True)`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `align_arrays(align=True, verbose=False)`                                                         | Run alignment on every currently-connected array.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `process(mode="parallel", wait=True, progress_callback=None, poll_interval=2.0)`                  | Run the calibration / index pipeline on the project's images (wraps `ChlorosLocal.process`; these four are the **only** accepted kwargs — `indices=` etc. raise `TypeError`; set indices via `ChlorosLocal.configure()`). Lazily constructs a `ChlorosLocal()`, which auto-starts a backend.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

Attributes:

* `proj.cameras` — `Dict[str, CameraHandle]` keyed by name AND serial.
* `proj.arrays` — `Dict[str, ArrayHandle]` keyed by name AND array\_id.
* `proj.sensors` — `Dict[str, SensorHandle]` keyed by name AND slot\_id.
* `proj.config` — `project.json["config"]` dict.

### `CameraHandle`

```python
cam = proj.cameras["FrontLeft"]

# Save a frame to disk (processing-aware)
filepath = cam.capture(
    output_dir="./out",
    format="tiff",
    processing="radiance",           # see the level table below
    apply_calibration=True,          # DSNU + flat + 3x3 unmix + NIST
    apply_white_balance=True,        # DLS-aware WB
    apply_index=False,
    index_expression=None,
)

# In-memory grab (numpy array)
frame = cam.grab(processing="debayered")
frame, header = cam.grab(processing="radiance", with_metadata=True)

# Frame iterator (generator)
for arr in cam.frame_stream(processing="debayered", fps=5, count=100):
    my_analysis(arr)
```

**Processing levels.** `capture()`, `grab()`, and `frame_stream()` all take the same `processing` token, and the chain is cumulative — each level runs everything above it:

| Level         | Output                                                                                                                                                                                                                                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `raw`         | 1-channel Bayer, sensor-native                                                                                                                                                                                                                | No demosaic. Overlays are not available at this level.                                                                                                                                                                                                                                                                                                                                                                  |
| `debayered`   | 3-channel colour (**default** for `CameraHandle` and every `grab()` / `frame_stream()`; `ArrayHandle.capture()`, `capture_smart()` and `stream()` default to `raw`): BGR in memory (`grab()` / `frame_stream()`), saved as RGB by `capture()` | In backend mode, as a capture: the calibration pack's dark offset (DSNU) off the raw, then OpenCV's edge-aware demosaic — no linearity LUT, flat field or unmix. The only level that works without backend mode, where it is the camera library's plain bilinear demosaic (no dark offset). The saved TIFF is photometric RGB, so reverse an in-memory frame's channels (`frame[..., ::-1]`) to compare it with a file. |
| `radiance`    | float32, W/m²/sr/nm, **one plane per band**                                                                                                                                                                                                   | Full radiometric chain: demosaic + 3×3 unmix (multispec) + DSNU + flat-field + NIST scale, with exposure × gain divided out so values are absolute.                                                                                                                                                                                                                                                                     |
| `reflectance` | uint16, 32768 = 1.0 (or uint8, 255 = 1.0 — see `bit_depth`), **one plane per band**                                                                                                                                                           | Radiance divided by downwelling irradiance (ρ = π·L/E). Needs a DLS/DAQ reading — see the note below.                                                                                                                                                                                                                                                                                                                   |
| `display`     | 8-bit sRGB-ish                                                                                                                                                                                                                                | GUI-equivalent render: CCM + white balance + gamma via the cam's active colour profile.                                                                                                                                                                                                                                                                                                                                 |

In direct (backend-free) mode only `debayered` is available: `grab()` at another level raises `NotImplementedError`, `capture()` ignores `processing`, and `frame_stream()` raises `RuntimeError` at every level. `reflectance` needs a usable downwelling reading — the frame endpoint pulls the pooled DAQ into the camera's DLS slot automatically, but with no DAQ bound the chain refuses the reflectance exit and honestly stamps the demotion in the returned metadata rather than silently handing back a lesser product.

> **Reflectance DN scale — don't hardcode it.** LATTICE reflectance uses `32768` = ρ 1.0 and stamps XMP `Chloros:PixelScale=32768`; Survey3 reflectance uses `65535` = ρ 1.0 and carries no `Chloros:*` tags. Read the tag and divide by it. It is defined in the uint16 domain, so it stays `32768` for every format that rescales (16-bit TIFF, 8-bit TIFF, 8-bit PNG/JPG, 32-bit percent) — normalise the stored dtype back to uint16 first (×257 from 8-bit, ×65535 from float). The one exception is a file from a build before 1.3.0: an 8-bit TIFF was *clipped* then, not rescaled, so no scale describes it, and it carries no `PixelScale` or MicaSense tuple. Treat a missing tag on a LATTICE reflectance file as "no valid scale", not as a default.

**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 continuous-recording / multi-camera-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. Processing 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 (`capture_aligned_multiband()`, `start_aligned_stream()`, `capture_live_index(save_multiband=True)`, `Registration.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 — a `capture_aligned_multiband()` / `start_aligned_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 processing 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, a `capture_aligned_multiband(per_camera=True)` frame, a stack or live index of a single camera — carries that camera's own identity tags, as every other capture file does. `capture_aligned_multiband()`'s stack, per-band and per-camera files, and each `start_aligned_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).** Frames from `grab()` / `frame_stream()` are always in the camera's native orientation, at every level. Saved captures follow the camera's orientation setting (the GUI's Mirror H / Mirror V / rotation):

* **`raw` and `debayered` files are exactly what the sensor read**, whatever the setting — a Bayer mosaic turned or flipped would be a different colour-filter pattern, and the calibration maps are on the sensor's own grid.
* **`display`, `radiance`, `reflectance` and index files are oriented** — turned once, after all the calibration math. Their clamp masks 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, `true` on the oriented products. `ChlorosProcessing` lists the operations applied to that file's pixels (`none` when native). That includes every frame of a continuous recording (the camera's own setting, unapplied) and of a multi-camera stream (the identity: its member frames are native, like an array capture's).
* **Processing a project applies the recorded orientation** to the products it makes from a raw (calibration in sensor coordinates first, the array alignment warp next, the orientation last), so they match the live capture's products — the uncalibrated sensor-response / vignette-corrected fallback products included; its 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; a file without the record is shown as stored.
* **Captures without the record are processed as native.** Before 1.3.0 a single-camera capture turned its raw and debayered files itself; Chloros cannot tell such a raw from a native one and does not guess.
* **Array captures keep every member file native by default** and record the identity; `ArraySession.capture(orient=True)` turns their products (see the array capture controls).

#### Per-band output and mixed arrays

At the `radiance` and `reflectance` levels a camera returns **one plane per band of that camera** — three for an M3C (its three unmixed bands, BGR channel order), one for an M3M (its single narrowband filter). The mono camera's replicated planes are collapsed, so a **mixed M3C/M3M array yields different array shapes per serial**. Read the `bands` key from the frame metadata to learn what each plane is; do not infer it from the channel count:

```python
for serial, (arr, hdr) in arr_handle.grab(processing="reflectance",
                                          with_metadata=True).items():
    print(serial, arr.shape, hdr["bands"])   # ('…', (1536, 2048, 3), ['nir','green','red'])
                                             # ('…', (1536, 2048, 1), ['F685'])
    rho = arr.astype("float32") / hdr["pixel_scale"]
```

Always check `hdr["processing_level"] == "reflectance"` before using the values. A demotion (no DAQ reading, no cal pack, unknown band layout) is reported in `processing_level` and `radiometric_refused` rather than raised — the array you get back is still a valid frame, just not the product you asked for. A saved capture that was demoted carries the same code in its XMP as `Chloros:RadiometricRefused` (e.g. `no-band-layout`, `no-dls-snapshot`).

#### One trigger per read — `group_id`

**Array members are served from the array's synced frame group, not from each camera's own grab buffer.** The cameras of a hardware-synced array expose together, but N per-camera reads do not *sample* together — reading each camera's latest buffered frame straddles trigger boundaries, and a single dropped frame desynchronises the set with nothing noticing.

Serving from the group is necessary but not sufficient on its own: each request still snapshots *the latest* group at its own instant, and the grab loop can publish in between. Measured on a live 4-camera array, **12 of 20 parallel reads straddled two groups** — always exactly adjacent. So the read is **pinned**:

1. Every frame carries `group_id`, the array's monotonic publish counter.
2. `grab()` reads the master (or, if the master cannot be served, the next camera that can), then pins the remaining cameras to the group id it landed on (`?group_id=N` on the HTTP endpoint).
3. The backend keeps recent groups for **at least half a second**, so a sibling already overtaken by later publishes is still served that trigger — long enough for a per-camera reflectance export's round trip even on a 9-camera full-sensor array. A pin the backend no longer holds is refused with `409` and `group_aged_out: true` rather than silently answered with a different trigger — `grab()` re-reads the set.

Re-measured with pinning: **20 of 20 reads returned one trigger.** `grab()` does this for you; you only need `group_id=` when driving the HTTP endpoint directly.

* A camera that cannot be served at the pinned group — missing from it, or refusing the request (a `band` it does not have, a level it cannot produce) — is **omitted rather than back-filled** from a different trigger, and the other cameras are still returned.
* The dict `grab()` returns is a `GrabResult` (a plain `dict` subclass; `from chloros_sdk import GrabResult`): `.errors` maps each omitted serial to the exception its read raised, and `.group_id` is the shared group. An empty `.errors` means every camera made this group.
* A standalone camera has no group, reports `group_id: None`, and **rejects** a `group_id=` pin rather than ignoring it.

```python
frames = arr_handle.grab(processing="reflectance")
for serial, err in frames.errors.items():
    print(f"SN:{serial} omitted: {err}")       # e.g. status=400 ... band 'F685' not in [...]

frames = arr_handle.grab(processing="reflectance", with_metadata=True)
ids = {hdr["group_id"] for _a, hdr in frames.values()}
assert len(ids) == 1, f"straddled triggers: {ids}"     # belt and braces
```

The same counter is published on **every per-camera MJPEG stream** of an array member — the preview (`/api/camera/stream/<serial>`), the annotated preview (`/stream-annotated`) and the reflectance stream (`/stream-reflectance`) — as `X-Chloros-Group-Id` on each part, beside `X-Chloros-Frame-Id` and `X-Chloros-Timestamp-Ns`. Streams are continuous rather than point-in-time, so they are matched by collecting parts and grouping on that header — there is no pin to set. A standalone camera has no group. See [Per-camera MJPEG streams](#per-camera-mjpeg-streams-no-rtsp).

**`frame_stream()` never goes silent.** A tick that fails for a reason that can clear on its own is skipped — a camera stream yields nothing for it, an array stream yields the cameras that did answer (possibly none). Those reasons are: no frame yet; the camera's grab thread paused for a second or two (`404 not streaming`, which the backend answers whenever another camera connects or disconnects, or a setting change rebalances the pool); a backend restart or `5xx`; alignment still settling (`409 … retry shortly`); and a reflectance refusal because the DAQ has no reading yet (`no-dls-snapshot`, a stale or empty reading). A refusal the next tick would only repeat — an unknown `band`, `bit_depth=8` on radiance, a cal pack with no radiance scale, a reflectance refusal with **no DAQ at all** (none bound to the camera or its array, none connected to the backend: the refusal's `dls_source` is `"none"`), any other `4xx` — raises `chloros_sdk.FrameFetchError` (a `RuntimeError`, carrying `.status` and `.body`) at once. So does **60 seconds** of skipped ticks with no frame in between, whatever the `fps` — long enough to ride out alignment settling and a backend restart, short enough that a camera that is really gone ends the stream. That give-up error is a `FrameFetchError` too, for a camera as for an array, with the last read's own exception on `.errors` (and, for a camera, as `__cause__`). For an array, "refused" means every camera refused; the exception's `.errors` holds each camera's reason.

**An array `frame_stream()` yields each trigger once** (`ArrayHandle` and `ArraySession` alike). A tick whose newest set is the trigger it already yielded waits for the next trigger instead of yielding the same set again, so the stream runs at the slower of `fps` and the array's own frame rate, and consecutive sets never share a `group_id`. An array that stops publishing raises `FrameFetchError` ("no new trigger for 60 s") rather than repeating its last set. Without this, a stream asked for more than the array published — or started right after connect — handed out repeats: in one measured run, 20 sets held 11 distinct group ids.

```python
from chloros_sdk import FrameFetchError

try:
    for arr in cam.frame_stream(processing="radiance", bit_depth=8):
        my_analysis(arr)
except FrameFetchError as exc:
    print(exc.status, exc.body)        # the HTTP status and the backend's reason
```

#### Exporting a single band — `band`

`grab()` / `frame_stream()` take `band="<name>"` to export just one of a camera's bands as a single-channel `(H, W, 1)` array — the same shape a mono camera produces, so one-band output is handled identically whether it came from an M3M or from splitting an M3C. An FRGN's red band:

```python
red = cam.grab(processing="reflectance", band="red")        # (1536, 2048, 1)
```

Accepted spellings are the full layout name (`Red_660`, `NIR_850`, `Green_550`) or its short head (`red`, `nir`, `green`), case-insensitive. An unknown name is rejected with the available names listed.

> **Selection is by name, not by channel number — deliberately.** "Channel 1" is `Green_550` in the array's BGR channel order but *red* in the filter code's letter order (`RGN`), and the two disagree. Picking the wrong one yields a perfectly plausible frame of the wrong band, which nothing downstream can detect. There is no numeric index for that reason.

#### Aligning the streams — `align`

`align=True` warps the frame into its array's common reference frame. Each camera is warped through the **same** profile resolution and crop ROI, so per-camera streams opened independently come out **mutually registered** — you do not have to request them together:

```python
frames = arr_handle.grab(processing="reflectance", align=True)   # {serial: array}
# or one MJPEG stream per camera, each co-registered on its own:
#   GET /api/camera/<serial>/stream-reflectance?align=1
```

Requirements and behaviour:

* The camera must be in a **hardware-synced** array (M8 sync cable) that has an alignment profile — co-registration assumes the members exposed simultaneously, which a software or free-run array does not provide. Refused with `409` otherwise.
* **Refused, never silently unaligned.** The capture path may save unaligned with a warning because a file keeps its provenance tags and can be re-registered later; a live stream has no such second chance, so a missing profile is an error rather than a fallback.
* **Asking for alignment starts it.** Requesting `align` on an array with no profile kicks the calibration and returns `409` with what it is waiting for (e.g. *"waiting for exposure to settle on 214000551 (1/3)"*) — retry and it succeeds, typically within a few tens of seconds. This matters headlessly: the connect-time auto-align gives up after 30 s, and every attempt inside that window is skipped while smart-AE is still settling, so an array whose exposure converges slowly used to end up with no profile for the whole session and no way to obtain one without opening the desktop combined view. `alignment_status` also reports `ae_align_holdouts`, naming the cameras still settling and their progress.
* Give every stream of one array the **same `max_h`**, or their crops land on different pixel grids.
* Alignment is applied *before* the bit-depth encode, so the warp interpolates full-precision values.

#### `bit_depth` — trading precision for bandwidth

`grab()` and `frame_stream()` accept `bit_depth=16` (default) or `bit_depth=8`:

| `bit_depth` | Reflectance encoding                         | Cost                                                                                                      |
| ----------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `16`        | uint16, 32768 = ρ 1.0, headroom to ρ 2.0     | Full precision.                                                                                           |
| `8`         | uint8 spanning `0..refl_max` (default ρ 1.0) | Half the bytes; \~0.004 ρ quantisation at the default ceiling. Values above the ceiling clip — see below. |

**The 8-bit ceiling — `refl_max`**

`refl_max` sets the ρ the 8-bit range spans, so `pixel_scale = 255 / refl_max` and ρ is still `pixel / pixel_scale`. `grab()` and `frame_stream()` take it as a keyword on both camera and array handles (`?refl_max=` on the HTTP endpoint). Raise it to buy headroom for specular highlights, at proportionally coarser steps:

```python
frame = cam.grab(processing="reflectance", bit_depth=8, refl_max=1.5)   # 0..1.5 in 0..255
```

| `refl_max`      | `pixel_scale` | step     |
| --------------- | ------------- | -------- |
| `1.0` (default) | 255           | 0.0039 ρ |
| `1.5`           | 170           | 0.0059 ρ |
| `2.0`           | 127.5         | 0.0078 ρ |

> **Auto-exposure cannot fix an 8-bit clip, and using it to try makes the data worse.** ρ = π·L/E with exposure and gain divided out, so ρ is a property of the scene, not of the camera setting — measured on a live array, halving exposure moved mean ρ by 1.3%. Raising exposure to "fit" the range instead drives pixels into **sensor** saturation, which underestimates L and biases ρ **low** with no error raised (measured: max ρ 1.203 → 0.985 at 2× exposure, mean −23%). Choose the range with `refl_max`; keeping the sensor out of saturation is what AE is already for, and that protects ρ's *validity* rather than its range.

**Read `reflectance_clipped_fraction`, not the flag.** `reflectance_clipped_at_1_0` trips on a single pixel — on a real scene it reported `True` while the fraction was `0.000001`, one pixel in a million. The fraction is what tells you whether to raise the ceiling.

**`bit_depth=8` is reflectance-only.** Requesting it for `radiance` is rejected rather than served: reflectance has a fixed 0..1 range that survives an 8-bit encode, while radiance has no fixed range, so fitting it into 8 bits requires a per-frame percentile stretch whose mapping changes every frame — a picture, not a measurement.

#### Live reflectance stream (MJPEG)

`GET /api/camera/<serial>/stream-reflectance` serves 8-bit per-band reflectance as `multipart/x-mixed-replace` — an M3C as a 3-channel JPEG, an M3M as greyscale. Query params: `fps` (default 10), `jpeg_q` (default 95), `max_h` (0 = native), `band` (one named band, as above), `align` (`1` to co-register — same rules as the SDK's `align`), `refl_max` (the 8-bit encoding ceiling, as above). Each part carries `X-Chloros-Group-Id`, `X-Chloros-Frame-Id`, `X-Chloros-Timestamp-Ns`, `X-Chloros-Bands`, `X-Chloros-Pixel-Scale`, `X-Chloros-Aligned` and `X-Chloros-Reflectance-Clipped`. **Parts from different cameras carrying the same `X-Chloros-Group-Id` are the same trigger** — that is how several per-camera streams of one array are reassembled, and it is guaranteed server-side because array members are served from the synced frame group (see [One trigger per read](#one-trigger-per-read--group_id)). It returns `409` when reflectance is unavailable at connect time and ends the stream if it becomes unavailable mid-run, so a stalled stream means "no longer reflectance" rather than "still fine, just static".

> **JPEG is lossy — these pixels are a measurement.** Compression error lands directly in the reflectance values and is worst at edges, which is where material boundaries are. Quality defaults to 95 for that reason. If you need the numbers intact, use `grab(processing="reflectance")` / `frame_stream(...)`, which return the same product with no codec in the path (and `bit_depth=8` there if wire cost, not the codec, is the constraint).

> **EXIF carried through to the export.** `process()` copies the source capture's GPS block **and its ExifIFD** onto every product, so exports carry `FocalLength`, `FNumber`, `ExposureTime`, `ISO`, `DateTimeOriginal` and `CameraSerialNumber` as well as the georeferencing. `FocalLength` is what Pix4D solves ground sample distance from — without it the reconstruction falls back to a wildly wrong scale (a measured case turned a 411 m site into a 47.8 km one). The copy is deliberately not `-all:all`: IFD0's structural tags break LATTICE output, and `ExifImageWidth`/`Height` are excluded because they describe the source capture rather than the exported raster.

Capture-stage sub-flags (apply to the radiometric levels — `radiance`, `reflectance`, `display`):

| Flag                  | Default | Meaning                                                                |
| --------------------- | ------- | ---------------------------------------------------------------------- |
| `apply_calibration`   | `True`  | DSNU + flat-field + 3x3 unmix + NIST radiometric scale.                |
| `apply_white_balance` | `True`  | WB LUT. DLS-aware when a DAQ is bound to the cam.                      |
| `apply_index`         | `False` | Vegetation index evaluation.                                           |
| `index_expression`    | `None`  | Override formula. Non-empty → auto-enables index.                      |
| `annotated`           | `False` | Overlay GUI decorations (zebra/grid/peaking). Not available for `raw`. |

### `ArrayHandle`

```python
arr = proj.arrays["main_rig"]

# Single synced capture group
files = arr.capture("./out", format="tiff", processing="reflectance")
# → {"213800234": "/path/to/x.tif", "214000533": "/path/to/y.tif", ...}

# Multi-level: each serial's value becomes an ordered LIST, not a str
files = arr.capture("./out", processing="all")
# → {"213800234": ["/raw.tif", "/debayered.tif", ...], "combined": "/idx.tif"}

# Smart capture (wait for AE to settle)
result = arr.capture_smart(
    "./out", processing="reflectance",
    settle_timeout_s=5.0,
    stability_window_s=1.5,
    exposure_tolerance_pct=5.0,
)
print(result["frames"], result["settle"])

# In-memory grab: {serial: numpy array}
frames = arr.grab(processing="debayered")
frames = arr.grab(processing="radiance", with_metadata=True)

# Stream-to-disk loop
arr.stream(count=60, output_dir="./stream", fps=5, processing="raw")

# Frame-iterator (tolerates per-cam drops; great for downstream analysis pipelines)
for frames in arr.frame_stream(processing="radiance", fps=5, count=100):
    if "213800234" in frames:
        my_analysis_pipeline(frames["213800234"])

# Preview iterator (live MJPEG-equivalent; tolerates partial cycles)
counts = arr.preview_stream("./preview", fps=3.0, duration=30.0)
print(counts)  # frames written per serial
```

> **The return value is a `chloros_sdk.CapturePaths`, typed `CapturePathMap`, not `Dict[str, str]`.** `chloros_sdk.CapturePathMap` is `Dict[str, Union[str, List[str]]]`: a single-level `processing` gives each serial one path, while `processing="all"` gives it the **ordered list** of every product saved for that camera. `ArrayHandle.capture()` takes no `levels=`, and it ignores keyword arguments it does not know (`levels`, `daq`, `render_index`, `force_daq`), so pass only the ones shown here (`aligned=False` saves native files, as on `ArraySession.capture()`); use `ArraySession.capture()` for those controls. A live combined composite, if one was streaming, arrives under the extra `"combined"` key rather than under a serial. Code that assumes `str` breaks on the list form without any type checker objecting — the annotation said `Dict[str, str]` for a while after the list form shipped, which is why the alias exists. Normalise when you want the flat form:
>
> ```python
> paths = arr.capture(processing="all")
> flat = [p for v in paths.values()
>         for p in (v if isinstance(v, list) else [v])]
> ```

> **What could not be written: `.failed`.** The map `capture()` returns is a `chloros_sdk.CapturePaths` — a plain `dict` subclass, so everything above works unchanged — that also carries `.failed`: the files the backend could not write, the same entries as [`CaptureResult.failed`](#files-that-could-not-be-written--captureresultfailed) (`serial`, `level`, `error`, and `disk_full: True` on a full drive). A partial capture still returns every path that was written; on a full drive the map is empty and `.failed` says why. `.skipped` lists the per-camera skips and `.group_seq` the synced group, and `.alignment` / `.oriented` are the backend's, as on `CaptureResult`. `capture_smart()` returns them as `result["frames"].failed` and `result["failed"]`.
>
> ```python
> paths = arr.capture("./out", processing="all")
> if any(f.get("disk_full") for f in paths.failed):
>     raise SystemExit("drive full -- free space and capture again")
> ```

### Array Alignment

`ArrayHandle` exposes the full alignment surface. Profiles are session-only by default — call `export_alignment()` explicitly to persist.

```python
from chloros_sdk import AlignmentSpec

arr = proj.arrays["main_rig"]

# Defaults: ORB / affine / one synced snapshot — same as the GUI's auto-cal
result = arr.calibrate_alignment()
print(result["profile"]["rms_residual_px"])

# Custom spec for tough scenes (low-contrast canopy)
spec = AlignmentSpec(
    method="feature_orb",         # feature_orb / feature_akaze / phase_correlation / checkerboard / manual
    model="rigid",                # translation / rigid / affine / homography
    num_frames=5,
    max_features=8000,
    ratio_threshold=0.7,
    ransac_threshold_px=2.0,
    min_matches=30,
    max_reproj_err_px=2.0,
)
arr.calibrate_alignment(spec)

# Or tweak one knob at a time
arr.calibrate_alignment(num_frames=3, model="affine")

# Manual control points: each camera's pixel coordinates of the same
# features, the reference camera's included (>= 2 per camera). Every one
# of num_frames is solved from these points.
arr.calibrate_alignment(method="manual", model="rigid", control_points={
    "214701173": [[412, 300], [1630, 310], [1020, 1180]],   # reference (master)
    "214701292": [[418, 297], [1637, 306], [1027, 1177]],
})

# Inspect / manipulate
status = arr.alignment_status()
arr.tweak_alignment("214701292", dx=2.5, dy=-1.0, rotation_deg=0.0, scale=1.0)
arr.export_alignment("/tmp/main_rig_alignment.json")
arr.import_alignment("/tmp/main_rig_alignment.json", validate=True)
arr.clear_alignment()
```

#### Connect-Time Alignment

`connect_all(align=...)` can auto-align every array at connect:

```python
# Align every array with defaults
proj.connect_all(align=True)

# Per-array control
proj.connect_all(align={
    "main_rig": AlignmentSpec(num_frames=5, model="affine"),
    "side_rig": True,             # use defaults
    "verify_rig": False,          # skip
})
```

Falls back to `project.json["config"]["auto_align_on_connect"]` when unspecified.

### `SensorHandle`

A saved light sensor (DAQ-U, DAQ-M or DAQ-E), opened by `connect_all()` in the backend's [DAQ sensor pool](#daq-sensor-sessions) — the same pool `connect_daq_sensor()` and `chloros-cli daq pool-connect` use.

```python
reading = proj.sensors["Sky"].read()
if reading is not None:
    spectrum, is_saturated, integration_time, x, y, z = reading
```

* `read()` waits for the sensor's **next** spectrum — one already buffered when you call does not count — and returns `(spectrum, is_saturated, integration_time, x, y, z)`, or `None` if none arrives within 5 s. A paused stream is resumed. `spectrum` is in W/m²/nm when the sensor is calibrated.
* `.sensor` is the sensor's [`DAQSensorSession`](#daq-sensor-sessions), for everything else: `latest(n=...)`, `status()`, `record_start()` / `record_stop()`.
* `.slot_id`, `.model`, `.serial`, `.name` and `.settings` are the saved entry from `sensors.json`.

**What `connect_all` restores.** Each sensor is opened at its saved address — its COM port, Bluetooth address or DAQ-E host — and, when the project recorded the sensor's id, it must be that sensor: a different unit at that address is refused, not connected. Its saved integration time, frame averaging and auto-exposure are applied, and its cap correction:

| Saved cap                                            | Connected with                                                                                                                                                         |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A cap profile (e.g. `fov_30`)                        | That profile.                                                                                                                                                          |
| None chosen                                          | `sunshine_cosine`, the connect default, recorded as assumed (`cap_id_source=auto_default`), so processing warns. The sensors ship bare: choose the cap that is fitted. |
| `none` — chosen as **None (bare sensor)** in the GUI | No cap correction.                                                                                                                                                     |

A DAQ-E-S takes no cap profile, whatever was saved: its diffuser is part of its calibration (see [DAQ-E-S](#daq-e-s--fixed-diffuser-and-tilt-sensor)). A project saved by an earlier Chloros recorded a bare sensor as no choice, so it reconnects with `sunshine_cosine`; choose **None (bare sensor)** in the GUI once more and save the project.

A sensor another client already has open in the pool (the CLI, another script) is attached as it is, without re-applying settings, and `disconnect_all()` leaves it running; a sensor `connect_all()` opened is released. As with `connect_daq_sensor()`, the Chloros GUI is **not** part of the pool: close a sensor in the GUI before connecting the project from a script.

**Requirements and the report.** Light sensors need a running Chloros backend logged in on a paid Chloros+ tier (Copper or higher), and `connect_all()` never starts one. With none running, every saved sensor is listed under `report["sensors"]["errors"]`, saying so. A sensor the backend cannot open is listed there too, with the backend's reason; `report["sensors"]["missing"]` stays empty for light sensors.

***

## Direct Hardware (Backend-Free)

When you want zero dependency on the backend for LATTICE cameras (CI, headless robots, embedded), import `lattice_sdk` directly — it is re-exported by `chloros_sdk`. Guard on `CAMERA_AVAILABLE`: `lattice_sdk` is in the SDK wheel, but needs the Arena SDK runtime and OpenCV (`cv2`) present, and the wheel installs neither. Light sensors go through the backend — [`connect_daq_sensor()`](#daq-sensor-sessions) or a project's `proj.sensors` — with one exception, the DAQ-M band-magnitude helper [`DLS`](#daq-m-band-magnitudes--dlsband_magnitudes), which also needs `bleak`.

```python
from chloros_sdk import (
    # cameras
    LatticeCamera, CameraSettings, PRESETS, CameraPool,
    Calibration, CalibrationCoefficients, FilterModel, list_filters,
    DLS, NetworkDiagnostics, gpu_info, gpu_available,
    # discovery
    discover_cameras, discover_cameras_via_backend,
    # exceptions
    LatticeError, CameraNotFoundError, StreamError, CaptureError,
    CalibrationError, NetworkError, DLSError,
)

# Find a camera and capture in one go
cams = discover_cameras(timeout_ms=3000)
print(cams)

settings = PRESETS["high_quality"]
with LatticeCamera(serial="213800234", settings=settings) as cam:
    result = cam.capture(output_dir="./out", format="tiff")
    print(result.filepath, result.width, result.height)
```

**Presets and the trigger**

Three of the four presets **free-run**: the camera exposes continuously and a `capture()` returns the next frame. `triggered` is the exception — it arms the camera for a hardware edge on Line 2, so it captures nothing until one arrives.

| Preset         | Trigger           | Use it when                                                           |
| -------------- | ----------------- | --------------------------------------------------------------------- |
| `default`      | free-run          | general use                                                           |
| `high_speed`   | free-run          | 8-bit, 60 fps cap, short exposure                                     |
| `high_quality` | free-run          | 12-bit, no fps cap — the usual choice for stills                      |
| `triggered`    | **armed, Line 2** | the camera is wired into an M8 sync cable and something else fires it |

If you pick `triggered` (or set `trigger_mode="On"` yourself) with nothing driving Line 2, every `capture()` will time out — correctly, since you asked the camera to wait. The SDK explains this when it happens; see [SC\_ERR\_TIMEOUT during capture](#direct-hardware-backend-free).

> **Note — "GVSP probe" / `SC_ERR_TIMEOUT -1011` messages on connect are not errors.** On connect the SDK tries to negotiate **jumbo frames** (9000-byte GVSP packets) for higher throughput. On a direct point-to-point NIC link (e.g. a link-local `169.254.x.x` address) the network usually can't carry jumbo frames, so this probe times out and logs lines such as:
>
> ```
> [Network] GVSP probe: unexpected error (TimeoutError: ... SC_ERR_TIMEOUT -1011)
> [Network] GVSP probe at 9000 did not deliver a complete buffer; reverting to ICMP-chosen size
> [Network] GVSP packet size: 1500 bytes (standard)
> ```
>
> This is the **designed fallback**: the SDK automatically reverts to standard 1500-byte packets and the camera keeps connecting normally (the `[chunk-enable …]` lines that follow are part of the normal connect sequence). Capture still works.
>
> You can skip this probe, but **it is not just a log-silencer — it turns jumbo frames off.** The camera answers Don't-Fragment pings only up to 1500 bytes no matter how good your network is, so the ping test alone can never find jumbo; this probe is the only thing that can. Disable it and the camera runs standard 1500-byte packets forever, on any network:
>
> ```bash
> CHLOROS_GVSP_PROBE_FALLBACK=0   # gives up jumbo — see the warning it prints
> ```
>
> Only worth it on a network you *know* can't carry jumbo, where it saves roughly a second of connect time per camera. Since it's a real trade rather than a cosmetic one, the SDK now says so when you use it:
>
> ```
> [Network] ⚠️ GVSP probe disabled (CHLOROS_GVSP_PROBE_FALLBACK=0) — staying at
> 1500 bytes, jumbo NOT tested. … if this network does carry it, you are giving
> up ~1.45x wire ceiling. Unset the variable to test for jumbo.
> ```
>
> **Leave it alone unless you have a reason.** Left enabled, 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.
>
> If you *want* the jumbo throughput, enable jumbo end-to-end (NIC MTU 9000 + a switch that passes them), or pin it with `CHLOROS_GVSP_PACKET_SIZE_FORCE=9000` when you know the link carries it — though prefer a per-command `CHLOROS_GVSP_PACKET_SIZE_FORCE=9000 python …` over setting it permanently, since a pinned size skips the probe and stops adapting to the network in front of it. **Every** device in the path has to pass jumbo — including any PoE splitter or injector, which is the usual reason an otherwise jumbo-capable setup can't carry them.

> **`SC_ERR_TIMEOUT -1011` during `capture()` / `grab*()` is a different problem — that one is a real error.** The note above is only about `-1011` logged by the **connect-time probe**. The same error raised from a **capture** means the camera connected fine but is not sending any images:
>
> ```
> File ".../lattice_sdk/camera.py", line ..., in grab_frame_with_metadata
>   buffer = self._get_buffer(timeout)
> lattice_sdk.exceptions.CaptureError: Capture failed: ... SC_ERR_TIMEOUT -1011
> ```
>
> The give-away is a camera whose *control* channel is healthy — discovery works, settings and `[chunk-enable …]` writes all succeed — while *every* frame times out.
>
> **The usual cause is that the camera is armed for a hardware trigger.** With `trigger_mode="On"` and `trigger_source="Line2"`, the camera emits nothing at all until an electrical edge arrives on the M8 sync cable. If you have no cable driving that line, every grab waits forever. The camera is not broken and the network is fine — it is doing exactly what it was told.
>
> `CameraSettings()` and the `default` / `high_speed` / `high_quality` presets free-run, and a grab that times out while armed explains itself instead of printing a bare `-1011`. `PRESETS["triggered"]` arms Line2, by design.
>
> To force any camera to free-run:
>
> ```python
> import copy
> settings = copy.deepcopy(PRESETS["high_quality"])   # PRESETS entries are shared
> settings.trigger_mode = "Off"        # free-run; don't wait for an M8 edge
> ```
>
> If it still times out with `trigger_mode="Off"`, the camera really isn't delivering data — send us the log and `ip link show`.

#### Colour Profiles (RGB live preview) — `set_color_profile`

`LatticeCamera.set_color_profile(profile, custom_cct_k=None)` picks the display colour profile for the **live preview** on RGB cams (multispec cams ignore the setting):

| Profile       | Meaning                                                                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `raw`         | Bypass the radiometric chain entirely.                                                                                                                                        |
| `linear`      | DSNU + flat + WB, no CCM, no gamma.                                                                                                                                           |
| `natural`     | Linear + measured CCM + sRGB gamma, with the cheap finish only (chroma smoothing + highlight desaturation) — the realistic default.                                           |
| `enhanced`    | `natural` plus the full hub-parity finish (defringe, vibrance, CLAHE local contrast). Richer look at roughly **double the per-frame finish cost**, so a lower LIVE framerate. |
| `custom_temp` | `natural` but WB pinned to `custom_cct_k` Kelvin (DLS ignored; clamped to 2000–10000 K backend-side).                                                                         |

The profile is a **live-preview-only** speed/look knob: saved captures always get the full rich finish regardless of the selected profile, so picking `natural` to buy back frame time does not lower the quality of what lands on disk. An unknown profile raises `ValueError`; when a chloros backend is reachable the change is also POSTed to it so the next preview frame reflects it (direct-SDK users without a backend still get the settings mutation).

```python
with LatticeCamera(serial="214701292") as cam:   # RGB cam
    cam.set_color_profile("enhanced")            # richer look, lower LIVE fps
    cam.set_color_profile("custom_temp", custom_cct_k=5600)
```

#### Highlights (RGB display) — `set_highlights`

`LatticeCamera.set_highlights(value)` pulls the brightest, whitest pixels of the **display** render down on RGB cams — the fix for a bright white surface that renders as a flat white blob. `value` is `-100`..`0` (clamped); `0` is off, and the render is then exactly what it is without the setting. Stronger settings lower display white (to about 60% at `-100`) and widen the tone curve, so a surface that the preview's automatic brightness pushed to pure white gets its detail back.

It is a display control, but unlike saturation and contrast (which only change the live preview) it also changes what you save: the live preview and **display-level** captures follow it, so those files come out darker too (they carry `Chloros:DisplayHighlights`); radiance and reflectance exports never do, and it cannot recover sensor data that clipped — lower the exposure for that. Multispec and mono cams ignore it. The value is stored on `settings.highlights` and POSTed to a reachable chloros backend, exactly like `set_color_profile`; the CLI equivalent is `lattice highlights --set N`.

```python
with LatticeCamera(serial="214701292") as cam:   # RGB cam
    cam.set_highlights(-60)                      # 0 = off, -100 = strongest
```

#### Mono (M3M) Cameras and `Calibration`

A mono **M3M** camera (`M3M-<lens>-F<wavelength>`) is single-band: one grayscale plane, no Bayer mosaic, no 3×3 spectral-crosstalk matrix. `Calibration` recognises it and exposes an `is_mono` flag. Reflectance still applies as a per-band radiometric map (the unmix is the identity matrix), but multi-band maths on a single camera raises rather than returning nonsense:

```python
from chloros_sdk import Calibration, CalibrationError

calib = Calibration("M3M-L87-F685")
print(calib.is_mono)        # True  (False for any M3C / RGN Bayer cam)
print(calib.filter_type)    # 'mono'  (sentinel; not a real crosstalk key)

# NDVI needs two bands (Red + NIR); one mono band can't supply both.
try:
    calib.compute_ndvi(reflectance_frame)
except CalibrationError as e:
    print(e)   # "...single-band mono (M3M) camera. Combine multiple..."
```

To build a vegetation index from mono hardware, combine several M3M cams at different wavelengths into an aligned multi-band stack (see [Array Alignment](#array-alignment)) and compute the index across that stack instead of on one camera.

#### DAQ-M band magnitudes — `DLS.band_magnitudes`

`DLS(mac_address, filter_model="RGN-IMX265")` connects to a DAQ-M over Bluetooth by its own BLE MAC. It is the one light-sensor class that talks to the sensor directly rather than through the backend, so it needs what the direct camera classes need (`CAMERA_AVAILABLE`: the Arena SDK runtime and OpenCV) plus `bleak` for Bluetooth (`pip install "chloros-sdk[camera]"`, or `pip install bleak`; without it `DLS` raises `DLSError`). A DAQ-M connected elsewhere (the backend's pool, a project, the GUI) stops advertising, so release it there first. **`mac_address` is required**: there is no default, since every unit has its own, and `DLS()` without one raises `DLSError` before any connection is tried. Find the MAC with `discover_daq_sensors(transports=["ble"])` (see [Discovery](#discovery--finding-an-address-to-connect-with)) or `chloros-cli daq pool-discover --only ble`.

`DLS.band_magnitudes(spectrum=None, *, spectral_response=None)` integrates a DAQ-M spectrum (the latest reading when `spectrum` is `None`; `DLSError` if there is none yet) through a camera's three channel responses and returns `{"red": …, "green": …, "nir": …}` — the keys name the channels in that order; with an RGB camera's curves the third (`nir`) is its blue channel.

* Without `spectral_response` it uses the filter model's fleet curve (the `filter_model` the `DLS` was built with), which was measured on one unit.
* `spectral_response` takes a camera's **own** measured curves instead: a dict `{"wavelengths": [...], "R": [...], "G": [...], "B": [...]}`, as stored in that camera's calibration pack (`color_correction.spectral_response_smoothed` — RGB cameras; multispectral packs carry no such curve). A dict it cannot use falls back to the fleet curve.

```python
from chloros_sdk import DLS

# camera_curves: {"wavelengths": [...], "R": [...], "G": [...], "B": [...]}
with DLS(mac_address="AA:BB:CC:DD:EE:FF") as dls:
    reading = dls.acquire()
    fleet = dls.band_magnitudes(reading)                         # fleet curve
    own = dls.band_magnitudes(reading,
                              spectral_response=camera_curves)   # the camera's own
```

The CLI's `chloros-cli lattice dls --camera SERIAL` does the same through the backend, finding the camera's curve in its loaded or cached calibration pack, and says whose curve it used. Over HTTP that is `POST /api/dls/cli-read` with `mac` (required: without it the reply is HTTP 400, `code` `MAC_REQUIRED`) and `camera_serial` in the body; the reply's `band_magnitudes_source` is `camera <serial>` when that camera's own curve was used, or `model <filter>` for the fleet curve (a camera with no curve: not RGB, or no pack loaded or cached).

***

## Exceptions

Catch the base class to handle "anything Chloros went wrong":

```python
import chloros_sdk

try:
    chloros_sdk.process_folder("/path/to/folder")
except chloros_sdk.ChlorosAuthenticationError:
    print("Run `chloros-cli login` first.")
except chloros_sdk.ChlorosLicenseError:
    print("Chloros+ subscription required.")
except chloros_sdk.ChlorosError as e:
    print(f"Chloros error: {e}")
```

> `ChlorosAuthenticationError` and `ChlorosConfigurationError` are attributes of `chloros_sdk` (and of `chloros_sdk.exceptions`) but not in `__all__`, so `from chloros_sdk import *` does not bring them in: import them by name. The `ChlorosError` family is raised by `ChlorosLocal` and the functions built on it (`process_folder()`, `process_lattice_capture()`); the smart-connect surface raises `ChlorosConnectError`.

Hierarchy:

```
ChlorosError
├── ChlorosBackendError           (backend binary not found / failed to start)
├── ChlorosConnectionError        (HTTP transport failure; no backend running
│                                  with auto_start_backend=False)
├── ChlorosLicenseError           (403 PLAN_UPGRADE_REQUIRED: plan below Copper)
├── ChlorosAuthenticationError    (401 AUTH_REQUIRED: not logged in)
├── ChlorosConfigurationError     (bad configure() inputs)
└── ChlorosProcessingError        (pipeline failed; create/import refused)
    └── ChlorosProjectFilesMissingError  (open_project(): none of the
                                  project's source files found, even after
                                  the relink; .missing_roots, .audit)

ChlorosConnectError                (the smart-connect surface: connect_*, attach_array,
                                    list_*, discover_*, every CameraSession /
                                    ArraySession / DAQSensorSession method,
                                    RecorderHandle, ContinuousHandle,
                                    disconnect_all(), and analyze_array_network()
                                    when no backend answers; 401 and 403 included.
                                    Derives from plain Exception, NOT from
                                    ChlorosError, so `except ChlorosError` will
                                    not catch it. .warning: a warning the
                                    backend sent beside its error (also at the
                                    end of the message); .recording_closed: the
                                    recording a failed DAQ-E restart closed;
                                    both None otherwise)

FrameFetchError (RuntimeError)     (grab() / frame_stream() refusals; .status,
                                    .body, .errors)
ValueError                         (capture() arguments: PNG/JPEG with a level they
                                    cannot hold; a bad packed=)
FileNotFoundError / ImportError    (open_project(): no such folder / no project
                                    loaders)
RuntimeError                       (CameraHandle / ArrayHandle: a backend refusal)

lattice_sdk exceptions:
LatticeError
├── CameraNotFoundError
├── CameraConnectionError
├── StreamError
├── CaptureError
├── CalibrationError
├── NetworkError
└── DLSError
```

***

## End-to-End Examples

### 1. Process a Folder with a Custom Progress Bar

```python
from chloros_sdk import ChlorosLocal

def progress(percent, message):
    bar = "#" * (percent // 5)
    print(f"\r[{bar:<20s}] {percent:3d}% {message}", end="", flush=True)

with ChlorosLocal() as cl:
    cl.create_project("FieldA_2026-05-26")
    cl.import_images("C:/DroneImages/Flight001", recursive=True)
    cl.configure(
        debayer="High Quality (Faster)",
        vignette_correction=True,
        reflectance_calibration=True,
        indices=["NDVI", "GNDVI", "OSAVI", "SAVI"],
        export_format="TIFF (16-bit)",
    )
    cl.process(progress_callback=progress)
print()
```

### 2. Live LATTICE Array → Reflectance + DAQ Reference

```python
import chloros_sdk

# Open a paired sensor first so the array's reflectance step has an
# absolute reference. Smart-detect picks USB / BLE / ETH automatically.
with chloros_sdk.connect_daq_sensor() as daq:
    with chloros_sdk.connect_array([
            "213800234", "214000533", "214701288", "214701292"
    ]) as arr:
        # Smart capture: wait for AE to settle, then snap
        arr.capture("./out", processing="reflectance", smart=True)

        # Record the corresponding DAQ frames as ground truth
        daq.record_start(output_dir="./out", device_name="sky-reference")
        # ... do whatever capture campaign ...
        info = daq.record_stop()
        print(info["path"], info["rows"])
```

### 3. Project-Driven Capture Campaign

```python
import time, chloros_sdk

with chloros_sdk.open_project("/home/user/Chloros Projects/Field_A") as proj:
    report = proj.connect_all(verbose=True, align=True)
    if report["arrays"]["errors"]:
        raise SystemExit(f"Array(s) failed to connect: {report['arrays']['errors']}")

    rig = proj.arrays["main_rig"]

    # Re-align right before the campaign
    rig.calibrate_alignment(num_frames=5)
    rig.export_alignment("./alignments/main_rig.json")

    # 50 sequential single-frame captures at 2 fps
    for i in range(50):
        frames = rig.capture(
            output_dir=f"./out/frame_{i:04d}",
            processing="reflectance",
            apply_calibration=True,
            apply_white_balance=True,
        )
        time.sleep(0.5)

    # End-of-day: process the captured folder. process() accepts only
    # mode/wait/progress_callback/poll_interval — indices come from the
    # project's saved config (or set them via ChlorosLocal.configure()).
    proj.process()
```

### 4. Multi-Camera Frame-Stream → NumPy Pipeline

```python
import chloros_sdk
import numpy as np

with chloros_sdk.open_project("/path/to/proj") as proj:
    proj.connect_all()
    rig = proj.arrays["main_rig"]

    for frames in rig.frame_stream(
            processing="radiance",
            fps=5.0, count=300,
            apply_calibration=True,
            apply_white_balance=True):
        # frames is {serial: numpy_array}; cams not delivering this tick are omitted
        for serial, frame in frames.items():
            print(serial, frame.shape, frame.dtype, frame.mean())
```

### 5. Headless Direct-Hardware (No Backend) Capture Script

```python
from chloros_sdk import LatticeCamera, PRESETS, discover_cameras

cams = discover_cameras(timeout_ms=3000)
print(f"Found {len(cams)} cams")

settings = PRESETS["high_quality"]
for c in cams:
    with LatticeCamera(serial=c.serial, settings=settings) as cam:
        result = cam.capture(output_dir="./out", format="tiff")
        print(c.serial, result.filepath)
```

### 6. Capability Probe Before Connecting a 4-Cam Array

```python
import chloros_sdk

serials = ["214701288", "213800234", "214000533", "214701162"]

probe = chloros_sdk.analyze_array_network(
    master_serial=serials[0],
    slave_serials=serials[1:],
    width=2048, height=1536,
    pixel_format="BayerRG12",
)

if probe["status"] == "ok":
    arr = chloros_sdk.connect_array(
        serials, width=2048, height=1536, pixel_format="BayerRG12")
elif probe["status"] == "auto_capped_fps":
    r = probe["recommended"]
    print(f"Keeping resolution; capping trigger rate at "
          f"{r['recommended_target_fps']} fps")
    arr = chloros_sdk.connect_array(
        serials, width=2048, height=1536, pixel_format="BayerRG12",
        target_fps=r["recommended_target_fps"])
elif probe["status"] == "auto_shrunk":
    r = probe["recommended"]
    print(f"Auto-shrinking to {r['out_width']}x{r['out_height']} "
          f"binning={r['binning']} for sim-sync")
    arr = chloros_sdk.connect_array(
        serials,
        width=r["width"], height=r["height"],     # before binning
        pixel_format=r["pixel_format"], binning=r["binning"])
elif probe["status"] == "needs_force_slip":
    print("Wire can't sustain sim-sync; falling back to slip mode")
    arr = chloros_sdk.connect_array(
        serials, force_tier="slip-emit-and-capture")
else:
    raise RuntimeError(f"Probe error: {probe.get('error')}")
```

### 7. Capture Recipe Equivalent (Pure Python)

`run_project_recipe()` runs a CLI recipe as it is (see [Project Folder & Recipes](#project-folder--recipes)). Written out in Python instead, the same steps are:

```python
import time, chloros_sdk

with chloros_sdk.open_project("/path/to/proj") as proj:
    proj.connect_all()
    cam = proj.cameras["FrontLeft"]
    rig = proj.arrays["main_rig"]
    sky = proj.sensors["Sky"]

    # apply: connect_all() applied each camera's saved settings. CameraHandle
    # has no settings method; a CameraSession on the same pooled camera does
    # (it is borrowed, so it never releases the camera)
    chloros_sdk.connect_camera(cam.serial).set_settings(
        exposure_time=5000, gain=6.0)

    # wait
    time.sleep(2)

    # capture
    cam.capture("pose_a/", format="tiff", processing="radiance")

    # stream
    rig.stream(count=60, fps=5, output_dir="stream/", processing="raw")

    # sensor read
    print(sky.read())
```

***

## MCP Server (AI Assistants)

`chloros-mcp` lets an AI assistant that speaks the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), such as Claude Desktop, Claude Code or Cursor, drive Chloros: process imagery (create a project, import a folder of captures, choose settings, process, report what the run exported) and run LATTICE cameras, arrays and DAQ light sensors (connect, preview, set exposure and colour, capture, record, update firmware). Its tools cover what this SDK does. You ask in plain language and the assistant calls the server's tools:

```
You:  Process the flight in D:\Flights\2026-10-17 to reflectance and NDVI.

The assistant calls:
  create_project          {"project_name": "Flight_2026-10-17"}
  import_images           {"folder_path": "D:\\Flights\\2026-10-17"}
  configure_processing    {"indices": ["NDVI"]}
  start_processing        {}
  get_processing_status   {}      (every 30-60 s until its state is "finished")

You:  Show me what the array sees, then capture reflectance every 10 seconds
      for 5 minutes.

The assistant calls:
  list_devices            {}
  get_camera_preview      {"array_id": "array-1779862544497"}
  start_capture_run       {"array_id": "array-1779862544497", "mode": "interval",
                           "interval_s": 10, "duration_s": 300,
                           "processing": "reflectance"}
  get_job_status          {"job_id": "..."}   (until its state is "finished")
```

The server is built on this SDK: the processing tools call [`ChlorosLocal`](#image-processing--chloroslocal) and the hardware tools the [smart-connect calls](#smart-connect-for-lattice-cameras), [DAQ sessions](#daq-sensor-sessions), `ChlorosProject` and the [camera utilities](#camera-utilities), all talking to the same backend the Chloros app uses. Its requests carry `X-Chloros-Client: sdk`, so the backend applies the SDK's sign-in and plan checks, and the SDK's rules come with it (Texture Aware is refused for LATTICE captures, for example).

### Install

The server ships in the `chloros-sdk` package; there is nothing else to install. The SDK installs a `chloros-mcp` command, which is the same as `python -m chloros_sdk.mcp_server`:

```bash
pip install chloros-sdk        # not needed where the Chloros installer set up the SDK (Step 2)
chloros-mcp --help
```

* **Windows:** the Chloros installer pip-installs the SDK into your Python, which puts `chloros-mcp.exe` in that Python's `Scripts` folder.
* **Linux (.deb):** the package installs the SDK for the system `python3` and puts the `chloros-mcp` command in `/usr/bin`, so it is on every user's `PATH`. In a virtualenv, `pip install /usr/lib/chloros/sdk/chloros_sdk-*.whl` adds `chloros-mcp` to the virtualenv's `bin`.

The server uses only the standard library on top of the SDK (Python 3.7+). An MCP client starts it and talks to it over stdin/stdout; you do not run it yourself, except with `--help`.

### Client Setup

**Claude Desktop:** add the server to `claude_desktop_config.json` (on Windows `%APPDATA%\Claude\claude_desktop_config.json`; **Settings > Developer > Edit Config** opens it), then restart Claude Desktop:

```json
{
  "mcpServers": {
    "chloros": {"command": "chloros-mcp"}
  }
}
```

**Claude Code:**

```bash
claude mcp add chloros -- chloros-mcp
```

**Cursor:** the same `mcpServers` entry as Claude Desktop, in `~/.cursor/mcp.json` (every project; `%USERPROFILE%\.cursor\mcp.json` on Windows) or `.cursor/mcp.json` in one project.

Options go in `args`, or after the command for Claude Code (`claude mcp add chloros -- chloros-mcp --no-auto-start`). To use a particular Python's SDK instead of the `chloros-mcp` on the `PATH`, run the module with that Python (its full path as `command` if it is not the first `python3` on the `PATH`):

```json
{
  "mcpServers": {
    "chloros": {"command": "python3", "args": ["-m", "chloros_sdk.mcp_server"]}
  }
}
```

A client starts the server without your shell, so if it reports that the server failed to start, `chloros-mcp` is probably not on the `PATH` the client sees. Give the full path instead (`where chloros-mcp` on Windows, `which chloros-mcp` on Linux, where the .deb's is `/usr/bin/chloros-mcp`), or run the module with the Python that has the SDK.

### Options

| Option               | Default                   | What it does                                                                                                                                                                                                                                                                     |
| -------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--backend-url URL`  | `http://127.0.0.1:5000`   | The Chloros backend to use.                                                                                                                                                                                                                                                      |
| `--no-auto-start`    | off                       | Never start a backend: use one already running, such as the Chloros app's, the Linux backend service, or a tunnel to another machine's (see [Remote-Backend Mode](#remote-backend-mode-pip-only-host-via-tunnel); folder paths must then name the same folder on both machines). |
| `--backend-exe PATH` | where Chloros installs it | The backend to start when none is running, for a Chloros installed where the SDK does not look.                                                                                                                                                                                  |
| `--log-level LEVEL`  | `WARNING`                 | `DEBUG`, `INFO`, `WARNING` or `ERROR`. Logs go to stderr, which most clients show in their MCP log; stdout carries only protocol messages.                                                                                                                                       |

### Tools

Every tool's arguments are those of the SDK call it wraps; the client lists each one with its full schema. Paths are absolute.

**Processing**

| Tool                    | SDK call                                     | What it does                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_project`        | `ChlorosLocal.create_project`                | Creates a project and makes it the open project, which the processing tools act on. A plain name creates the folder in the default project folder; an absolute path creates it there.                                                                                                                                                         |
| `open_project`          | `ChlorosLocal.open_project`                  | Opens a saved project and makes it the open project. A moved project's paths are re-pointed at the folder it is in now; `relink_folder` (absolute) names the folder its other missing files are in now. Returns `source_files` and `image_count`. None found: an error listing where they were and naming `relink_folder`; nothing is opened. |
| `import_images`         | `import_images`                              | Imports Survey3 `.RAW`+`.JPG` pairs, LATTICE `.tif` captures and DAQ `.daq` recordings; returns `count` (images) and `scan_count` (recordings).                                                                                                                                                                                               |
| `configure_processing`  | `configure`                                  | Changes the settings passed and no others (values: [Supported Values](#supported-values)); `custom_settings` sends a whole configuration as given.                                                                                                                                                                                            |
| `get_project_settings`  | `get_config`                                 | Reads the open project's saved processing, export and index settings.                                                                                                                                                                                                                                                                         |
| `start_processing`      | `process(wait=False)`                        | Starts processing the open project and returns at once.                                                                                                                                                                                                                                                                                       |
| `get_processing_status` | `get_status`                                 | Reports `state` (`idle`, `starting`, `processing` or `finished`) and progress; once finished, the run's `summary`, `export_check_failure` when the exports could not be verified, and `image_failure` when images were lost: the other products are written; report the run as failed.                                                        |
| `process_folder`        | `process_folder` / `process_lattice_capture` | Creates a project for a folder, imports it, configures and starts the run in one call (`lattice: true` for LATTICE captures). While a run is in flight it refuses before it creates anything, and the backend refuses a project change from any tool then too.                                                                                |
| `export_light_sensor`   | `export_light_sensor`                        | Writes calibrated `.daq` and `.csv` files for the project's light-sensor recordings without processing images, fetching the factory calibration from MAPIR Cloud when it is not cached (see [Light-Sensor Recordings](#light-sensor-recordings--calibrated-daq--csv)).                                                                        |
| `read_image_audit_tags` | `read_image_audit_tags`                      | Reads a processed image's Chloros audit metadata (source, calibration, stages applied).                                                                                                                                                                                                                                                       |

**Cameras and arrays**

| Tool                                                                                                                                                     | SDK call                                                                                                                            | What it does                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_devices`                                                                                                                                           | `list_cameras`, `list_arrays`, `list_daq_sensors`                                                                                   | What is connected now, in any client, each with `connected_here`; plus the server's running jobs.                                                                                                                                                                                           |
| `discover_devices`                                                                                                                                       | `discover_lattice_cameras`, `discover_daq_sensors`                                                                                  | Cameras and light sensors that could be connected.                                                                                                                                                                                                                                          |
| `get_device_status`                                                                                                                                      | `CameraSession.status`, `ArraySession.status` / `capability`, `DAQSensorSession.status`                                             | One camera's, array's (with its capability and health) or light sensor's live state.                                                                                                                                                                                                        |
| `analyze_array_network`                                                                                                                                  | `analyze_array_network`                                                                                                             | What this host and network can carry for a proposed array.                                                                                                                                                                                                                                  |
| `connect_camera` / `connect_array`                                                                                                                       | `connect_camera` / `connect_array`                                                                                                  | Connect a camera, or a synchronized array (master first).                                                                                                                                                                                                                                   |
| `connect_project_devices`                                                                                                                                | `open_project(...).connect_all`                                                                                                     | Connect every device a saved project remembers, with its settings.                                                                                                                                                                                                                          |
| `disconnect_device`                                                                                                                                      | `disconnect` / `force_disconnect`                                                                                                   | Release a camera, array or light sensor (see Behaviour). `keep_settings: true` on an array saves each camera's settings into its own memory, `clear_settings: true` resets that memory (its result carries `camera_memory`).                                                                |
| `disconnect_project_devices`, `align_project_arrays`, `capture_project_devices`                                                                          | `disconnect_all`, `align_arrays`, `capture_all`                                                                                     | The project's devices, together.                                                                                                                                                                                                                                                            |
| `read_camera_settings` / `set_camera_settings`                                                                                                           | `CameraSession.read_nodes` / `set_settings`                                                                                         | Read or write camera settings, by friendly name or GenICam node name.                                                                                                                                                                                                                       |
| `set_array_frame_rate`                                                                                                                                   | `ArraySession.set_target_fps`                                                                                                       | Fix an array's rate, or hand it back to the automatic rate.                                                                                                                                                                                                                                 |
| `capture_camera` / `capture_array`                                                                                                                       | `CameraSession.capture` / `ArraySession.capture`                                                                                    | One capture (`fastest` and `wait_for_exposure` are `capture_fastest` and the settled-exposure capture). With no `output_dir` it saves into the open project's `captures` folder, and the files join the project (held back until a processing run ends); the reply's `project_add` says so. |
| `start_capture_run`                                                                                                                                      | `ArraySession.continuous`, `capture_repeated`                                                                                       | Continuous or interval captures, as a job.                                                                                                                                                                                                                                                  |
| `start_array_recording`                                                                                                                                  | `ArraySession.record` / `burst`                                                                                                     | A combined-index video, or a raw burst, as a job.                                                                                                                                                                                                                                           |
| `build_burst_video`                                                                                                                                      | `ArraySession.build_video`                                                                                                          | Reprocess a burst into calibrated video, as a job.                                                                                                                                                                                                                                          |
| `get_job_status` / `stop_job`                                                                                                                            |                                                                                                                                     | Follow or stop a job.                                                                                                                                                                                                                                                                       |
| `get_camera_preview`                                                                                                                                     |                                                                                                                                     | Each camera's live preview, returned as an image.                                                                                                                                                                                                                                           |
| `grab_frames`                                                                                                                                            | `ArraySession.grab`, `CameraHandle.grab`                                                                                            | One frame (or one synchronized set) at a processing level, without saving: per-plane statistics and a PNG of each.                                                                                                                                                                          |
| `calibrate_array_alignment`, `get_array_alignment`, `clear_array_alignment`, `nudge_array_alignment`, `export_array_alignment`, `import_array_alignment` | `ArrayHandle.calibrate_alignment`, `alignment_status`, `clear_alignment`, `tweak_alignment`, `export_alignment`, `import_alignment` | An array's alignment.                                                                                                                                                                                                                                                                       |

**Light sensors**

| Tool                                                                                                                                                                         | SDK call                                                                                   | What it does                                                                                                                                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connect_light_sensor`                                                                                                                                                       | `connect_daq_sensor`                                                                       | Connect a DAQ-U, DAQ-M or DAQ-E (`cap_id` sets its cap correction).                                                                                     |
| `get_light_sensor_reading`                                                                                                                                                   | `DAQSensorSession.latest`                                                                  | The latest readings: time stamp, saturation, spectrum range and peak, and the spectrum averaged into wavelength bins (`full_spectrum` for every point). |
| `set_light_sensor_streaming`                                                                                                                                                 | `stream_start` / `stream_stop`                                                             | Start or stop the stream.                                                                                                                               |
| `start_light_sensor_recording` / `stop_light_sensor_recording`                                                                                                               | `record_start` / `record_stop`                                                             | Record a `.daq` file, as a job; `duration_s` stops it by itself.                                                                                        |
| `set_light_sensor_cap`                                                                                                                                                       | `DAQSensorSession.set_cap`                                                                 | The cap correction (`none` for a bare sensor).                                                                                                          |
| `get_light_sensor_bindings` / `set_light_sensor_bindings`                                                                                                                    | `daq_bindings` / `set_daq_bindings`                                                        | Which sensor feeds each camera's and array's reflectance.                                                                                               |
| `get_light_sensor_band_presets` / `get_light_sensor_reflectance`                                                                                                             | `daq_band_presets` / `light_sensor_reflectance`                                            | The band sets, and two streaming sensors' Ambient + Object reflectance and indices.                                                                     |
| `get_light_sensor_device_info`, `set_light_sensor_network`, `set_light_sensor_auto_stream`, `enable_light_sensor_ptp`, `reboot_light_sensor`, `update_light_sensor_firmware` | `device_info`, `set_network`, `set_auto_stream`, `enable_ptp`, `reboot`, `update_firmware` | A DAQ-E's own settings, saved in the unit.                                                                                                              |

**Camera utilities** ([Camera Utilities](#camera-utilities))

| Tool                                                      | SDK call                                                                             | What it does                                                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `get_camera_color_settings` / `set_camera_color_settings` | `camera_color_profile`, `camera_color_adjust`, `camera_highlights` and their setters | An RGB camera's display colour: profile and colour temperature, saturation / contrast, highlights. |
| `run_camera_white_balance` / `set_camera_white_balance`   | `camera_white_balance_once` / `set_camera_white_balance`                             | One-shot white balance, or auto / off / fixed ratios.                                              |
| `list_camera_presets` / `apply_camera_preset`             | `camera_presets` / `apply_camera_preset`                                             | Camera presets.                                                                                    |
| `list_filter_models`                                      | `camera_filter_models`, `camera_filter_model_info`                                   | The filter models, or one by name.                                                                 |
| `get_camera_firmware_status` / `update_camera_firmware`   | `camera_firmware_status` / `update_camera_firmware`                                  | Firmware versions, and a flash (a job by default).                                                 |
| `get_camera_power_info` / `set_camera_power`              | `camera_power_probe`, `sleep_camera`, `wake_camera`                                  | Power and thermal state; sleep or wake.                                                            |
| `calibrate_camera_with_target`                            | `calibrate_camera_with_target`                                                       | Coefficients from a calibration target in view.                                                    |
| `get_network_adapters` / `fix_network_settings`           | `network_adapters` / `fix_network_settings`                                          | The camera network adapters, an estimate, and the fix (Administrator only).                        |
| `apply_vignette_correction`                               | `apply_vignette_correction`                                                          | Vignette-correct a folder of images.                                                               |
| `read_dls`                                                | `read_dls`                                                                           | One DLS reading.                                                                                   |
| `probe_system` / `get_system_info`                        | `probe_system` / `system_info`                                                       | The host's hardware and runtime.                                                                   |

**Transient cameras, alignment profiles and indices** ([Transient Arrays, Alignment Profiles & Indices](#transient-arrays-alignment-profiles--indices)). Every tool here that opens cameras takes `keep_settings` / `clear_settings` (default false): see [Camera memory](#camera-memory--keep_settings--clear_settings).

| Tool                                                        | SDK call                                                | What it does                                                                                |
| ----------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `start_camera_continuous` / `start_multi_camera_stream`     | `start_camera_continuous` / `start_multi_camera_stream` | Record one camera, or stream several in sync, as a job (`duration_s` stops it by itself).   |
| `capture_cameras_transient`                                 | `capture_cameras_transient`                             | One synchronized capture without connecting an array.                                       |
| `test_array_sync` / `detect_array_master`                   | `test_array_sync` / `detect_array_master`               | The trigger sync check, and which cameras are on the sync line.                             |
| `analyze_array_models`                                      | `analyze_array_models`                                  | What an array of these models would get on this network.                                    |
| `calibrate_alignment_profile`                               | `calibrate_alignment_profile`                           | Solve and save an alignment profile file (`options` holds the finer solver options).        |
| `capture_aligned_multiband` / `start_aligned_stream`        | `capture_aligned_multiband` / `start_aligned_stream`    | An aligned multi-band image, or a stream of them as a job.                                  |
| `read_alignment_profile` / `reorder_alignment_profile`      | `alignment_profile_info` / `reorder_alignment_profile`  | A profile file's contents; its band order and enabled cameras.                              |
| `list_index_presets`, `compute_index`, `capture_live_index` | `index_catalog`, `compute_index`, `capture_live_index`  | Index presets and gradients; an index over a multi-band TIFF; capture-to-index in one step. |

**Time sync, project folder and recipes** ([PTP Grandmaster](#ptp-grandmaster--time_sync_status), [Project Folder & Recipes](#project-folder--recipes))

| Tool                                                                 | SDK call                                                         | What it does                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_time_sync_status`                                               | `time_sync_status`, `time_sync_peers`, `time_sync_cameras`       | The PTP grandmaster's health, its peers and each array camera's PTP state.                                                                                                                                                                                                       |
| `restart_time_sync` / `set_time_sync_priority`                       | `restart_time_sync` / `set_time_sync_priority`                   | Restart it; set its priorities.                                                                                                                                                                                                                                                  |
| `get_project_folder` / `set_project_folder` / `reset_project_folder` | `project_folder` / `set_project_folder` / `reset_project_folder` | The folder new projects are made in.                                                                                                                                                                                                                                             |
| `run_project_recipe`                                                 | `run_project_recipe`                                             | Run a saved project's recipe, as a job with its log. Checked first: a recipe with an error is refused and runs nothing; unconnected arrays / sensors are warned about (it does not connect them: `connect_project_devices` first). `dry_run` returns the check and runs nothing. |

There is no tool to open a saved project for processing: each processing job starts with `create_project` (or `process_folder`).

### Requirements

* **Chloros installed on the same computer.** The Chloros backend does the processing. The server can instead use a backend reached through a tunnel (`--backend-url` with `--no-auto-start`, see [Options](#options)).
* **Signed in on that computer**, in the Chloros app or with `chloros-cli login`. The server cannot sign in for you: a tool called while signed out answers "Not signed in to Chloros" with the backend's reason, and the assistant tells you.
* **Any paid Chloros+ tier (Copper or higher).** The server is SDK access, and the free Iron tier has none: a tool called on the free tier answers "Not available on this Chloros plan" with the backend's reason.
* Python 3.7 or newer with the SDK, and an MCP client that starts local (stdio) servers.

### Behaviour

* **The backend.** Launching the server or listing its tools starts nothing; the first tool call connects. If the Chloros app (or the Linux backend service) is running, the server uses its backend and leaves it running. If no backend is running, the server starts the installed one, window-less. When the server exits (you quit the client, or it restarts the server), it stops the capture jobs and light-sensor recordings it started and releases the devices it connected; the backend keeps running, so an unfinished processing run carries on to its end, and it stops itself after 30 minutes with nothing using it. With `--no-auto-start` the server never starts a backend: a tool called with none running asks you to open the Chloros app, and the next call after you do connects.
* **One open project.** The backend has one open project, shared with the Chloros app when the app is open, so do not work on another project in the app while the assistant works.
* **Only the settings passed change.** `configure_processing` leaves every setting it is not given at its saved value (the SDK's `configure()` resets debayer, vignette correction, reflectance calibration, PPK and export format to their defaults when they are not passed; the server fills them in from the project). If it cannot read the project's saved settings, it changes nothing and says so, unless all five are given. `indices` replaces the project's index list. The result lists what was sent as `settings_sent`, and names under `warnings` any index the camera's bands cannot make.
* **Processing is start-then-poll.** `start_processing` returns as soon as the run starts, which then takes minutes to hours, and the assistant follows it with `get_processing_status`. `state` is `idle` (nothing processing), `starting` (the backend has not reported the run yet, for up to 20 s), `processing`, or `finished`, with the run's [summary](#post-run-summary--hints): what it exported, and hints when it exported less than expected (no images, no calibration target found). Products are written under the project folder, as from the app. `start_processing` is refused while a run is in progress, and a backend that stops answering is reported as an error, not as a finished run.
* **What the assistant sees.** The SDK's warnings come back in the tool result under `warnings`, and failures (signed out, plan, a bad path) as error text it can read and pass on to you. A list longer than 20 items is cut to its first 20, with its full length as `<key>_total`. Paths must be absolute.
* **Devices are shared.** Cameras, arrays and light sensors live in the backend, so the assistant can drive one the Chloros app connected, and what it changes shows in the app. `disconnect_device` releases what the server connected; a device another client connected (the app, `chloros-cli`, a script, another `chloros-mcp`) is released only with `force: true`, which is the SDK's `force_disconnect`, and the refusal names who connected it when the backend knows; a device the backend does not hold at all is reported not connected (`released: false`, `connected: false`, nothing to release). A recording or stream the backend runs leads its `get_job_status` view with `counts` — `frames_written`, `frames_dropped`, `frames_failed`, `drop_reason` (frame groups for a multi-camera stream) — and a one-line `summary` ("220 frames written, 55 dropped, 0 failed: ..."), while it runs and, finished, its final numbers; another client's listing of it (`other_clients_jobs`) carries the same (`list_cameras()`, `list_arrays()` and `list_daq_sensors()` carry each device's `connected_by`: `client`, `label`, `name`, `at`). Each `chloros-mcp` names itself to the backend as `chloros-mcp (pid N)` (`chloros_sdk.connect.CLIENT_LABEL`, sent as `X-Chloros-Client-Label`; any SDK script may set it). Stopping another client's light-sensor recording takes `force` too.
* **Long work is a job.** `start_capture_run`, `start_array_recording`, `build_burst_video`, `start_light_sensor_recording`, `start_camera_continuous`, `start_multi_camera_stream`, `start_aligned_stream`, `run_project_recipe`, and any capture, solve or index asked for `background`, return a `job_id` at once; `get_job_status` follows it and `stop_job` ends it. A run continues until stopped unless you give it `max_captures`, `duration_s` (or, for a burst, `max_frames`); `min_free_gb` refuses to start when the drive has less free space. No limit is applied unless you set one. A recording or stream the backend runs (`start_camera_continuous`, `start_multi_camera_stream`, `start_aligned_stream`) keeps the backend's job id, so another `chloros-mcp` — one started later — finds it by that id: `get_job_status` follows it (and lists such jobs as `other_clients_jobs`, from `GET /api/camera/cli-jobs`, each with `started_by`), and `stop_job` stops it only with `force: true`. Any other job (a capture run, an array recording or burst, a background capture) runs in the `chloros-mcp` that started it, and only that server knows it: another one asked for it says so. A stopped one reads `stopping` while it writes out its queue, then `finished` with its final counts, for 10 minutes and from any `chloros-mcp`: the one that started it sees another's forced stop the same way. `get_job_status` never waits for a stop: during one (its own `stop_job`'s, another client's, or the stop that releases the cameras of a job that ended by itself) it answers at once with `stopping` and the live counts, and `stop_job` of a job already stopping says so. A job that ended says why in `stop_reason`: its own reason (`no_frames`, `disk_full`, `member_missing`, or for an array continuous run `count`, `duration`, `array_gone`), `limit reached` only when its counts show its `count` (or a burst's `max_frames`, a recording's `duration_s`) reached, `error`, `stopped` (with `stopped_by`) when a client stopped it, else `finished`.
* **Where captures go.** To the open project's `captures` folder, where the app saves them, unless `output_dir` is given.
* **Images.** `get_camera_preview` and `grab_frames` return images the assistant can look at, beside their JSON. `grab_frames` images are contrast-stretched for viewing; its statistics are the real values.
* **When the server exits**, jobs it started stop and a light-sensor recording it started is closed. If the server started the backend, it also releases the devices it connected before stopping the backend; in the app's backend they stay connected.
* **Protocol.** stdio only (no HTTP endpoint), tools only (no resources or prompts), text and image results, MCP protocol versions 2024-11-05 to 2025-11-25.

**What is left out.** Signing in or out (the account is yours; the server cannot sign in), and stopping a backend the server did not start. Everything else this SDK does with processing and hardware has a tool. (A DAQ-E's provisioning -- its name, auth token, OTA password, signature requirement, factory reset -- and the direct DAQ servers are `chloros-cli`'s alone, in the SDK too: a wrong name or token locks every Chloros install out of the unit.)

***

## Backend Auto-Start

The smart-connect entry points — `connect_camera`, `connect_array`, `connect_daq_sensor`, `discover_lattice_cameras` and `discover_daq_sensors` — are thin HTTP clients that assume a backend is listening on `127.0.0.1:5000` (the smart-connect surface's default URL). When the GUI or CLI is already running, one is. From a bare script, there might not be — so these functions **auto-start the bundled backend binary** (window-less, the same way `ChlorosLocal` does) before their first call, then wait up to 60 s for it to come up. `list_cameras()`, `list_arrays()`, `list_daq_sensors()`, `attach_array()` and `analyze_array_network()` never start one.

Rules:

* **Only a local URL is ever spawned.** A `backend_url` pointing at `localhost` / `127.0.0.1` / `[::1]` is eligible; any other host is assumed to be someone else's machine and is never spawned.
* **A backend that exits before it answers ends the wait.** The call raises at once with the exit code, the command it ran and the last lines the backend printed, instead of waiting out the 60 s. Exit code 98 is the exception: another backend already holds the port or lock file (the Chloros app's, the backend service, or another script's that is still starting), so the call keeps waiting for that one to answer. `ChlorosLocal` does the same.
* **The backend is left running for reuse** (same as the CLI) — there's no implicit shutdown when your script exits. Re-running the script reuses the live backend.
* **Opt out with `auto_start_backend=False`** on any of those calls (e.g. when you've pointed at a remote backend, or you manage the backend lifecycle yourself).

```python
import chloros_sdk

# Fresh shell, no backend running, no GUI open — this still works:
with chloros_sdk.connect_camera("213800234") as cam:   # spawns the backend
    cam.capture("output/")

# Remote backend (via tunnel — see Remote-Backend Mode): don't spawn one locally
arr = chloros_sdk.connect_array(serials,
                                backend_url="http://127.0.0.1:5000",
                                auto_start_backend=False)
```

If the bundled binary can't be located or started, the subsequent HTTP call raises an actionable, **platform-aware** `ChlorosConnectError` rather than a bare connection-refused trace — on Windows it points you at the desktop app or a `chloros-cli` command; on Linux (no GUI) it points you at a `chloros-cli` command or the `.deb`.

***

## Environment & Headers

The SDK marks every backend HTTP call with `X-Chloros-Client: sdk`. The backend applies SDK/CLI licensing rules (login **and** a paid Chloros+ plan required) rather than the GUI free-tier path. This is set automatically at import time — you don't need to do anything.

The header is added to every `requests` / `urllib` call whose URL contains `localhost` or `127.0.0.1`, on any port — your own local services included — and replaces a value you set yourself. Calls to other hosts are left untouched.

Override the backend URL by passing `backend_url=` (`ChlorosLocal` takes `backend_url=` or `api_url=`; `process_folder()` and `process_lattice_capture()` take only `api_url=`):

```python
chloros_sdk.connect_camera("213800234", backend_url="http://127.0.0.1:5000")
chloros_sdk.connect_array(serials, backend_url="http://127.0.0.1:5000")
chloros_sdk.connect_daq_sensor(eth_host="daq-e-1.local",
                                backend_url="http://127.0.0.1:5000")
chloros_sdk.ChlorosLocal(backend_url="http://127.0.0.1:5000")
```

(An installed backend listens on loopback only, so a LAN `backend_url` cannot reach it; see [Remote-Backend Mode](#remote-backend-mode-pip-only-host-via-tunnel) for the tunnel pattern.)

***

## Versioning & Compatibility

* SDK version is exposed as `chloros_sdk.__version__`.
* The SDK pins behaviour to the bundled backend version. Mixing an older SDK with a newer backend usually works (forward-compatible endpoints), but mixing a newer SDK with an older backend may surface `404` errors on new endpoints — upgrade the desktop app to match.
* The smart-connect surface (`connect_camera` / `connect_array` / `connect_daq_sensor`) and the network-analysis endpoint return stable JSON schemas; new fields are additive.

***

## Troubleshooting Pointers

* **`ChlorosAuthenticationError: Login required`** (from `ChlorosLocal`; the smart-connect calls raise `ChlorosConnectError: Login required. …` for the same cause) → Run `chloros-cli login EMAIL PASSWORD` once on this machine, or sign in via the Chloros desktop app.
* **`ChlorosProcessingError: Failed to start processing: … The project folder is too deep for this computer …`** (or `Failed to create project: …` from `create_project()`) → 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, 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*.
* **`ChlorosConnectError: No Chloros backend is running …`** → The smart-connect calls auto-start a local backend, so this only appears when the bundled binary can't be found/started (e.g. a pip-only host with no desktop package). The message is platform-aware: on Windows open the desktop app or run any `chloros-cli` command; on Linux run a `chloros-cli` command (no GUI exists) or install the `.deb`. For a remote backend, pass `backend_url=` (and `auto_start_backend=False`).
* **`CAMERA_AVAILABLE == False`** at import → `lattice_sdk` failed to load: the Arena SDK runtime, or OpenCV (`cv2`), is not importable in this Python. The backend-driven surface (`connect_*`, projects through a backend, `ChlorosLocal`) still works.
* **Array connects at full sensor but a low frame rate** → By design: auto keeps the full sensor and lets the rate fall to what the wire carries. Pass `binning=2` / `4` or a smaller `width` / `height` for more frames per second, or enable jumbo frames / upgrade the link. Binning and ROI do **not** cover aggregate over-subscription (`oversubscribed: true`, fps fields 0): too many cams for the wire cannot be fixed by binning/ROI — reduce the camera count, enable jumbo frames, or move to a faster NIC (see [Over-Subscription](#over-subscription-the-per-cam-floor)).
* **`analyze_array_network()` reports the NIC RX ring as tiny (\~0.26 MB) / connect gates with "FRAMES WILL DROP"** → The host NIC's receive ring is at its default (often reset to 32 after a NIC driver update). On a Realtek USB 10GbE adapter set `ReceiveBufferLen=256` and `PendingReceives=64` (elevated), then restart the backend so it re-reads the ring. Full procedure: [CLI Reference → Host NIC Setup & Tuning](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#host-nic-setup--tuning-lattice-arrays).
* **Host hangs on restart/shutdown, later WMI `Invalid class` errors / NIC won't enable** → Outdated USB 10GbE driver causing `DRIVER_POWER_STATE_FAILURE` (BSOD `0x9F`). Update the adapter driver to a current version (≥ 2026) and re-apply the receive-ring settings. See [CLI Reference → Host NIC Setup & Tuning](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md#host-nic-setup--tuning-lattice-arrays).
* **Array capture fails with HTTP 503 "No fresh synced frame group"** → The array published no new frame group within the wait. Check `arr.status()`: `stalled: True` (or `streaming: False`) with `actual_fps` 0 means the grab loop has stopped publishing — disconnect and reconnect the array. If `stalled` is False and `actual_fps` is above 0, retry. Right after `connect_array()` a capture already waits up to 20 s for the first group.
* **`status()` shows `link_speed_mbps: 4294`** → Windows could not read the adapter's speed; typical of USB Ethernet adapters, and not a fault. See [Expected Frame Rates](#expected-frame-rates).
* **`update_firmware()` fails with `device never connected back on TCP <port>`** → A firewall blocked the DAQ-E's connection back to this computer. The Windows installer adds the rule (see [DAQ-E Device Settings](#daq-e-device-settings)); with another firewall, allow inbound TCP to the backend from the sensor's subnet.
* **Reflectance refused** → A live DAQ must be bound to the cam (or array) for absolute-scale reflectance. Either bind via the GUI or use `processing="radiance"` (W/m²/sr/nm) which doesn't require a paired sensor.
* **`smart=True` capture takes longer than expected** → AE convergence depends on scene dynamics. With `ArrayHandle.capture_smart()`, widen `exposure_tolerance_pct`, shorten `stability_window_s` or lower `settle_timeout_s` for a faster, less settled trigger.

***

## See Also

* [CLI Reference](https://mapir.gitbook.io/chloros/reference-cli-and-sdk/cli-reference.md) — every CLI subcommand mirrors an SDK call.
* [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/api-python-sdk`
