lidar

type AcceptanceMetrics struct {
	BucketsMeters []float64
	AcceptCounts  []int64
	RejectCounts  []int64
}

type AnalysisRun struct {
	RunID            string          `json:"run_id"`
	CreatedAt        time.Time       `json:"created_at"`
	SourceType       string          `json:"source_type"` // "pcap" or "live"
	SourcePath       string          `json:"source_path,omitempty"`
	SensorID         string          `json:"sensor_id"`
	ParamsJSON       json.RawMessage `json:"params_json"`
	DurationSecs     float64         `json:"duration_secs"`
	TotalFrames      int             `json:"total_frames"`
	TotalClusters    int             `json:"total_clusters"`
	TotalTracks      int             `json:"total_tracks"`
	ConfirmedTracks  int             `json:"confirmed_tracks"`
	ProcessingTimeMs int64           `json:"processing_time_ms"`
	Status           string          `json:"status"` // "running", "completed", "failed"
	ErrorMessage     string          `json:"error_message,omitempty"`
	ParentRunID      string          `json:"parent_run_id,omitempty"`
	Notes            string          `json:"notes,omitempty"`
}

type AnalysisRunManager struct {
	// contains filtered or unexported fields
}

type AnalysisRunStore struct {
	// contains filtered or unexported fields
}

type AnalysisStats struct {
	DurationSecs     float64
	TotalFrames      int
	TotalClusters    int
	TotalTracks      int
	ConfirmedTracks  int
	ProcessingTimeMs int64
}

type BackgroundCell struct {
	AverageRangeMeters   float32
	RangeSpreadMeters    float32
	TimesSeenCount       uint32
	LastUpdateUnixNanos  int64
	FrozenUntilUnixNanos int64
	// RecentForegroundCount tracks consecutive foreground observations.
	// Used for fast re-acquisition: when this is >0 and observation matches
	// background, we apply boosted alpha for faster convergence.
	RecentForegroundCount uint16

	// LockedBaseline is the stable reference distance that only updates when
	// we have high confidence (TimesSeenCount > LockedThreshold). This protects
	// against transit corruption where EMA average drifts during occlusion.
	LockedBaseline float32
	// LockedSpread is the acceptable variance around LockedBaseline. Observations
	// within LockedBaseline ± (LockedSpread * multiplier) are considered background.
	// This allows per-cell variance (trees, glass have more variance).
	LockedSpread float32
	// LockedAtCount is the TimesSeenCount when baseline was last locked.
	// Used to detect when we should update the locked values.
	LockedAtCount uint32
}

type BackgroundGrid struct {
	SensorID    string
	SensorFrame FrameID // e.g., "sensor/hesai-01"

	Rings       int // e.g., 40 - matches schema rings INTEGER NOT NULL
	AzimuthBins int // e.g., 1800 for 0.2° - matches schema azimuth_bins INTEGER NOT NULL

	Cells []BackgroundCell // len = Rings * AzimuthBins

	Params BackgroundParams

	// Enhanced persistence tracking matching schema lidar_bg_snapshot table
	Manager              *BackgroundManager
	LastSnapshotTime     time.Time
	ChangesSinceSnapshot int
	SnapshotID           *int64 // tracks last persisted snapshot_id from schema

	// Performance tracking for system_events table integration
	LastProcessingTimeUs  int64
	WarmupFramesRemaining int
	SettlingComplete      bool

	// Telemetry for monitoring (feeds into system_events)
	ForegroundCount int64
	BackgroundCount int64

	// Simple range-bucketed acceptance metrics to help tune NoiseRelativeFraction.
	// Buckets are upper bounds in meters; counts are number of accepted/rejected
	// observations that fell into that distance bucket. These are incremented
	// inside ProcessFramePolar while holding g.mu, and can be read via
	// BackgroundManager.GetAcceptanceMetrics().
	AcceptanceBucketsMeters []float64
	AcceptByRangeBuckets    []int64
	RejectByRangeBuckets    []int64

	// Optional per-ring elevation angles (degrees) for converting polar->cartesian.
	// If populated (len == Rings) ToASCPoints will use these to compute Z = r*sin(elev).
	RingElevations []float64
	// LastObservedNoiseRel tracks the last noise_relative value observed by
	// ProcessFramePolar so we can log when the runtime value changes.
	LastObservedNoiseRel float32

	// RegionMgr handles adaptive parameter regions for different settling characteristics
	RegionMgr *RegionManager
	// contains filtered or unexported fields
}

type BackgroundManager struct {
	Grid            *BackgroundGrid
	SettlingTimer   *time.Timer
	PersistTimer    *time.Timer
	HasSettled      bool
	LastPersistTime time.Time
	StartTime       time.Time

	// Persistence callback to main app - should save to schema lidar_bg_snapshot table
	PersistCallback func(snapshot *BgSnapshot) error
	// EnableDiagnostics controls whether this manager emits diagnostic messages
	// via the shared monitoring logger. Default: false.
	EnableDiagnostics bool
	// contains filtered or unexported fields
}

type BackgroundParams struct {
	BackgroundUpdateFraction       float32 // e.g., 0.02
	ClosenessSensitivityMultiplier float32 // e.g., 3.0
	SafetyMarginMeters             float32 // e.g., 0.5
	FreezeDurationNanos            int64   // e.g., 5e9 (5s)
	NeighborConfirmationCount      int     // e.g., 5 of 8 neighbors
	WarmupDurationNanos            int64   // optional extra settle time before emitting foreground
	WarmupMinFrames                int     // optional minimum frames before considering settled
	PostSettleUpdateFraction       float32 // optional lower alpha after settle for stability
	ForegroundMinClusterPoints     int     // min points for a cluster to be forwarded/considered
	ForegroundDBSCANEps            float32 // clustering radius for foreground gating
	// NoiseRelativeFraction is the fraction of range (distance) to treat as
	// expected measurement noise. This allows closeness thresholds to grow
	// with distance so that farther returns (which naturally have larger
	// absolute noise) aren't biased as foreground. Typical values: 0.01
	// (1%) to 0.02 (2%). If zero, a sensible default (0.01) is used.
	NoiseRelativeFraction float32

	// SeedFromFirstObservation, when true, will initialize empty background cells
	// from the first observation seen for that cell. This is useful for PCAP
	// replay mode where there is no prior live-warmup data; default: false.
	SeedFromFirstObservation bool

	// ReacquisitionBoostMultiplier controls how much faster cells re-acquire
	// background after a foreground event. When a cell that recently saw foreground
	// receives an observation matching the prior background, the effective alpha
	// is multiplied by this factor for faster convergence. Default: 5.0.
	// Set to 1.0 to disable the boost.
	ReacquisitionBoostMultiplier float32

	// MinConfidenceFloor is the minimum TimesSeenCount to preserve during foreground
	// observations. This prevents cells from completely "forgetting" their settled
	// background when a vehicle passes through. Default: 3.
	MinConfidenceFloor uint32

	// LockedBaselineThreshold is the minimum TimesSeenCount before we lock the
	// baseline. Once locked, the baseline only updates slowly. Default: 50.
	LockedBaselineThreshold uint32
	// LockedBaselineMultiplier controls how many times the LockedSpread defines
	// the acceptance window. Observations within LockedBaseline ± (LockedSpread *
	// LockedBaselineMultiplier) are considered background. Default: 4.0.
	LockedBaselineMultiplier float32

	// Debug logging region (only active if EnableDiagnostics is true)
	DebugRingMin int     // Min ring index (inclusive)
	DebugRingMax int     // Max ring index (inclusive)
	DebugAzMin   float32 // Min azimuth degrees (inclusive)
	DebugAzMax   float32 // Max azimuth degrees (inclusive)

	// Additional params for persistence matching schema requirements
	SettlingPeriodNanos        int64 // 5 minutes before first snapshot
	SnapshotIntervalNanos      int64 // 2 hours between snapshots
	ChangeThresholdForSnapshot int   // min changed cells to trigger snapshot
}

type BackgroundParamsExport struct {
	BackgroundUpdateFraction       float32 `json:"background_update_fraction"`
	ClosenessSensitivityMultiplier float32 `json:"closeness_sensitivity_multiplier"`
	SafetyMarginMeters             float32 `json:"safety_margin_meters"`
	NeighborConfirmationCount      int     `json:"neighbor_confirmation_count"`
	NoiseRelativeFraction          float32 `json:"noise_relative_fraction"`
	SeedFromFirstObservation       bool    `json:"seed_from_first_observation"`
	FreezeDurationNanos            int64   `json:"freeze_duration_nanos"`
}

type BgSnapshot struct {
	SnapshotID         *int64 // will be set by database after insert
	SensorID           string // matches sensor_id TEXT NOT NULL
	TakenUnixNanos     int64  // matches taken_unix_nanos INTEGER NOT NULL
	Rings              int    // matches rings INTEGER NOT NULL
	AzimuthBins        int    // matches azimuth_bins INTEGER NOT NULL
	ParamsJSON         string // matches params_json TEXT NOT NULL
	RingElevationsJSON string // matches ring_elevations_json TEXT NULL - optional per-ring elevation JSON
	GridBlob           []byte // matches grid_blob BLOB NOT NULL (compressed BackgroundCell data)
	ChangedCellsCount  int    // matches changed_cells_count INTEGER
	SnapshotReason     string // matches snapshot_reason TEXT ('settling_complete', 'periodic_update', 'manual')
}

type BgStore interface {
	InsertBgSnapshot(s *BgSnapshot) (int64, error)
}

type ClassificationFeatures struct {
	// Spatial features
	AvgHeight float32 // Average bounding box height
	AvgLength float32 // Average bounding box length
	AvgWidth  float32 // Average bounding box width
	HeightP95 float32 // Maximum P95 height

	// Kinematic features
	AvgSpeed  float32 // Average speed
	PeakSpeed float32 // Peak speed
	P50Speed  float32 // Median speed
	P85Speed  float32 // 85th percentile speed
	P95Speed  float32 // 95th percentile speed

	// Temporal features
	ObservationCount int
	DurationSecs     float32
}

type ClassificationParamsExport struct {
	ModelType  string                 `json:"model_type"`
	Thresholds map[string]interface{} `json:"thresholds,omitempty"`
}

type ClassificationResult struct {
	Class      ObjectClass
	Confidence float32
	Model      string // Model version used
	Features   ClassificationFeatures
}

type ClusteringParamsExport struct {
	Eps      float64 `json:"eps"`
	MinPts   int     `json:"min_pts"`
	CellSize float64 `json:"cell_size,omitempty"`
}

type CoarseBucket struct {
	Ring            int     `json:"ring"`
	AzimuthDegStart float64 `json:"azimuth_deg_start"`
	AzimuthDegEnd   float64 `json:"azimuth_deg_end"`
	TotalCells      int     `json:"total_cells"`
	FilledCells     int     `json:"filled_cells"`
	SettledCells    int     `json:"settled_cells"`
	FrozenCells     int     `json:"frozen_cells"`
	MeanTimesSeen   float64 `json:"mean_times_seen"`
	MeanRangeMeters float64 `json:"mean_range_meters"`
	MinRangeMeters  float64 `json:"min_range_meters"`
	MaxRangeMeters  float64 `json:"max_range_meters"`
}

type DBSCANParams struct {
	Eps    float64 // Neighborhood radius in meters
	MinPts int     // Minimum points to form a cluster
}

type Event struct {
	When    time.Time              // event timestamp
	Level   string                 // "info", "warn", "error", "debug"
	Message string                 // human-readable message
	Context map[string]interface{} // structured context data

	// Schema integration fields
	SensorID  *string // sensor that generated the event (if applicable)
	EventType string  // maps to system_events.event_type for persistence
}

type ExportedCell struct {
	Ring        int
	AzimuthDeg  float32
	Range       float32
	Spread      float32
	TimesSeen   uint32
	LastUpdate  int64
	FrozenUntil int64
}

type ForegroundForwarder interface {
	ForwardForeground(points []PointPolar)
}

type ForegroundFrame struct {
	SensorID         string       // Sensor that captured this frame
	TSUnixNanos      int64        // Timestamp of the frame
	SequenceID       string       // Optional sequence grouping (e.g., "seq_20251130_001")
	ForegroundPoints []PointPolar // Foreground points in polar (sensor) frame

	// Frame statistics
	TotalPoints      int
	BackgroundPoints int
}

type ForegroundSnapshot struct {
	SensorID         string
	Timestamp        time.Time
	ForegroundPoints []ProjectedPoint
	BackgroundPoints []ProjectedPoint
	TotalPoints      int
	ForegroundCount  int
	BackgroundCount  int
}

type FrameBuilder struct {
	// contains filtered or unexported fields
}

type FrameBuilderConfig struct {
	SensorID              string            // sensor identifier
	FrameCallback         func(*LiDARFrame) // callback when frame is complete
	AzimuthTolerance      float64           // tolerance for azimuth wrap detection (default: 10°)
	MinFramePoints        int               // minimum points required for valid frame (default: 1000)
	MaxBackfillDelay      time.Duration     // max time to wait for backfill packets (default: 100ms)
	FrameBufferSize       int               // max frames to buffer (default: 10)
	BufferTimeout         time.Duration     // how long to wait before finalizing frame (default: 1s)
	CleanupInterval       time.Duration     // how often to check for frames to finalize (default: 250ms)
	ExpectedFrameDuration time.Duration     // expected duration per frame based on motor speed (default: 0 = azimuth-only)
	EnableTimeBased       bool              // true to use time-based detection with azimuth validation
}

type FrameID string

type FrameMetrics struct {
	TotalPoints        int     `json:"total_points"`
	ForegroundPoints   int     `json:"foreground_points"`
	BackgroundPoints   int     `json:"background_points"`
	ForegroundFraction float64 `json:"foreground_fraction"`
	ProcessingTimeUs   int64   `json:"processing_time_us"`
}

type FrameStats struct {
	TSUnixNanos      int64
	PacketsReceived  int
	PointsTotal      int
	ForegroundPoints int
	ClustersFound    int
	TracksActive     int
	ProcessingTimeUs int64

	// Additional metrics for 100-track monitoring
	MemoryUsageMB   int64
	CPUUsagePercent float32
	DroppedPackets  int64
}

type GridHeatmap struct {
	SensorID      string                 `json:"sensor_id"`
	Timestamp     time.Time              `json:"timestamp"`
	GridParams    map[string]interface{} `json:"grid_params"`
	HeatmapParams map[string]interface{} `json:"heatmap_params"`
	Summary       map[string]interface{} `json:"summary"`
	Buckets       []CoarseBucket         `json:"buckets"`
}

type LiDARFrame struct {
	FrameID        string    // unique identifier for this frame
	SensorID       string    // which sensor generated this frame
	StartTimestamp time.Time // timestamp of first point in frame
	EndTimestamp   time.Time // timestamp of last point in frame
	StartWallTime  time.Time // wall-clock time when frame started (ingest time)
	EndWallTime    time.Time // wall-clock time when last point was ingested
	Points         []Point   // all points in this complete rotation
	MinAzimuth     float64   // minimum azimuth angle observed
	MaxAzimuth     float64   // maximum azimuth angle observed
	PointCount     int       // total number of points in frame
	SpinComplete   bool      // true when full 360° rotation detected

	// Completeness tracking
	ExpectedPackets   map[uint32]bool // expected UDP sequence numbers
	ReceivedPackets   map[uint32]bool // received UDP sequence numbers
	MissingPackets    []uint32        // sequence numbers of missing packets
	PacketGaps        int             // count of missing packets
	CompletenessRatio float64         // ratio of received/expected packets
	AzimuthCoverage   float64         // degrees of azimuth covered (0-360)
}

type NoiseCoverageMetrics struct {
	TotalTracks         int                `json:"total_tracks"`
	TracksWithHighNoise int                `json:"tracks_with_high_noise"`       // noise_ratio > 0.3
	TracksUnknownClass  int                `json:"tracks_unknown_class"`         // object_class == "other"
	TracksLowConfidence int                `json:"tracks_low_confidence"`        // object_confidence < 0.6
	UnknownRatioBySpeed map[string]float32 `json:"unknown_ratio_by_speed"`       // "slow"/"medium"/"fast"
	UnknownRatioBySize  map[string]float32 `json:"unknown_ratio_by_size"`        // "small"/"medium"/"large"
	NoiseRatioHistogram []int              `json:"noise_ratio_histogram_counts"` // Counts for bins [0-0.1, 0.1-0.2, ...]
}

type ObjectClass string

type Point struct {
	// 3D Cartesian coordinates (computed from spherical measurements)
	X float64 `json:"x"` // X coordinate in meters (forward direction from sensor)
	Y float64 `json:"y"` // Y coordinate in meters (right direction from sensor)
	Z float64 `json:"z"` // Z coordinate in meters (upward direction from sensor)

	// Measurement metadata
	Intensity uint8     `json:"intensity"` // Laser return intensity/reflectivity (0-255)
	Distance  float64   `json:"distance"`  // Radial distance from sensor in meters
	Azimuth   float64   `json:"azimuth"`   // Horizontal angle in degrees (0-360, corrected)
	Elevation float64   `json:"elevation"` // Vertical angle in degrees (corrected for channel)
	Channel   int       `json:"channel"`   // Laser channel number (1-40)
	Timestamp time.Time `json:"timestamp"` // Point acquisition time (with firetime correction)
	BlockID   int       `json:"block_id"`  // Data block index within packet (0-9)

	// Packet tracking for completeness validation
	UDPSequence     uint32 `json:"udp_sequence"`      // UDP sequence number for gap detection
	RawBlockAzimuth uint16 `json:"raw_block_azimuth"` // Original block azimuth from packet (0.01 deg units)
}

type PointASC struct {
	X, Y, Z   float64
	Intensity int
	Extra     []interface{}
}

type PointPolar struct {
	Channel         int
	Azimuth         float64
	Elevation       float64
	Distance        float64
	Intensity       uint8
	Timestamp       int64 // unix nanos if needed; keep small to avoid heavy time usage
	BlockID         int
	UDPSequence     uint32
	RawBlockAzimuth uint16 // Original block azimuth from packet (0.01 deg units)
}

type PolarPointCompact struct {
	DistanceCm        uint16 // Distance in centimeters (0-655.35m range)
	AzimuthCentideg   uint16 // Azimuth in centidegrees (0-36000 = 0-360°)
	ElevationCentideg int16  // Elevation in centidegrees (-18000 to +18000 = -180° to +180°)
	Intensity         uint8  // Laser return intensity
	Ring              uint8  // Ring/channel number
}

type Pose struct {
	PoseID                    int64       // matches pose_id INTEGER PRIMARY KEY
	SensorID                  string      // matches sensor_id TEXT NOT NULL
	FromFrame                 FrameID     // matches from_frame TEXT NOT NULL
	ToFrame                   FrameID     // matches to_frame TEXT NOT NULL
	T                         [16]float64 // matches T_rowmajor_4x4 BLOB (16 floats)
	ValidFromNanos            int64       // matches valid_from_ns INTEGER NOT NULL
	ValidToNanos              *int64      // matches valid_to_ns INTEGER (NULL = current)
	Method                    string      // matches method TEXT
	RootMeanSquareErrorMeters float32     // matches root_mean_square_error_meters REAL
}

type PoseCache struct {
	BySensorID map[string]*Pose
	WorldFrame FrameID // canonical site frame (e.g., "site/main-st-001")

}

type ProjectedPoint struct {
	X         float64
	Y         float64
	Z         float64
	Intensity uint8
}

type Region struct {
	ID       int          // unique region identifier
	CellMask []bool       // len = Rings * AzimuthBins; true if cell belongs to this region
	Params   RegionParams // parameters for this region
	CellList []int        // list of cell indices in this region (for efficient iteration)
	// Statistics for region characterization
	MeanVariance float64 // mean variance of cells in this region during settling
	CellCount    int     // number of cells in this region
}

type RegionDebugInfo struct {
	SensorID               string       `json:"sensor_id"`
	Timestamp              time.Time    `json:"timestamp"`
	IdentificationComplete bool         `json:"identification_complete"`
	IdentificationTime     time.Time    `json:"identification_time,omitempty"`
	FramesSampled          int          `json:"frames_sampled"`
	RegionCount            int          `json:"region_count"`
	Regions                []RegionInfo `json:"regions"`
	// Grid mapping: for each cell, which region it belongs to
	GridMapping []int `json:"grid_mapping"` // maps cell index to region ID
}

type RegionInfo struct {
	ID           int          `json:"id"`
	CellCount    int          `json:"cell_count"`
	MeanVariance float64      `json:"mean_variance"`
	Params       RegionParams `json:"params"`
	Cells        []struct {
		Ring       int     `json:"ring"`
		AzimuthDeg float32 `json:"azimuth_deg"`
	} `json:"cells,omitempty"` // Optional: can be large, include only on request
}

type RegionManager struct {
	Regions         []*Region // list of identified regions
	CellToRegionID  []int     // maps cell index to region ID (-1 if unassigned)
	SettlingMetrics struct {
		VariancePerCell []float64 // variance observed per cell during settling
		FramesSampled   int       // frames sampled for variance calculation
	}
	IdentificationComplete bool      // true once regions are identified
	IdentificationTime     time.Time // when regions were identified
}

type RegionParams struct {
	NoiseRelativeFraction     float32 `json:"noise_relative_fraction"`     // noise threshold for this region
	NeighborConfirmationCount int     `json:"neighbor_confirmation_count"` // neighbor confirmation for this region
	SettleUpdateFraction      float32 `json:"settle_update_fraction"`      // alpha during settling for this region
}

type RetentionConfig struct {
	MaxConcurrentTracks          int           // 100 - matches design target
	MaxTrackObservationsPerTrack int           // 1000 observations per track - ring buffer size
	MaxRecentClusters            int           // 10,000 recent clusters - memory management
	MaxTrackAge                  time.Duration // 30 minutes for inactive tracks
	BgSnapshotInterval           time.Duration // 2 hours - matches schema automatic persistence
	BgSnapshotRetention          time.Duration // 48 hours - cleanup old snapshots
	BgSettlingPeriod             time.Duration // 5 minutes before first persist

	// Enhanced cleanup policies for schema maintenance
	MaxTrackFeatureAge   time.Duration // 7 days - cleanup old feature vectors
	MaxSystemEventAge    time.Duration // 30 days - cleanup old performance metrics
	ClusterPruneInterval time.Duration // 1 hour - memory cleanup frequency
}

type RingBuffer[T any] struct {
	Items    []T
	Head     int
	Tail     int
	Size     int
	Capacity int
	// contains filtered or unexported fields
}

type RunComparison struct {
	Run1ID          string         `json:"run1_id"`
	Run2ID          string         `json:"run2_id"`
	ParamDiff       map[string]any `json:"param_diff,omitempty"`
	TracksOnlyRun1  []string       `json:"tracks_only_run1,omitempty"`
	TracksOnlyRun2  []string       `json:"tracks_only_run2,omitempty"`
	SplitCandidates []TrackSplit   `json:"split_candidates,omitempty"`
	MergeCandidates []TrackMerge   `json:"merge_candidates,omitempty"`
	MatchedTracks   []TrackMatch   `json:"matched_tracks,omitempty"`
}

type RunParams struct {
	Version        string                     `json:"version"`
	Timestamp      time.Time                  `json:"timestamp"`
	Background     BackgroundParamsExport     `json:"background"`
	Clustering     ClusteringParamsExport     `json:"clustering"`
	Tracking       TrackingParamsExport       `json:"tracking"`
	Classification ClassificationParamsExport `json:"classification,omitempty"`
}

type RunStatistics struct {
	// Track Quality Distribution
	AvgTrackLength    float32 `json:"avg_track_length_meters"`
	MedianTrackLength float32 `json:"median_track_length_meters"`
	AvgTrackDuration  float32 `json:"avg_track_duration_secs"`
	AvgOcclusionCount float32 `json:"avg_occlusion_count"`

	// Classification Distribution
	ClassCounts        map[string]int     `json:"class_counts"`
	ClassConfidenceAvg map[string]float32 `json:"class_confidence_avg"`
	UnknownRatio       float32            `json:"unknown_ratio"`

	// Noise & Coverage
	AvgNoiseRatio      float32 `json:"avg_noise_ratio"`
	AvgSpatialCoverage float32 `json:"avg_spatial_coverage"`

	// Track Lifecycle
	TentativeRatio          float32 `json:"tentative_ratio"`
	ConfirmedRatio          float32 `json:"confirmed_ratio"`
	AvgObservationsPerTrack int     `json:"avg_observations_per_track"`
}

type RunTrack struct {
	RunID   string `json:"run_id"`
	TrackID string `json:"track_id"`

	// Track fields (from TrackedObject)
	SensorID             string  `json:"sensor_id"`
	TrackState           string  `json:"track_state"`
	StartUnixNanos       int64   `json:"start_unix_nanos"`
	EndUnixNanos         int64   `json:"end_unix_nanos,omitempty"`
	ObservationCount     int     `json:"observation_count"`
	AvgSpeedMps          float32 `json:"avg_speed_mps"`
	PeakSpeedMps         float32 `json:"peak_speed_mps"`
	P50SpeedMps          float32 `json:"p50_speed_mps,omitempty"`
	P85SpeedMps          float32 `json:"p85_speed_mps,omitempty"`
	P95SpeedMps          float32 `json:"p95_speed_mps,omitempty"`
	BoundingBoxLengthAvg float32 `json:"bounding_box_length_avg"`
	BoundingBoxWidthAvg  float32 `json:"bounding_box_width_avg"`
	BoundingBoxHeightAvg float32 `json:"bounding_box_height_avg"`
	HeightP95Max         float32 `json:"height_p95_max"`
	IntensityMeanAvg     float32 `json:"intensity_mean_avg"`
	ObjectClass          string  `json:"object_class,omitempty"`
	ObjectConfidence     float32 `json:"object_confidence,omitempty"`
	ClassificationModel  string  `json:"classification_model,omitempty"`

	// User labels (for ML training)
	UserLabel       string  `json:"user_label,omitempty"`
	LabelConfidence float32 `json:"label_confidence,omitempty"`
	LabelerID       string  `json:"labeler_id,omitempty"`
	LabeledAt       int64   `json:"labeled_at,omitempty"`

	// Track quality flags
	IsSplitCandidate bool     `json:"is_split_candidate,omitempty"`
	IsMergeCandidate bool     `json:"is_merge_candidate,omitempty"`
	LinkedTrackIDs   []string `json:"linked_track_ids,omitempty"`
}

type SensorConfig struct {
	ModelName     string  // e.g., "Pandar40P"
	Channels      int     // Number of laser channels (40 for Pandar40P)
	MotorSpeedRPM float64 // Motor speed for packet metadata
	UDPPort       int     // Target UDP port (default 2368)
}

type SidecarState struct {
	Poses              *PoseCache                    // thread-safe pose management
	BackgroundManagers map[string]*BackgroundManager // enhanced with persistence
	Tracks             map[string]*Track             // up to 100 concurrent

	// Ring buffers sized for 100 tracks with thread safety
	RecentClusters   *RingBuffer[*WorldCluster]        // 10,000 capacity
	RecentTrackObs   map[string]*RingBuffer[*TrackObs] // 1000 per track
	RecentFrameStats *RingBuffer[*FrameStats]          // 1000 capacity

	// Performance monitoring for system_events integration
	TrackCount     int64
	DroppedPackets int64
	ActiveTracks   int64 // current number of active tracks
	TotalClusters  int64 // lifetime cluster count
	TotalFrames    int64 // lifetime frame count

	// Configuration
	Config *RetentionConfig

	// Schema integration hooks
	SystemEventCallback func(event *SystemEvent) error    // callback to persist system events
	ClusterCallback     func(cluster *WorldCluster) error // callback to persist clusters
	TrackObsCallback    func(obs *TrackObs) error         // callback to persist track observations
	// contains filtered or unexported fields
}

type SpatialIndex struct {
	CellSize float64
	Grid     map[int64][]int // Cell ID → point indices
}

type SystemEvent struct {
	EventID     *int64                 // auto-generated by database
	SensorID    *string                // NULL for system-wide events
	TSUnixNanos int64                  // event timestamp
	EventType   string                 // 'performance', 'track_initiate', etc.
	EventData   map[string]interface{} // JSON data specific to event type
}

type Track struct {
	// Core identification matching schema exactly
	TrackID    string  // matches track_id TEXT PRIMARY KEY
	SensorID   string  // matches sensor_id TEXT NOT NULL
	WorldFrame FrameID // matches world_frame TEXT NOT NULL
	PoseID     int64   // matches pose_id INTEGER NOT NULL

	// Lifecycle timestamps matching schema
	FirstUnixNanos int64 // matches start_unix_nanos INTEGER NOT NULL
	LastUnixNanos  int64 // matches end_unix_nanos INTEGER (NULL if active)

	// Current state for real-time tracking
	State TrackState2D

	// Running averages matching schema summary fields
	BoundingBoxLengthAvg, BoundingBoxWidthAvg, BoundingBoxHeightAvg float32 // matches bounding_box_length_avg, bounding_box_width_avg, bounding_box_height_avg REAL

	// Rollups for features/training matching schema fields
	ObservationCount int     // matches observation_count INTEGER
	AvgSpeedMps      float32 // matches avg_speed_mps REAL
	PeakSpeedMps     float32 // matches peak_speed_mps REAL
	HeightP95Max     float32 // matches height_p95_max REAL
	IntensityMeanAvg float32 // matches intensity_mean_avg REAL

	// Classification matching schema
	ClassLabel      string  // matches class_label TEXT
	ClassConfidence float32 // matches class_conf REAL

	// Source tracking matching schema (LiDAR-only implementation)
	SourceMask uint8 // matches source_mask INTEGER (bit0=lidar only for now)

	// Life-cycle management (in-memory only)
	Misses int // consecutive misses for deletion
}

type TrackClassifier struct {
	ModelVersion string
}

type TrackMatch struct {
	Track1ID   string  `json:"track1_id"`
	Track2ID   string  `json:"track2_id"`
	OverlapPct float32 `json:"overlap_pct"`
}

type TrackMerge struct {
	MergedTrack  string   `json:"merged_track"`
	SourceTracks []string `json:"source_tracks"`
	MergeX       float32  `json:"merge_x"`
	MergeY       float32  `json:"merge_y"`
	Confidence   float32  `json:"confidence"`
}

type TrackObs struct {
	TrackID    string  // matches track_id TEXT NOT NULL
	UnixNanos  int64   // matches ts_unix_nanos INTEGER NOT NULL
	WorldFrame FrameID // matches world_frame TEXT NOT NULL
	PoseID     int64   // matches pose_id INTEGER NOT NULL

	// Position matching schema
	X, Y, Z float32 // matches x, y, z REAL

	// Velocity matching schema
	VelocityX, VelocityY, VelocityZ float32 // matches velocity_x, velocity_y, velocity_z REAL

	// Derived kinematics matching schema
	SpeedMps   float32 // matches speed_mps REAL
	HeadingRad float32 // matches heading_rad REAL

	// Shape matching schema
	BoundingBoxLength, BoundingBoxWidth, BoundingBoxHeight float32 // matches bounding_box_length, bounding_box_width, bounding_box_height REAL

	// Quality metrics matching schema
	HeightP95     float32 // matches height_p95 REAL
	IntensityMean float32 // matches intensity_mean REAL
}

type TrackObservation struct {
	TrackID     string
	TSUnixNanos int64
	WorldFrame  string

	// Position (world frame)
	X, Y, Z float32

	// Velocity (world frame)
	VelocityX, VelocityY float32
	SpeedMps             float32
	HeadingRad           float32

	// Shape
	BoundingBoxLength float32
	BoundingBoxWidth  float32
	BoundingBoxHeight float32
	HeightP95         float32
	IntensityMean     float32
}

type TrackPoint struct {
	X         float32
	Y         float32
	Timestamp int64 // Unix nanos
}

type TrackPointCloudExporter struct {
	// contains filtered or unexported fields
}

type TrackPointCloudFrame struct {
	TrackID     string       // Track identifier
	FrameIndex  int          // Frame sequence number within track
	Timestamp   time.Time    // Frame timestamp
	PolarPoints []PointPolar // Points in polar coordinates
}

type TrackPointCloudMetadata struct {
	TrackID          string    `json:"track_id"`
	SensorID         string    `json:"sensor_id"`
	StartTime        time.Time `json:"start_time"`
	EndTime          time.Time `json:"end_time"`
	TotalFrames      int       `json:"total_frames"`
	TotalPoints      int       `json:"total_points"`
	ObjectClass      string    `json:"object_class,omitempty"`
	ObjectConfidence float32   `json:"object_confidence,omitempty"`
	// Phase 1 quality metrics
	TrackLength    float32 `json:"track_length_meters"`
	Duration       float32 `json:"duration_secs"`
	OcclusionCount int     `json:"occlusion_count"`
	QualityScore   float32 `json:"quality_score,omitempty"`
}

type TrackQualityMetrics struct {
	TrackID            string  `json:"track_id"`
	TrackLengthMeters  float32 `json:"track_length_meters"`
	TrackDurationSecs  float32 `json:"track_duration_secs"`
	OcclusionCount     int     `json:"occlusion_count"`
	MaxOcclusionFrames int     `json:"max_occlusion_frames"`
	SpatialCoverage    float32 `json:"spatial_coverage"`
	NoisePointRatio    float32 `json:"noise_point_ratio"`
	QualityScore       float32 `json:"quality_score"` // Composite quality metric (0-1)
}

type TrackSplit struct {
	OriginalTrack string   `json:"original_track"`
	SplitTracks   []string `json:"split_tracks"`
	SplitX        float32  `json:"split_x"`
	SplitY        float32  `json:"split_y"`
	Confidence    float32  `json:"confidence"`
}

type TrackState string

type TrackState2D struct {
	X, Y                 float32     // State vector in world frame: [x y velocity_x velocity_y]
	VelocityX, VelocityY float32     // Velocity components in world frame
	CovarianceMatrix     [16]float32 // Row-major covariance (4x4). float32 saves RAM for 100-track performance.
}

type TrackStore interface {
	InsertCluster(cluster *WorldCluster) (int64, error)
	InsertTrack(track *TrackedObject, worldFrame string) error
	UpdateTrack(track *TrackedObject, worldFrame string) error
	InsertTrackObservation(obs *TrackObservation) error
	ClearTracks(sensorID string) error
	GetTrack(trackID string) (*TrackedObject, error)
	GetActiveTracks(sensorID string, state string) ([]*TrackedObject, error)
	GetTracksInRange(sensorID string, state string, startNanos, endNanos int64, limit int) ([]*TrackedObject, error)
	GetTrackObservations(trackID string, limit int) ([]*TrackObservation, error)
	GetTrackObservationsInRange(sensorID string, startNanos, endNanos int64, limit int, trackID string) ([]*TrackObservation, error)
	GetRecentClusters(sensorID string, startNanos, endNanos int64, limit int) ([]*WorldCluster, error)
}

type TrackSummary struct {
	TrackID    string  // matches schema track_id TEXT PRIMARY KEY
	SensorID   string  // matches schema sensor_id TEXT NOT NULL
	WorldFrame FrameID // matches schema world_frame TEXT NOT NULL
	UnixNanos  int64   // current observation timestamp

	// Current kinematics (world frame; road-plane oriented)
	X, Y                 float32 // current position
	VelocityX, VelocityY float32 // current velocity
	SpeedMps             float32 // current speed magnitude
	HeadingRad           float32 // current heading

	// Current shape/quality
	BoundingBoxLength float32
	BoundingBoxWidth  float32
	BoundingBoxHeight float32
	PointsCount       int
	HeightP95         float32
	IntensityMean     float32

	// Classification from track summary
	ClassLabel      string  // matches schema class_label TEXT
	ClassConfidence float32 // matches schema class_conf REAL

	// Optional uncertainty (for advanced fusion)
	Covariance4x4 []float32 // flattened 4x4 covariance of [x y velocity_x velocity_y]
}

type TrackTrainingFilter struct {
	MinQualityScore   float32      // Minimum composite quality score (0-1)
	MinDuration       float32      // Minimum track duration (seconds)
	MinLength         float32      // Minimum track length (meters)
	MaxOcclusionRatio float32      // Maximum occlusion ratio (occlusions / observations)
	MinObservations   int          // Minimum observation count
	RequireClass      bool         // Only include tracks with assigned class
	AllowedStates     []TrackState // Allowed track states (e.g., only confirmed)
}

type TrackedObject struct {
	// Identity
	TrackID  string
	SensorID string
	State    TrackState

	// Lifecycle counters
	Hits   int // Consecutive successful associations
	Misses int // Consecutive missed associations

	// Timestamps
	FirstUnixNanos int64
	LastUnixNanos  int64

	// Kalman state (world frame): [x, y, vx, vy]
	X  float32 // Position X
	Y  float32 // Position Y
	VX float32 // Velocity X
	VY float32 // Velocity Y

	// Kalman covariance (4x4, row-major)
	P [16]float32

	// Aggregated features
	ObservationCount     int
	BoundingBoxLengthAvg float32
	BoundingBoxWidthAvg  float32
	BoundingBoxHeightAvg float32
	HeightP95Max         float32
	IntensityMeanAvg     float32
	AvgSpeedMps          float32
	PeakSpeedMps         float32

	// History of positions
	History []TrackPoint

	// Classification (Phase 3.4)
	ObjectClass         string  // Classification result: "pedestrian", "car", "bird", "other"
	ObjectConfidence    float32 // Classification confidence [0, 1]
	ClassificationModel string  // Model version used for classification

	// Phase 1: Track Quality Metrics
	TrackLengthMeters  float32 // Total distance traveled (meters)
	TrackDurationSecs  float32 // Total lifetime (seconds)
	OcclusionCount     int     // Number of missed frames (gaps)
	MaxOcclusionFrames int     // Longest gap in observations
	SpatialCoverage    float32 // % of bounding box covered by observations
	NoisePointRatio    float32 // Ratio of noise points to cluster points
	// contains filtered or unexported fields
}

type Tracker struct {
	Tracks      map[string]*TrackedObject
	NextTrackID int64
	Config      TrackerConfig

	// Last update timestamp for dt computation
	LastUpdateNanos int64
	// contains filtered or unexported fields
}

type TrackerConfig struct {
	MaxTracks               int           // Maximum number of concurrent tracks
	MaxMisses               int           // Consecutive misses before deletion
	HitsToConfirm           int           // Consecutive hits needed for confirmation
	GatingDistanceSquared   float32       // Squared gating distance for association (meters²)
	ProcessNoisePos         float32       // Process noise for position (σ²)
	ProcessNoiseVel         float32       // Process noise for velocity (σ²)
	MeasurementNoise        float32       // Measurement noise (σ²)
	DeletedTrackGracePeriod time.Duration // How long to keep deleted tracks before cleanup
}

type TrackingParamsExport struct {
	MaxTracks               int           `json:"max_tracks"`
	MaxMisses               int           `json:"max_misses"`
	HitsToConfirm           int           `json:"hits_to_confirm"`
	GatingDistanceSquared   float32       `json:"gating_distance_squared"`
	ProcessNoisePos         float32       `json:"process_noise_pos"`
	ProcessNoiseVel         float32       `json:"process_noise_vel"`
	MeasurementNoise        float32       `json:"measurement_noise"`
	DeletedTrackGracePeriod time.Duration `json:"deleted_track_grace_period_nanos"`
}

type TrackingPipelineConfig struct {
	BackgroundManager  *BackgroundManager
	FgForwarder        ForegroundForwarder // Use interface to avoid import cycle
	Tracker            *Tracker
	Classifier         *TrackClassifier
	DB                 *sql.DB // Use standard sql.DB to avoid import cycle with db package
	SensorID           string
	DebugMode          bool
	AnalysisRunManager *AnalysisRunManager // Optional: for recording analysis runs
}

type TrainingDataFilter struct {
	SensorID       string // Filter by sensor (empty = all)
	SequenceID     string // Filter by sequence (empty = all)
	MinForeground  int    // Minimum foreground points per frame
	AnnotationOnly bool   // Only return annotated frames
}

type TrainingDatasetSummary struct {
	TotalTracks       int            `json:"total_tracks"`
	TotalFrames       int            `json:"total_frames"`
	TotalPoints       int            `json:"total_points"`
	ClassDistribution map[string]int `json:"class_distribution"`
	AvgQualityScore   float32        `json:"avg_quality_score"`
	AvgDuration       float32        `json:"avg_duration_secs"`
	AvgLength         float32        `json:"avg_length_meters"`
}

type TrainingFrameMetadata struct {
	FrameID          int64
	SensorID         string
	TSUnixNanos      int64
	SequenceID       string
	TotalPoints      int
	ForegroundPoints int
	BackgroundPoints int
	AnnotationStatus string // "unlabeled", "in_progress", "labeled"
}

type WorldCluster struct {
	ClusterID         int64   // matches lidar_cluster_id INTEGER PRIMARY KEY
	SensorID          string  // matches sensor_id TEXT NOT NULL
	WorldFrame        FrameID // matches world_frame TEXT NOT NULL
	TSUnixNanos       int64   // matches ts_unix_nanos INTEGER NOT NULL
	CentroidX         float32 // matches centroid_x REAL
	CentroidY         float32 // matches centroid_y REAL
	CentroidZ         float32 // matches centroid_z REAL
	BoundingBoxLength float32 // matches bounding_box_length REAL
	BoundingBoxWidth  float32 // matches bounding_box_width REAL
	BoundingBoxHeight float32 // matches bounding_box_height REAL
	PointsCount       int     // matches points_count INTEGER
	HeightP95         float32 // matches height_p95 REAL
	IntensityMean     float32 // matches intensity_mean REAL

	// Debug hints matching schema optional fields
	SensorRingHint  *int     // matches sensor_ring_hint INTEGER
	SensorAzDegHint *float32 // matches sensor_azimuth_deg_hint REAL

	// Optional in-memory only fields (not persisted to schema)
	SamplePoints [][3]float32 // for debugging/thumbnails
}

type WorldPoint struct {
	X, Y, Z   float64   // World frame position (meters)
	Intensity uint8     // Laser return intensity
	Timestamp time.Time // Acquisition time
	SensorID  string    // Source sensor
}