braid_types/

lib.rs

// Copyright (C) The Strand-Braid Authors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Core types for the Braid tracking system.
//!
//! This crate provides the fundamental data structures and configuration types
//! used throughout the Braid multi-camera tracking system, including tracking
//! parameters, camera configurations, and data storage formats.
//!
//! ## Features
//!
//! - `with-tokio-codec`: Enables CBOR packet codec for tokio-based applications
//! - `start-listener`: Enables TCP listener utilities for HTTP servers

#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]

#[macro_use]
extern crate static_assertions;

use ordered_float::NotNan;
use std::net::SocketAddr;
use strand_cam_bui_types::{ClockModel, RecordingPath};

use serde::{Deserialize, Deserializer, Serialize};

use strand_bui_backend_session_types::BuiServerAddrInfo;
use strand_withkey::WithKey;

/// Default address for the model server.
pub const DEFAULT_MODEL_SERVER_ADDR: &str = "0.0.0.0:8397";

// These are the filenames saved during recording. --------------------
//
// BraidMetadataSchemaTag (BRAID_SCHEMA) is versioned like semver: it is bumped
// only on a backward-incompatible change to the on-disk format -- one that
// would prevent an existing reader from correctly parsing a newly written file.
// Examples that REQUIRE a bump: removing or renaming a file, removing a CSV
// column or struct field, or changing the type or meaning of an existing one.
// Purely additive changes -- a new file, a new optional CSV column, or a new
// `#[serde(default)]` struct field -- are backward compatible and do NOT bump
// the schema, since old readers continue to work unchanged.
/// Version number for the Braid metadata schema.
pub const BRAID_SCHEMA: u16 = 3; // BraidMetadataSchemaTag

// CSV files. (These may also exist as .csv.gz)
/// CSV filename for Kalman filter estimates.
pub const KALMAN_ESTIMATES_CSV_FNAME: &str = "kalman_estimates.csv";
/// CSV filename for data association records.
pub const DATA_ASSOCIATE_CSV_FNAME: &str = "data_association.csv";
/// CSV filename for 2D distorted coordinate data.
pub const DATA2D_DISTORTED_CSV_FNAME: &str = "data2d_distorted.csv";
/// CSV filename for camera information.
pub const CAM_INFO_CSV_FNAME: &str = "cam_info.csv";
/// CSV filename for trigger clock information.
pub const TRIGGER_CLOCK_INFO_CSV_FNAME: &str = "trigger_clock_info.csv";
/// CSV filename for experiment information.
pub const EXPERIMENT_INFO_CSV_FNAME: &str = "experiment_info.csv";
/// CSV filename for text log messages.
pub const TEXTLOG_CSV_FNAME: &str = "textlog.csv";

// Other files
/// XML filename for camera calibration data.
pub const CALIBRATION_XML_FNAME: &str = "calibration.xml";
/// YAML filename for Braid metadata.
pub const BRAID_METADATA_YML_FNAME: &str = "braid_metadata.yml";
/// Markdown filename for README documentation.
pub const README_MD_FNAME: &str = "README.md";
/// Directory name for saved images.
pub const IMAGES_DIRNAME: &str = "images";
/// Directory name for camera settings.
pub const CAM_SETTINGS_DIRNAME: &str = "cam_settings";
/// Directory name for feature detection settings.
pub const FEATURE_DETECT_SETTINGS_DIRNAME: &str = "feature_detect_settings";
/// HLog filename for reconstruction latency measurements.
pub const RECONSTRUCT_LATENCY_HLOG_FNAME: &str = "reconstruct_latency_usec.hlog";
/// HLog filename for reprojection distance measurements.
pub const REPROJECTION_DIST_HLOG_FNAME: &str = "reprojection_distance_100x_pixels.hlog";

/// Duration in seconds for triggerbox synchronization.
pub const TRIGGERBOX_SYNC_SECONDS: u64 = 3;

// Ideas for future:
//
// Make tracking model and parameters "pluggable" so that other models - with
// different structure - can be easily used.
//
// **statistics cache for data2d_distorted** We could keep a statistics cache as
// we write a braidz file for things like num found points, average and maximum
// values etc. This could be periodically flushed to disk and recomputed anytime
// but would eliminate most needs to iterate over the entire dataset at read
// time.
//
// **statistics cache for kalman_estimates** Same as above but 3D.
//
// Cache the camera pixel sizes. Currently this can be found if images are saved
// or if the a camera calibration is present. The images in theory are always
// there but this is not currently implemented in the strand-cam "flydratrax"
// mode. Even when that is fixed, to simply read the image size that way will
// require parsing an entire image parser.
//
// Replace `TrackingParams.initial_position_std_meters` and
// `TrackingParams.initial_vel_std_meters_per_sec` with a scaled version of the
// process covariance matrix Q. According to this ([p.
// 18](https://www.robots.ox.ac.uk/~ian/Teaching/Estimation/LectureNotes2.pdf)),
// this approach is common with a scale factor of 10.
// --------------------------------------------------------------------

/// Camera information record for CSV output.
// Backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition).
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct CamInfoRow {
    /// The index of the camera. This changes from invocation to invocation of Braid.
    pub camn: CamNum,
    /// The name of the camera. This is stable across invocations of Braid.
    ///
    /// Any valid UTF-8 string is possible. (Previously, this was the "ROS name"
    /// of the camera in which, e.g. '-' was replaced with '_'. This is no
    /// longer the case.)
    pub cam_id: String,
}

/// Kalman filter state estimate record for CSV output.
// Backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition).
#[expect(
    non_snake_case,
    reason = "fields with covariance are named after the standard Kalman filter covariance matrix notation."
)]
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct KalmanEstimatesRow {
    /// Object ID being tracked.
    pub obj_id: u32,
    /// Synchronized frame number.
    pub frame: SyncFno,
    /// The timestamp when the trigger pulse fired.
    ///
    /// Note that calculating this live in braid requires that the clock model
    /// has established itself. Thus, the initial frames immediately after
    /// synchronization will not have a timestamp.
    #[serde(with = "crate::timestamp_opt_f64")]
    pub timestamp: Option<FlydraFloatTimestampLocal<Triggerbox>>,
    /// X position estimate in meters.
    pub x: f64,
    /// Y position estimate in meters.
    pub y: f64,
    /// Z position estimate in meters.
    pub z: f64,
    /// X velocity estimate in meters per second.
    pub xvel: f64,
    /// Y velocity estimate in meters per second.
    pub yvel: f64,
    /// Z velocity estimate in meters per second.
    pub zvel: f64,
    /// Covariance matrix element P\[0,0\].
    pub P00: f64,
    /// Covariance matrix element P\[0,1\].
    pub P01: f64,
    /// Covariance matrix element P\[0,2\].
    pub P02: f64,
    /// Covariance matrix element P\[1,1\].
    pub P11: f64,
    /// Covariance matrix element P\[1,2\].
    pub P12: f64,
    /// Covariance matrix element P\[2,2\].
    pub P22: f64,
    /// Covariance matrix element P\[3,3\].
    pub P33: f64,
    /// Covariance matrix element P\[4,4\].
    pub P44: f64,
    /// Covariance matrix element P\[5,5\].
    pub P55: f64,
}
impl WithKey<SyncFno> for KalmanEstimatesRow {
    fn key(&self) -> SyncFno {
        self.frame
    }
}

/// Data association record linking 2D detections to 3D tracks.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct DataAssocRow {
    // backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition)
    /// Object ID being tracked.
    pub obj_id: u32,
    /// Synchronized frame number.
    pub frame: SyncFno,
    /// Camera number.
    pub cam_num: CamNum,
    /// Point index within the frame.
    pub pt_idx: u8,
}
impl WithKey<SyncFno> for DataAssocRow {
    fn key(&self) -> SyncFno {
        self.frame
    }
}

/// A 2D feature detection result transmitted via UDP.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct FlydraRawUdpPoint {
    /// X coordinate in absolute pixels.
    pub x0_abs: f64,
    /// Y coordinate in absolute pixels.
    pub y0_abs: f64,
    /// Area of the detection in pixels.
    pub area: f64,
    /// Optional slope and eccentricity values.
    pub maybe_slope_eccentricty: Option<(f64, f64)>,
    /// Current pixel value.
    pub cur_val: u8,
    /// Mean pixel value.
    pub mean_val: f64,
    /// Sum of squares of pixel values.
    pub sumsqf_val: f64,
}

/// The original camera name from the driver.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Eq, PartialOrd, Ord)]
pub struct RawCamName(String);

impl RawCamName {
    /// Create a new RawCamName from a string.
    pub fn new(s: String) -> Self {
        RawCamName(s)
    }
    /// Get the camera name as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for RawCamName {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// HTTP API utilities for Braid server.
pub mod braid_http {
    /// URL path for remote camera info endpoint.
    pub const REMOTE_CAMERA_INFO_PATH: &str = "remote-camera-info";
    /// URL path for camera proxy endpoint.
    pub const CAM_PROXY_PATH: &str = "cam-proxy";

    /// Encode camera name, potentially with slashes or spaces, to be a single
    /// URL path component.
    ///
    /// Use percent-encoding, which `axum::extract::Path` automatically decodes.
    pub fn encode_cam_name(cam_name: &crate::RawCamName) -> String {
        percent_encoding::utf8_percent_encode(&cam_name.0, percent_encoding::NON_ALPHANUMERIC)
            .to_string()
    }
}

/// Frame rate limiting configuration for camera startup.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Default)]
pub enum StartSoftwareFrameRateLimit {
    /// Set the frame_rate limit at a given frame rate.
    Enable(f64),
    /// Disable the frame_rate limit.
    Disabled,
    /// Do not change the frame rate limit.
    #[default]
    NoChange,
}

/// Camera startup information sent to strand cameras.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct RemoteCameraInfoResponse {
    /// The destination UDP port to use for low-latency tracking data
    pub camdata_udp_port: u16,
    /// Camera configuration.
    pub config: BraidCameraConfig,
    /// Whether to force camera synchronization mode.
    pub force_camera_sync_mode: bool,
    /// Software frame rate limiting configuration.
    pub software_limit_framerate: StartSoftwareFrameRateLimit,
    /// camera triggering configuration (global for all cameras)
    pub trig_config: TriggerType,
}

/// Newtype storing time as number of nanoseconds since Jan 1, 1970 in UTC.
///
/// This is the lower 64 bits of the 80 bit PTP timestamp.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct PtpStamp(u64);

impl PtpStamp {
    /// Create a new PtpStamp from nanoseconds since epoch.
    pub fn new(val: u64) -> Self {
        PtpStamp(val)
    }

    /// Get the raw nanoseconds value.
    pub fn get(&self) -> u64 {
        self.0
    }

    /// Calculate duration since another timestamp.
    pub fn duration_since(&self, other: &Self) -> Option<PtpStampDuration> {
        if self.0 >= other.0 {
            Some(PtpStampDuration(self.0 - other.0))
        } else {
            None
        }
    }
}

/// Newtype storing a duration between two [PtpStamp] values.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct PtpStampDuration(u64);

impl PtpStampDuration {
    /// Get the duration in nanoseconds.
    pub fn nanos(&self) -> u64 {
        self.0
    }
}

impl<TZ> TryFrom<chrono::DateTime<TZ>> for PtpStamp
where
    TZ: chrono::TimeZone,
{
    type Error = &'static str;

    fn try_from(orig: chrono::DateTime<TZ>) -> Result<Self, Self::Error> {
        Ok(Self(
            orig.to_utc()
                .timestamp_nanos_opt()
                .ok_or("could not convert DateTime to i64 nanosec")?
                .try_into()
                .map_err(|_| "could not convert i64 nanosec to u64")?,
        ))
    }
}

impl TryFrom<PtpStamp> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_from(orig: PtpStamp) -> Result<Self, Self::Error> {
        let secs = orig.0 / 1_000_000_000;
        let nsecs = orig.0 % 1_000_000_000;
        chrono::DateTime::from_timestamp(
            secs.try_into()
                .map_err(|_| "could not convert u64 nanosec to i64")?,
            nsecs
                .try_into()
                .map_err(|_| "could not convert u64 nanosec to u32")?,
        )
        .ok_or("could not convert timestamp to DateTime")
    }
}

impl TryFrom<PtpStamp> for chrono::DateTime<chrono::FixedOffset> {
    type Error = &'static str;
    fn try_from(orig: PtpStamp) -> Result<Self, Self::Error> {
        let utc: chrono::DateTime<chrono::Utc> = orig.try_into()?;
        Ok(utc.into())
    }
}

impl TryFrom<PtpStamp> for chrono::DateTime<chrono::Local> {
    type Error = &'static str;
    fn try_from(orig: PtpStamp) -> Result<Self, Self::Error> {
        let utc: chrono::DateTime<chrono::Utc> = orig.try_into()?;
        Ok(utc.into())
    }
}

/// Default allowed imprecision for frame acquisition duration in milliseconds.
pub const DEFAULT_ACQUISITION_DURATION_ALLOWED_IMPRECISION_MSEC: Option<f64> = Some(5.0);

/// Configuration for a single camera in the Braid system.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct BraidCameraConfig {
    /// The name of the camera (e.g. "Basler-22005677")
    ///
    /// (This is the original UTF-8 camera name, not the ROS-encoded camera name
    /// in which certain characters are not allowed.)
    pub name: String,
    /// Filename of vendor-specific camera settings file.
    ///
    /// Can contain shell variables such as `~`, `$A`, or `${B}`.
    pub camera_settings_filename: Option<std::path::PathBuf>,
    /// The pixel format to use.
    pub pixel_format: Option<String>,
    /// Configuration for detecting points.
    #[serde(default = "flydra_pt_detect_cfg::default_absdiff")]
    pub point_detection_config: flydra_feature_detector_types::ImPtDetectCfg,
    /// Which camera backend to use.
    #[serde(default)]
    pub start_backend: StartCameraBackend,
    /// Allowed imprecision for frame acquisition duration.
    pub acquisition_duration_allowed_imprecision_msec: Option<f64>,
    /// The SocketAddr on which the strand camera BUI server should run.
    pub http_server_addr: Option<String>,
    /// The interval at which the current image should be sent, in milliseconds.
    #[serde(default = "default_send_current_image_interval_msec")]
    pub send_current_image_interval_msec: u64,

    /// Deprecated, useless old config option (not removed for backwards compatibility)
    #[serde(
        default,
        skip_serializing,
        rename = "raise_grab_thread_priority",
        deserialize_with = "raise_grab_thread_priority_deser"
    )]
    _raise_grab_thread_priority: bool,
}

fn raise_grab_thread_priority_deser<'de, D>(de: D) -> Result<bool, D::Error>
where
    D: Deserializer<'de>,
{
    tracing::error!(
        "The parameter 'raise_grab_thread_priority' is no longer used. Remove this parameter from your configuration."
    );
    bool::deserialize(de)
}

const fn default_send_current_image_interval_msec() -> u64 {
    2000
}

/// Camera backend selection for local camera startup.
#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
#[derive(Default)]
pub enum StartCameraBackend {
    /// Do not start a camera locally. Rather, wait for a remote camera to connect.
    Remote,
    /// Start a Pylon camera locally using the `strand-cam` program with the
    /// `--camera-backend pylon` argument.
    #[default]
    Pylon,
    /// Start a Vimba camera locally using the `strand-cam` program with the
    /// `--camera-backend vimba` argument.
    Vimba,
    /// Start a consumer webcam locally using the `strand-cam` program with
    /// the `--camera-backend webcam` argument.
    ///
    /// Intended for development use. The camera `name` to use in the
    /// configuration is the human-readable device name of the webcam.
    Webcam,
    /// Start a simulated camera locally using the `strand-cam` program with the
    /// `--camera-backend sim` argument.
    ///
    /// Used for end-to-end testing with no hardware: the camera renders
    /// synthetic images of simulated insects. The scenario is given by the
    /// `STRAND_CAM_SIM_SPEC` environment variable, and the camera `name` is one
    /// of the simulated camera names (e.g. `simcam0`).
    Sim,
}

impl StartCameraBackend {
    /// Get the executable name for the camera backend.
    ///
    /// All local backends are served by the single merged `strand-cam`
    /// executable, which selects the backend at runtime via
    /// [Self::camera_backend_arg].
    pub fn strand_cam_exe_name(&self) -> Option<&str> {
        match self {
            StartCameraBackend::Remote => None,
            StartCameraBackend::Pylon
            | StartCameraBackend::Vimba
            | StartCameraBackend::Webcam
            | StartCameraBackend::Sim => Some("strand-cam"),
        }
    }

    /// Get the value for the `--camera-backend` argument of the `strand-cam`
    /// executable, or `None` for a remote camera (whose backend is chosen on
    /// the remote machine).
    pub fn camera_backend_arg(&self) -> Option<&'static str> {
        match self {
            StartCameraBackend::Remote => None,
            StartCameraBackend::Pylon => Some("pylon"),
            StartCameraBackend::Vimba => Some("vimba"),
            StartCameraBackend::Webcam => Some("webcam"),
            StartCameraBackend::Sim => Some("sim"),
        }
    }
}

impl BraidCameraConfig {
    /// Create a default camera configuration with absolute difference point detection.
    pub fn default_absdiff_config(name: String) -> Self {
        Self {
            name,
            camera_settings_filename: None,
            pixel_format: None,
            point_detection_config: flydra_pt_detect_cfg::default_absdiff(),
            _raise_grab_thread_priority: Default::default(),
            start_backend: Default::default(),
            acquisition_duration_allowed_imprecision_msec:
                DEFAULT_ACQUISITION_DURATION_ALLOWED_IMPRECISION_MSEC,
            http_server_addr: None,
            send_current_image_interval_msec: default_send_current_image_interval_msec(),
        }
    }
}

/// Per-camera data to be saved during recording.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct PerCamSaveData {
    /// Current image as PNG data.
    pub current_image_png: PngImageData,
    /// Current camera settings data.
    pub cam_settings_data: Option<UpdateCamSettings>,
    /// Current feature detection settings.
    pub feature_detect_settings: Option<UpdateFeatureDetectSettings>,
}

/// Camera registration message sent to Braid.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct RegisterNewCamera {
    /// The name of the camera as returned by the camera
    pub raw_cam_name: RawCamName,
    /// Location of the camera control HTTP server.
    pub http_camserver_info: Option<BuiServerInfo>,
    /// The camera settings.
    pub cam_settings_data: Option<UpdateCamSettings>,
    /// The current image.
    pub current_image_png: PngImageData,
    /// The period of the periodic signal generator in the camera.
    /// This is used for PTP-based synchronization.
    pub camera_periodic_signal_period_usec: Option<f64>,
}

/// Image update message.
#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
pub struct UpdateImage {
    /// The current image.
    pub current_image_png: PngImageData,
}

/// PNG image data container.
#[derive(PartialEq, Eq, Clone, Serialize, Deserialize)]
pub struct PngImageData {
    /// Raw PNG image data bytes.
    pub data: Vec<u8>,
}

impl From<Vec<u8>> for PngImageData {
    fn from(data: Vec<u8>) -> Self {
        Self { data }
    }
}

impl PngImageData {
    /// Get the PNG data as a byte slice.
    pub fn as_slice(&self) -> &[u8] {
        self.data.as_slice()
    }

    /// Get the image dimensions as (width, height) in pixels.
    ///
    /// Returns `None` if the data is not valid PNG data.
    pub fn dimensions(&self) -> Option<(u32, u32)> {
        // The PNG format starts with an 8 byte signature followed by the IHDR
        // chunk, which the specification requires to be first. A chunk starts
        // with a 4 byte length and 4 byte type, after which the IHDR data
        // begins with the big-endian u32 width and height.
        const SIGNATURE: [u8; 8] = [0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a];
        let data = self.data.as_slice();
        if data.len() < 24 || data[0..8] != SIGNATURE || &data[12..16] != b"IHDR" {
            return None;
        }
        let width = u32::from_be_bytes(data[16..20].try_into().unwrap());
        let height = u32::from_be_bytes(data[20..24].try_into().unwrap());
        Some((width, height))
    }
}

impl std::fmt::Debug for PngImageData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "PngImageData{{..}}",)
    }
}

#[test]
fn test_png_dimensions() {
    // Minimal PNG header: signature, IHDR chunk length and type, width 640,
    // height 480.
    let mut data = vec![0x89, b'P', b'N', b'G', 0x0d, 0x0a, 0x1a, 0x0a];
    data.extend_from_slice(&13u32.to_be_bytes());
    data.extend_from_slice(b"IHDR");
    data.extend_from_slice(&640u32.to_be_bytes());
    data.extend_from_slice(&480u32.to_be_bytes());
    let png = PngImageData::from(data);
    assert_eq!(png.dimensions(), Some((640, 480)));

    assert_eq!(PngImageData::from(vec![0u8; 24]).dimensions(), None);
    assert_eq!(PngImageData::from(vec![]).dimensions(), None);
}

/// Camera settings update message.
#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
pub struct UpdateCamSettings {
    /// The current camera settings
    pub current_cam_settings_buf: String,
    /// The filename extension for the camera settings
    pub current_cam_settings_extension: String,
}

/// Feature detection settings update message.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct UpdateFeatureDetectSettings {
    /// The current feature detection settings.
    pub current_feature_detect_settings: flydra_feature_detector_types::ImPtDetectCfg,
}

/// Camera synchronization state.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum ConnectedCameraSyncState {
    /// No known reference to other cameras
    Unsynchronized,
    /// This `u64` is frame0, the offset to go from camera frame to sync frame.
    Synchronized(u64),
}

impl ConnectedCameraSyncState {
    /// Check if the camera is synchronized.
    pub fn is_synchronized(&self) -> bool {
        match self {
            ConnectedCameraSyncState::Unsynchronized => false,
            ConnectedCameraSyncState::Synchronized(_) => true,
        }
    }
}

/// Information about a newer available release of Braid.
///
/// Populated by the background version check when the version-check server
/// reports a version newer than the running one. Surfaced to every connected
/// browser as a dismissible banner.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct VersionUpdate {
    /// The newest available version as a semver string, e.g. `"1.0.0-rc.3"`.
    pub available: String,
    /// Human-readable message from the version-check server.
    pub message: String,
    /// URL with release notes / downloads, rendered as a link.
    pub url: String,
}

/// Shared state for the Braid HTTP API.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct BraidHttpApiSharedState {
    /// Camera synchronization trigger configuration.
    pub trigger_type: TriggerType,
    /// Whether a clock model is needed for synchronization.
    pub needs_clock_model: bool,
    /// The current clock model for time synchronization.
    pub clock_model: Option<ClockModel>,
    /// Directory path for CSV table recordings.
    pub csv_tables_dirname: Option<RecordingPath>,
    // This is "fake" because it only signals if each of the connected computers
    // is recording MKVs.
    /// Path for MP4 recording (signals if cameras are recording).
    pub fake_mp4_recording_path: Option<RecordingPath>,
    /// Size of post-trigger buffer in frames.
    pub post_trigger_buffer_size: usize,
    /// Filename of camera calibration file.
    pub calibration_filename: Option<String>,
    /// List of connected camera information.
    pub connected_cameras: Vec<CamInfo>, // TODO: make this a BTreeMap?
    /// Whether the feature detection background model is continuously
    /// updating, per camera.
    ///
    /// Cameras whose feature detection settings have not (yet) been received
    /// are absent from this map.
    pub background_model_updating: std::collections::BTreeMap<RawCamName, bool>,
    /// Image dimensions as (width, height) in pixels, per camera.
    ///
    /// Cameras whose image has not (yet) been received are absent from this
    /// map.
    pub camera_image_dimensions: std::collections::BTreeMap<RawCamName, (u32, u32)>,
    /// Address of the model server.
    pub model_server_addr: Option<SocketAddr>,
    /// Name of the Flydra application.
    pub flydra_app_name: String,
    /// Whether all expected cameras are synchronized.
    pub all_expected_cameras_are_synced: bool,
    /// A newer available release discovered by the background version check, or
    /// `None` if up to date (or the check has not yet found a newer version).
    pub version_update: Option<VersionUpdate>,
}

/// Statistics for recent camera activity.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Default)]
pub struct RecentStats {
    /// Total number of frames collected since start.
    pub total_frames_collected: usize,
    /// Number of frames collected in recent period.
    pub frames_collected: usize,
    /// Measured frame rate (frames per second) over the recent period.
    ///
    /// Computed on the mainbrain from the exact elapsed time of the
    /// measurement window, so it is stable regardless of how the shared state
    /// is delivered to clients.
    pub fps: f64,
    /// Number of points detected in recent period.
    pub points_detected: usize,
}

/// Generic HTTP API server information
///
/// This is used for both the Strand Camera BUI and the Braid BUI.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub enum BuiServerInfo {
    /// No server is present (e.g. prerecorded data).
    NoServer,
    /// A server is available.
    Server(BuiServerAddrInfo),
}

/// Check if a URL refers to a loopback address.
pub fn is_loopback(url: &http::Uri) -> bool {
    let authority = match url.authority() {
        None => return false,
        Some(authority) => authority,
    };
    match authority.host() {
        "127.0.0.1" | "[::1]" => true,
        // should we include "localhost"? only if it actually resolves?
        _ => false,
    }
}

// -----

/// Duration for which a freshly minted access token remains valid.
///
/// A token is only needed for a client's very first request: a successful auth
/// hands back a session cookie that carries the session from then on (browsers
/// persist it, and Braid persists its per-camera cookie jar to disk). Keeping
/// the token short-lived bounds the window in which a token leaked via a URL
/// (terminal scrollback, log files, a photographed QR code) can be replayed.
#[cfg(feature = "start-listener")]
pub const ACCESS_TOKEN_TTL: std::time::Duration = std::time::Duration::from_secs(30 * 60);

/// Start a TCP listener for an HTTP server, minting an access token if the
/// listen address is not loopback.
///
/// `persistent_secret` is the same cookie/MAC key used to build the server's
/// auth layer. The minted token is a self-expiring value signed with that
/// secret, so the auth layer accepts it without any token value being stored;
/// see [ACCESS_TOKEN_TTL] for its lifetime.
#[cfg(feature = "start-listener")]
pub async fn start_listener(
    address_string: &str,
    persistent_secret: &cookie::Key,
) -> eyre::Result<(tokio::net::TcpListener, BuiServerAddrInfo)> {
    let socket_addr = std::net::ToSocketAddrs::to_socket_addrs(&address_string)?
        .next()
        .ok_or_else(|| eyre::eyre!("no address found for HTTP server"))?;

    let listener = tokio::net::TcpListener::bind(socket_addr).await?;
    let listener_local_addr = listener.local_addr()?;
    let token = if !listener_local_addr.ip().is_loopback() {
        // Mint a short-lived, self-expiring token signed with the persistent
        // secret. The auth layer is configured with the same secret, so it
        // validates this token by signature and expiry; nothing is stored.
        let token_str = axum_token_auth::generate_token(persistent_secret, ACCESS_TOKEN_TTL);
        strand_bui_backend_session_types::AccessToken::PreSharedToken(token_str)
    } else {
        strand_bui_backend_session_types::AccessToken::NoToken
    };
    let http_camserver_info = BuiServerAddrInfo::new(listener_local_addr, token);

    Ok((listener, http_camserver_info))
}

/// Parse a list of CIDR strings (e.g. `"100.64.0.0/10"`) into the network type
/// expected by [`axum_token_auth::AuthConfig::trusted_networks`], returning a
/// descriptive error for the first one that fails to parse.
#[cfg(feature = "start-listener")]
pub fn parse_trusted_networks(nets: &[String]) -> eyre::Result<Vec<axum_token_auth::CidrBlock>> {
    nets.iter()
        .map(|s| {
            s.parse::<axum_token_auth::CidrBlock>()
                .map_err(|e| eyre::eyre!("invalid trusted network CIDR {s:?}: {e}"))
        })
        .collect()
}

/// Restrict the on-disk `preferences_serde1` file backing `key` to owner-only
/// access (Unix mode 0600), warning if it was previously reachable by other
/// local users.
///
/// The cookie/token secret is effectively a master credential (it can forge any
/// session and mint any token) and the persisted cookie jars hold live session
/// cookies, so neither should be group- or world-readable. `preferences_serde1`
/// creates the file with the process umask (typically 0644); this tightens it
/// after the fact. No-op on non-Unix platforms, whose permission model differs.
#[cfg(feature = "start-listener")]
pub fn harden_prefs_file(app: &preferences_serde1::AppInfo, key: &str) {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;

        // Mirror `preferences_serde1`'s path layout: <config>/<app>/<key>.prefs.json
        let Some(mut path) = preferences_serde1::prefs_base_dir() else {
            return;
        };
        path.push(app.name);
        path.push(key);
        let Some(mut name) = path.file_name().map(|n| n.to_os_string()) else {
            return;
        };
        name.push(".prefs.json");
        path.set_file_name(name);

        let Ok(md) = std::fs::metadata(&path) else {
            // No file on disk (e.g. secret supplied via override): nothing to do.
            return;
        };
        let mode = md.permissions().mode() & 0o777;
        if mode & 0o077 != 0 {
            tracing::warn!(
                "Restricting permissions on sensitive file {} from {mode:o} to 600 \
                 (it was accessible to other local users).",
                path.display(),
            );
        }
        if let Err(e) = std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)) {
            tracing::warn!("Could not restrict permissions on {}: {e}", path.display());
        }
    }
    #[cfg(not(unix))]
    {
        let _ = (app, key);
    }
}

// -----

/// Text log message record for CSV output.
#[derive(Debug, Serialize, Deserialize)]
pub struct TextlogRow {
    // backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition)
    /// Timestamp from the main brain system.
    pub mainbrain_timestamp: f64,
    /// Camera identifier.
    pub cam_id: String,
    /// Host system timestamp.
    pub host_timestamp: f64,
    /// Log message text.
    pub message: String,
}

/// Tracking parameters
///
/// The terminology used is as defined at [the Wikipedia page on the Kalman
/// filter](https://en.wikipedia.org/wiki/Kalman_filter).
///
/// The state estimated is a six component vector with position and velocity
/// **x** = \<x, y, z, x', y', z'\>. The motion model is a constant velocity
/// model with noise term, (see
/// [description](https://webee.technion.ac.il/people/shimkin/Estimation09/ch8_target.pdf)).
///
/// The state covariance matrix **P** is initialized with the value (α is
/// defined in the field [TrackingParams::initial_position_std_meters] and β is
/// defined in the field [TrackingParams::initial_vel_std_meters_per_sec]:<br/>
/// **P**<sub>initial</sub> = [[α<sup>2</sup>, 0, 0, 0, 0, 0],<br/>
/// [0, α<sup>2</sup>, 0, 0, 0, 0],<br/>
/// [0, 0, α<sup>2</sup>, 0, 0, 0],<br/>
/// [0, 0, 0, β<sup>2</sup>, 0, 0],<br/>
/// [0, 0, 0, 0, β<sup>2</sup>, 0],<br/>
/// [0, 0, 0, 0, 0, β<sup>2</sup>]]
///
/// The covariance of the state process update **Q**(τ) is defined as a function
/// of τ, the time interval from the previous update):<br/>
/// **Q**(τ) = [TrackingParams::motion_noise_scale] [[τ<sup>3</sup>/3, 0, 0, τ<sup>2</sup>/2, 0,
/// 0],<br/>
/// [0, τ<sup>3</sup>/3, 0, 0, τ<sup>2</sup>/2, 0],<br/>
/// [0, 0, τ<sup>3</sup>/3, 0, 0, τ<sup>2</sup>/2],<br/>
/// [τ<sup>2</sup>/2, 0, 0, τ, 0, 0],<br/>
/// [0, τ<sup>2</sup>/2, 0, 0, τ, 0],<br/>
/// [0, 0, τ<sup>2</sup>/2, 0, 0, τ]]
///
/// Note that this form of the state process update covariance has the property
/// that 2**Q**(τ) = **Q**(2τ). In other words, two successive additions of this
/// covariance will have an identical effect to a single addtion for twice the
/// time interval.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TrackingParams {
    /// This is used to scale the state noise covariance matrix **Q** as
    /// described at the struct-level (Kalman filter parameter).
    pub motion_noise_scale: f64,
    /// This is α in the above formula used to build the position terms in the
    /// initial estimate covariance matrix **P** as described at the
    /// struct-level (Kalman filter parameter).
    pub initial_position_std_meters: f64,
    /// This is β in the above formula used to build the velocity terms in the
    /// initial estimate covariance matrix **P** as described at the
    /// struct-level (Kalman filter parameter).
    pub initial_vel_std_meters_per_sec: f64,
    /// The observation noise covariance matrix **R** (Kalman filter
    /// parameter).
    pub ekf_observation_covariance_pixels: f64,
    /// This sets a minimum threshold for using an obervation to update an
    /// object being tracked (data association parameter).
    pub accept_observation_min_likelihood: f64,
    /// This is used to compute the maximum allowable covariance before an
    /// object is "killed" and no longer tracked.
    pub max_position_std_meters: f32,
    /// These are the hypothesis testing parameters used to "birth" a new new
    /// object and start tracking it.
    ///
    /// This is `None` if 2D (flat-3d) tracking.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hypothesis_test_params: Option<HypothesisTestParams>,
    /// This is the minimum number of observations before object becomes
    /// visible.
    #[serde(default = "default_num_observations_to_visibility")]
    pub num_observations_to_visibility: u8,
    /// Parameters defining mini arena configuration.
    ///
    /// This is MiniArenaConfig::NoMiniArena if no mini arena is in use.
    #[serde(skip_serializing_if = "MiniArenaConfig::is_none", default)]
    pub mini_arena_config: MiniArenaConfig,
}

/// Locator for determining which mini arena contains a point.
pub struct MiniArenaLocator {
    /// The index number of the mini arena. None if the point is not in a mini arena.
    my_idx: Option<u8>,
}

impl MiniArenaLocator {
    /// Create a locator for a specific mini arena index.
    pub fn from_mini_arena_idx(val: u8) -> Self {
        Self { my_idx: Some(val) }
    }

    /// Create a locator indicating no mini arena.
    pub fn new_none() -> Self {
        Self { my_idx: None }
    }

    /// Return the index number of the mini arena. None if the point is not in a
    /// mini arena.
    pub fn idx(&self) -> Option<u8> {
        self.my_idx
    }
}

/// Configuration defining potential mini arenas.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(tag = "type")]
pub enum MiniArenaConfig {
    /// No mini arena is in use.
    #[default]
    NoMiniArena,
    /// A 2D grid arranged along the X and Y axes.
    XYGrid(XYGridConfig),
}

#[expect(clippy::len_without_is_empty)]
impl MiniArenaConfig {
    fn is_none(&self) -> bool {
        self == &Self::NoMiniArena
    }

    /// Iterate over all mini arena locators in this configuration.
    pub fn iter_locators(&self) -> impl Iterator<Item = MiniArenaLocator> + use<> {
        let res = match self {
            Self::NoMiniArena => vec![MiniArenaLocator::from_mini_arena_idx(0)],
            Self::XYGrid(xy_grid_config) => {
                let sz = xy_grid_config.x_centers.0.len() * xy_grid_config.y_centers.0.len();
                (0..sz)
                    .map(|idx| MiniArenaLocator::from_mini_arena_idx(idx.try_into().unwrap()))
                    .collect()
            }
        };
        res.into_iter()
    }

    /// Get the number of mini arenas in this configuration.
    pub fn len(&self) -> usize {
        match self {
            Self::NoMiniArena => 1,
            Self::XYGrid(xy_grid_config) => {
                xy_grid_config.x_centers.0.len() * xy_grid_config.y_centers.0.len()
            }
        }
    }
}

/// Sorted list of floating point values for efficient nearest neighbor search.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
struct Sorted(Vec<f64>);

impl Sorted {
    fn new(vals: &[f64]) -> Self {
        assert!(!vals.is_empty());
        let mut vals: Vec<NotNan<f64>> = vals.iter().map(|v| NotNan::new(*v).unwrap()).collect();
        vals.sort();
        let vals = vals.iter().map(|v| v.into_inner()).collect();
        Sorted(vals)
    }
    fn dist_and_argmin(&self, x: f64) -> (f64, usize) {
        let mut best_dist = f64::INFINITY;
        let mut prev_dist = f64::INFINITY;
        let mut best_idx = 0;
        for (i, selfi) in self.0.iter().enumerate() {
            let dist = (selfi - x).abs();
            if dist < best_dist {
                best_dist = dist;
                best_idx = i;
            }
            if dist > prev_dist {
                // short circuit end of loop
                break;
            }
            prev_dist = dist
        }
        (best_dist, best_idx)
    }
}

#[test]
fn test_sorted() {
    let x = Sorted::new(&[1.0, 2.0, 1.0]);

    assert_eq!(x.0, vec![1.0, 1.0, 2.0]);
    assert_eq!(x.dist_and_argmin(1.1).1, 0);

    let x = Sorted::new(&[1.0, 2.0, 1.0, 3.0, 4.0]);
    assert_eq!(x.dist_and_argmin(2.1).1, 2);

    assert_eq!(x.dist_and_argmin(1.9).1, 2);
}

/// Parameters defining a 2D grid of mini arenas arranged along X and Y axes.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct XYGridConfig {
    x_centers: Sorted,
    y_centers: Sorted,
    radius: f64,
}

impl XYGridConfig {
    /// Create a new XYGrid configuration with specified centers and radius.
    pub fn new(x: &[f64], y: &[f64], radius: f64) -> Self {
        Self {
            x_centers: Sorted::new(x),
            y_centers: Sorted::new(y),
            radius,
        }
    }

    /// Iterate over all grid center coordinates.
    pub fn iter_centers(&self) -> impl Iterator<Item = (f64, f64)> + use<> {
        XYGridIter {
            col_centers: self.x_centers.0.clone(),
            row_centers: self.y_centers.0.clone(),
            next_idx: 0,
        }
    }

    /// Get the arena index for given 3D coordinates.
    pub fn get_arena_index(&self, coords: &[MyFloat; 3]) -> MiniArenaLocator {
        if coords[2] != 0.0 {
            return MiniArenaLocator::new_none();
        }
        let obj_x = coords[0];
        let obj_y = coords[1];

        let (dist_x, idx_x) = self.x_centers.dist_and_argmin(obj_x);
        let (dist_y, idx_y) = self.y_centers.dist_and_argmin(obj_y);

        let dist = (dist_x * dist_x + dist_y * dist_y).sqrt();
        if dist <= self.radius {
            let idx = (idx_y * self.x_centers.0.len() + idx_x).try_into().unwrap();
            MiniArenaLocator::from_mini_arena_idx(idx)
        } else {
            MiniArenaLocator::new_none()
        }
    }
}

struct XYGridIter {
    row_centers: Vec<f64>,
    col_centers: Vec<f64>,
    next_idx: usize,
}

impl Iterator for XYGridIter {
    type Item = (f64, f64);
    fn next(&mut self) -> Option<Self::Item> {
        let (row_idx, col_idx) = num_integer::div_rem(self.next_idx, self.col_centers.len());
        if row_idx >= self.row_centers.len() {
            None
        } else {
            let result = (self.col_centers[col_idx], self.row_centers[row_idx]);
            self.next_idx += 1;
            Some(result)
        }
    }
}

fn default_num_observations_to_visibility() -> u8 {
    // This number should suppress spurious trajectory births but not wait too
    // long before notifying listeners.
    3
}

/// Floating point type used for coordinates.
pub type MyFloat = f64;

/// Create default tracking parameters for full 3D tracking.
pub fn default_tracking_params_full_3d() -> TrackingParams {
    TrackingParams {
        motion_noise_scale: 0.1,
        initial_position_std_meters: 0.1,
        initial_vel_std_meters_per_sec: 1.0,
        accept_observation_min_likelihood: 1e-8,
        ekf_observation_covariance_pixels: 1.0,
        max_position_std_meters: 0.01212,
        hypothesis_test_params: Some(make_hypothesis_test_full3d_default()),
        num_observations_to_visibility: default_num_observations_to_visibility(),
        mini_arena_config: MiniArenaConfig::NoMiniArena,
    }
}

/// Create default tracking parameters for flat 3D tracking.
pub fn default_tracking_params_flat_3d() -> TrackingParams {
    TrackingParams {
        motion_noise_scale: 0.0005,
        initial_position_std_meters: 0.001,
        initial_vel_std_meters_per_sec: 0.02,
        accept_observation_min_likelihood: 0.00001,
        ekf_observation_covariance_pixels: 1.0,
        max_position_std_meters: 0.003,
        hypothesis_test_params: None,
        num_observations_to_visibility: 10,
        mini_arena_config: MiniArenaConfig::NoMiniArena,
    }
}

/// Parameters for hypothesis testing in track initialization.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HypothesisTestParams {
    /// Minimum number of cameras required for track initialization.
    pub minimum_number_of_cameras: u8,
    /// Maximum acceptable error in hypothesis testing.
    pub hypothesis_test_max_acceptable_error: f64,
    /// Minimum pixel absolute z-score threshold.
    pub minimum_pixel_abs_zscore: f64,
}

/// Create default hypothesis testing parameters for full 3D tracking.
pub fn make_hypothesis_test_full3d_default() -> HypothesisTestParams {
    HypothesisTestParams {
        minimum_number_of_cameras: 2,
        hypothesis_test_max_acceptable_error: 5.0,
        minimum_pixel_abs_zscore: 0.0,
    }
}

/// Information about a connected camera.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct CamInfo {
    /// The raw camera name.
    pub name: RawCamName,
    /// The camera's synchronization state.
    pub state: ConnectedCameraSyncState,
    /// HTTP server information for the camera.
    pub strand_cam_http_server_info: BuiServerInfo,
    /// Recent statistics for the camera.
    pub recent_stats: RecentStats,
}

/// API callback messages sent to Braid.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub enum BraidHttpApiCallback {
    /// Called from strand-cam to register a camera
    ///
    /// Note this is different than the `cam_info_handler` which only queries
    /// for the appropriate camera configuration.
    NewCamera(RegisterNewCamera),
    /// Called from strand-cam to update the current image
    UpdateCurrentImage(PerCam<UpdateImage>),
    /// Called from strand-cam to update the current camera settings (e.g.
    /// exposure time)
    UpdateCamSettings(PerCam<UpdateCamSettings>),
    /// Called from strand-cam to update the current feature detection settings
    /// (e.g. threshold different)
    UpdateFeatureDetectSettings(PerCam<UpdateFeatureDetectSettings>),
    /// Start or stop recording data (.braid directory with csv tables for later
    /// .braidz file)
    DoRecordCsvTables(bool),
    /// Start or stop recording MKV videos for all cameras
    DoRecordMp4Files(bool),
    /// set uuid in the experiment_info table
    SetExperimentUuid(String),
    /// Set the number of frames to buffer in each camera
    SetPostTriggerBufferSize(usize),
    /// Initiate MKV recording using post trigger
    PostTriggerMp4Recording,
    /// Take a new background image on all cameras.
    ///
    /// Each camera re-initializes the background model used for feature
    /// detection from its currently incoming images.
    DoTakeNewBackgroundImage,
    /// Enable or disable continuous background model updating on all cameras.
    SetBackgroundUpdating(bool),
    /// Quit Braid.
    ///
    /// This stops recording (closing all files), commands all connected
    /// cameras to quit, and then exits.
    DoQuit,
}

/// Wrapper for per-camera data.
#[derive(Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
pub struct PerCam<T> {
    /// The raw camera name.
    pub raw_cam_name: RawCamName,
    /// The wrapped data.
    pub inner: T,
}

/// Raw UDP packet containing 2D feature detections.
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FlydraRawUdpPacket {
    /// The name of the camera
    ///
    /// Traditionally this was the ROS camera name (e.g. with '-' converted to
    /// '_'), but have transitioned to allowing any valid UTF-8 string.
    pub cam_name: String,
    /// frame timestamp of trigger pulse start (or None if cannot be determined)
    #[serde(with = "crate::timestamp_opt_f64")]
    pub timestamp: Option<FlydraFloatTimestampLocal<Triggerbox>>,
    /// frame timestamp of camnode program sampling system clock
    #[serde(with = "crate::timestamp_f64")]
    pub cam_received_time: FlydraFloatTimestampLocal<HostClock>,
    /// timestamp from the camera
    pub device_timestamp: Option<u64>,
    /// frame number from the camera
    pub block_id: Option<u64>,
    /// Frame number from the camera.
    pub framenumber: i32,
    /// Detected 2D points in the frame.
    pub points: Vec<FlydraRawUdpPoint>,
}

mod synced_frame;
pub use synced_frame::SyncFno;

mod cam_num;
pub use cam_num::CamNum;

mod timestamp;
pub use crate::timestamp::{
    FlydraFloatTimestampLocal, HostClock, Source, Triggerbox, triggerbox_time,
};

/// Timestamp serialization for f64 format.
pub mod timestamp_f64;
/// Timestamp serialization for optional f64 format.
pub mod timestamp_opt_f64;

#[cfg(feature = "with-tokio-codec")]
mod tokio_cbor;
#[cfg(feature = "with-tokio-codec")]
pub use crate::tokio_cbor::CborPacketCodec;

/// Error types for Flydra operations.
#[derive(thiserror::Error, Debug)]
pub enum FlydraTypesError {
    #[error("CBOR data")]
    /// CBOR data error.
    CborDataError,
    #[error("serde error")]
    /// Serialization/deserialization error.
    SerdeError,
    #[error("unexpected hypothesis testing parameters")]
    /// Unexpected hypothesis testing parameters.
    UnexpectedHypothesisTestingParameters,
    #[error("input too long")]
    /// Input data too long.
    InputTooLong,
    #[error("long string not implemented")]
    /// Long string handling not implemented.
    LongStringNotImplemented,
    #[error("{0}")]
    /// I/O error.
    IoError(#[from] std::io::Error),
    #[error("{0}")]
    /// UTF-8 encoding error.
    Utf8Error(#[from] std::str::Utf8Error),
    #[error("URL parse error")]
    /// URL parsing error.
    UrlParseError,
}

/// Trigger clock information record for CSV output.
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct TriggerClockInfoRow {
    // backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition)
    #[serde(with = "crate::timestamp_f64")]
    /// Timestamp when recording started.
    pub start_timestamp: FlydraFloatTimestampLocal<HostClock>,
    /// Number of frames recorded.
    pub framecount: i64,
    /// Fraction of full framecount is tcnt/255
    /// Trigger counter value.
    pub tcnt: u8,
    #[serde(with = "crate::timestamp_f64")]
    /// Timestamp when recording stopped.
    pub stop_timestamp: FlydraFloatTimestampLocal<HostClock>,
}

/// Configuration for Triggerbox V1 hardware synchronization.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct TriggerboxConfig {
    /// Device filename for the triggerbox.
    pub device_fname: String,
    /// Frame rate for synchronized recording.
    pub framerate: f32,
    #[serde(default = "default_query_dt")]
    /// Query interval for triggerbox status.
    pub query_dt: std::time::Duration,
    /// Maximum acceptable measurement error.
    pub max_triggerbox_measurement_error: Option<std::time::Duration>,
}

impl std::default::Default for TriggerboxConfig {
    fn default() -> Self {
        Self {
            device_fname: "/dev/trig1".to_string(),
            framerate: 100.0,
            query_dt: default_query_dt(),
            // Make a relatively long default so that cameras will synchronize
            // even with relatively long delays. Users can always specify
            // tighter precision within a config file.
            max_triggerbox_measurement_error: Some(std::time::Duration::from_millis(20)),
        }
    }
}

const fn default_query_dt() -> std::time::Duration {
    std::time::Duration::from_millis(1500)
}

/// Configuration for PTP (Precision Time Protocol) synchronization.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct PtpSyncConfig {
    /// The period of the periodic signal.
    ///
    /// If this is set, it is transmitted to the cameras.
    pub periodic_signal_period_usec: Option<f64>,
}

/// Configuration for fake synchronization (no real synchronization).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct FakeSyncConfig {
    /// Simulated frame rate.
    pub framerate: f64,
}

impl Default for FakeSyncConfig {
    fn default() -> Self {
        Self { framerate: 95.0 }
    }
}

/// Camera synchronization method configuration.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
#[serde(tag = "trigger_type")]
pub enum TriggerType {
    /// Cameras are synchronized via hardware triggers controlled
    /// via a [Straw Lab triggerbox](https://github.com/strawlab/triggerbox).
    TriggerboxV1(TriggerboxConfig),
    /// Cameras are synchronized using PTP (Precision Time Protocol, IEEE 1588).
    PtpSync(PtpSyncConfig),
    /// Cameras are synchronized using device timestamps.
    DeviceTimestamp,
    /// Cameras are not synchronized, but we pretend they are.
    FakeSync(FakeSyncConfig),
}

impl Default for TriggerType {
    fn default() -> Self {
        TriggerType::FakeSync(FakeSyncConfig::default())
    }
}

/// Feature detection data in raw camera coordinates.
///
/// Because these are in raw camera coordinates (and thus have not been
/// undistorted with any lens distortion model), they are called "distorted".
///
/// Note that in `.braidz` files, subsequent rows on disk are not in general
/// monotonically increasing in frame number.
///
/// See the "Details about how data are processed online and saved for later
/// analysis" section in the "3D Tracking in Braid" chapter of the [User's
/// Guide](https://strawlab.github.io/strand-braid/) for a description of why
/// these cannot be relied upon in `.braidz` files to be monotonic.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Data2dDistortedRow {
    // backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition)
    // should be kept in sync with Data2dDistortedRowF32
    /// The number of the camera.
    pub camn: CamNum,
    /// The synchronized frame number.
    ///
    /// This is very likely to be different than [Self::block_id], the camera's
    /// internal frame number, because Braid synchronizes the frames so that,
    /// e.g. "frame 10" occurred at the same instant across all cameras.
    pub frame: i64,
    /// This is the trigger timestamp (if available).
    #[serde(with = "crate::timestamp_opt_f64")]
    pub timestamp: Option<FlydraFloatTimestampLocal<Triggerbox>>,
    #[serde(with = "crate::timestamp_f64")]
    /// Timestamp when the camera received the frame.
    pub cam_received_timestamp: FlydraFloatTimestampLocal<HostClock>,
    /// Timestamp from the camera.
    pub device_timestamp: Option<u64>,
    /// Frame number from the camera.
    ///
    /// Note that this is not the synchronized frame number, which is [Self::frame].
    pub block_id: Option<u64>,
    /// The X (horizontal) coordinate of the detection, in camera pixels.
    #[serde(deserialize_with = "invalid_nan")]
    pub x: f64,
    /// The Y (vertical) coordinate of the detection, in camera pixels.
    #[serde(deserialize_with = "invalid_nan")]
    pub y: f64,
    /// The area of the detection, in camera pixels^2.
    #[serde(deserialize_with = "invalid_nan")]
    pub area: f64,
    /// The slope of the detection.
    ///
    /// The orientation, modulo 𝜋, of the detection, is `atan(slope)`.
    #[serde(deserialize_with = "invalid_nan")]
    pub slope: f64,
    /// The eccentricity of the detection.
    #[serde(deserialize_with = "invalid_nan")]
    pub eccentricity: f64,
    /// The index of this particular detection within a given frame.
    ///
    /// Multiple detections can occur within a single frame, and each succesive
    /// detection will have a higher index.
    pub frame_pt_idx: u8,
    /// Current pixel value.
    pub cur_val: u8,
    #[serde(deserialize_with = "invalid_nan")]
    /// Mean pixel value.
    pub mean_val: f64,
    #[serde(deserialize_with = "invalid_nan")]
    /// Sum of squares of pixel values.
    pub sumsqf_val: f64,
}

/// Lower precision version of [Data2dDistortedRow] for saving to disk.
// Note that this matches the precision specified in the old flydra Python
// module `flydra_core.data_descriptions.Info2D`.
#[derive(Debug, Serialize)]
pub struct Data2dDistortedRowF32 {
    // backward-incompatible changes here require a BRAID_SCHEMA bump (see its definition)
    /// The number of the camera.
    pub camn: CamNum,
    /// The synchronized frame number.
    ///
    /// This is very likely to be different than [Self::block_id], the camera's
    /// internal frame number, because Braid synchronizes the frames so that,
    /// e.g. "frame 10" occurred at the same instant across all cameras.
    pub frame: i64,
    /// This is the trigger timestamp (if available).
    #[serde(with = "crate::timestamp_opt_f64")]
    pub timestamp: Option<FlydraFloatTimestampLocal<Triggerbox>>,
    #[serde(with = "crate::timestamp_f64")]
    /// Timestamp when the camera received the frame.
    pub cam_received_timestamp: FlydraFloatTimestampLocal<HostClock>,
    /// timestamp from the camera
    pub device_timestamp: Option<u64>,
    /// Frame number from the camera.
    ///
    /// Note that this is not the synchronized frame number, which is [Self::frame].
    pub block_id: Option<u64>,
    /// The X (horizontal) coordinate of the detection, in camera pixels.
    pub x: f32,
    /// The Y (vertial) coordinate of the detection, in camera pixels.
    pub y: f32,
    /// The area of the detection, in camera pixels^2.
    pub area: f32,
    /// The slope of the detection.
    ///
    /// The orientation, modulo 𝜋, of the detection, is `atan(slope)`.
    pub slope: f32,
    /// The eccentricity of the detection.
    pub eccentricity: f32,
    /// The index of this particular detection within a given frame.
    ///
    /// Multiple detections can occur within a single frame, and each succesive
    /// detection will have a higher index.
    pub frame_pt_idx: u8,
    /// Current pixel value.
    pub cur_val: u8,
    /// Mean pixel value.
    pub mean_val: f32,
    /// Sum of squares of pixel values.
    pub sumsqf_val: f32,
}

impl From<Data2dDistortedRow> for Data2dDistortedRowF32 {
    fn from(orig: Data2dDistortedRow) -> Self {
        Self {
            camn: orig.camn,
            frame: orig.frame,
            timestamp: orig.timestamp,
            cam_received_timestamp: orig.cam_received_timestamp,
            device_timestamp: orig.device_timestamp,
            block_id: orig.block_id,
            x: orig.x as f32,
            y: orig.y as f32,
            area: orig.area as f32,
            slope: orig.slope as f32,
            eccentricity: orig.eccentricity as f32,
            frame_pt_idx: orig.frame_pt_idx,
            cur_val: orig.cur_val,
            mean_val: orig.mean_val as f32,
            sumsqf_val: orig.sumsqf_val as f32,
        }
    }
}

impl WithKey<i64> for Data2dDistortedRow {
    fn key(&self) -> i64 {
        self.frame
    }
}

fn invalid_nan<'de, D>(de: D) -> Result<f64, D::Error>
where
    D: Deserializer<'de>,
{
    f64::deserialize(de).or(
        // TODO: should match on DeserializeError with empty field only,
        // otherwise, return error. The way this is written, anything
        // will return a nan.
        Ok(f64::NAN),
    )
}

/// URL path for Braid events endpoint.
pub const BRAID_EVENTS_URL_PATH: &str = "braid-events";
/// Event name for Braid events.
pub const BRAID_EVENT_NAME: &str = "braid";
/// Event name for the server-is-quitting SSE message.
///
/// Broadcast to every connected browser just before the server shuts down so
/// that all clients (not only the one that initiated the quit) show the "Braid
/// has quit" screen and stop trying to reconnect.
pub const BRAID_QUIT_EVENT_NAME: &str = "braid-quit";