analysis

type AlignmentSummary struct {
	AlignmentMeanDeg  *DistStats `json:"alignment_mean_deg,omitempty"`
	MisalignmentRatio *DistStats `json:"misalignment_ratio,omitempty"`
}

type AnalysisReport struct {
	Version     string `json:"version"`
	GeneratedAt string `json:"generated_at"`
	Source      string `json:"source"`

	Recording                  RecordingMeta         `json:"recording"`
	FrameSummary               FrameSummary          `json:"frame_summary"`
	TrackSummary               TrackSummary          `json:"track_summary"`
	Tracks                     []TrackDetail         `json:"tracks"`
	SpeedHistogram             SpeedHistogram        `json:"speed_histogram"`
	ClassificationDistribution map[string]ClassStats `json:"classification_distribution"`
}

type BBoxDims struct {
	Length float32 `json:"length"`
	Width  float32 `json:"width"`
	Height float32 `json:"height"`
}

type ClassStats struct {
	Count           int     `json:"count"`
	AvgSpeedMps     float64 `json:"avg_speed_mps"`
	AvgDurationSecs float64 `json:"avg_duration_secs"`
	AvgObservations float64 `json:"avg_observations"`
}

type ComparisonReport struct {
	Version     string `json:"version"`
	GeneratedAt string `json:"generated_at"`
	RunA        string `json:"run_a"`
	RunB        string `json:"run_b"`

	FrameOverlap  FrameOverlap  `json:"frame_overlap"`
	TrackMatching TrackMatching `json:"track_matching"`
	SpeedDelta    SpeedDelta    `json:"speed_delta"`
	QualityDelta  QualityDelta  `json:"quality_delta"`
}

type DeltaPair struct {
	A     float64 `json:"a"`
	B     float64 `json:"b"`
	Delta float64 `json:"delta"`
}

type DistStats struct {
	Samples int      `json:"samples"`
	Min     float64  `json:"min"`
	Avg     float64  `json:"avg"`
	P50     *float64 `json:"p50,omitempty"`
	P85     *float64 `json:"p85,omitempty"`
	P98     *float64 `json:"p98,omitempty"`
	Max     float64  `json:"max"`
}

type FrameOverlap struct {
	AFrames          int     `json:"a_frames"`
	BFrames          int     `json:"b_frames"`
	TemporalOverlapS float64 `json:"temporal_overlap_secs"`
	TemporalUnionS   float64 `json:"temporal_union_secs"`
	TemporalIoU      float64 `json:"temporal_iou"`
}

type FrameSummary struct {
	TotalFrames                 int        `json:"total_frames"`
	FramesWithTracks            int        `json:"frames_with_tracks"`
	FramesWithClusters          int        `json:"frames_with_clusters"`
	AvgPointsPerFrame           float64    `json:"avg_points_per_frame"`
	AvgForegroundPointsPerFrame float64    `json:"avg_foreground_points_per_frame"`
	ForegroundPct               float64    `json:"foreground_pct"`
	AvgClustersPerFrame         float64    `json:"avg_clusters_per_frame"`
	AvgTracksPerFrame           float64    `json:"avg_tracks_per_frame"`
	FrameIntervalMs             *DistStats `json:"frame_interval_ms,omitempty"`
}

type HistogramBin struct {
	Lower float64 `json:"lower"`
	Upper float64 `json:"upper"`
	Count int     `json:"count"`
}

type JitterSummary struct {
	HeadingJitterDeg *DistStats `json:"heading_jitter_deg,omitempty"`
	SpeedJitterMps   *DistStats `json:"speed_jitter_mps,omitempty"`
}

type MatchPair struct {
	ATrackID         string  `json:"a_track_id"`
	BTrackID         string  `json:"b_track_id"`
	TemporalIoU      float64 `json:"temporal_iou"`
	SpeedDeltaMps    float64 `json:"speed_delta_mps"`
	ObservationRatio float64 `json:"observation_ratio"`
	ClassMatch       bool    `json:"class_match"`
}

type MatchedPairSpeed struct {
	ATrackID      string  `json:"a_track_id"`
	BTrackID      string  `json:"b_track_id"`
	AAvgSpeedMps  float64 `json:"a_avg_speed_mps"`
	BAvgSpeedMps  float64 `json:"b_avg_speed_mps"`
	SpeedDeltaMps float64 `json:"speed_delta_mps"`
}

type OcclusionSummary struct {
	MeanOcclusionCount float64 `json:"mean_occlusion_count"`
	MaxOcclusionCount  int     `json:"max_occlusion_count"`
	TotalOcclusions    int     `json:"total_occlusions"`
}

type QualityDelta struct {
	FragmentationRatio DeltaPair `json:"fragmentation_ratio"`
	MeanObservations   DeltaPair `json:"mean_observations"`
	MeanOcclusionCount DeltaPair `json:"mean_occlusion_count"`
}

type RecordingMeta struct {
	FormatVersion       string  `json:"format_version"`
	SensorID            string  `json:"sensor_id"`
	TotalFrames         uint64  `json:"total_frames"`
	CreatedNs           int64   `json:"created_ns"`
	StartNs             int64   `json:"start_ns"`
	EndNs               int64   `json:"end_ns"`
	DurationSecs        float64 `json:"duration_secs"`
	FrameRateHz         float64 `json:"frame_rate_hz"`
	InferredReplaySpeed float64 `json:"inferred_replay_speed,omitempty"`
	CoordinateFrame     string  `json:"coordinate_frame"`

	// Provenance (§12.2)
	SourceType    string  `json:"source_type,omitempty"`
	PCAPPath      string  `json:"pcap_path,omitempty"`
	PlaybackRate  float64 `json:"playback_rate,omitempty"`
	TuningHash    string  `json:"tuning_hash,omitempty"`
	RunConfigID   string  `json:"run_config_id,omitempty"`
	ParamSetID    string  `json:"param_set_id,omitempty"`
	ConfigHash    string  `json:"config_hash,omitempty"`
	ParamsHash    string  `json:"params_hash,omitempty"`
	SchemaVersion string  `json:"schema_version,omitempty"`
	ParamSetType  string  `json:"param_set_type,omitempty"`
	BuildVersion  string  `json:"build_version,omitempty"`
	BuildGitSHA   string  `json:"build_git_sha,omitempty"`
}

type SpeedDelta struct {
	MeanAbsSpeedDeltaMps    float64            `json:"mean_abs_speed_delta_mps"`
	MaxAbsSpeedDeltaMps     float64            `json:"max_abs_speed_delta_mps"`
	SpeedCorrelation        float64            `json:"speed_correlation"`
	HistogramEarthMoverDist float64            `json:"histogram_earth_mover_distance"`
	PerPair                 []MatchedPairSpeed `json:"per_pair,omitempty"`
}

type SpeedHistogram struct {
	BinWidthMps float64        `json:"bin_width_mps"`
	Bins        []HistogramBin `json:"bins"`
	Percentiles *DistStats     `json:"percentiles"`
	TotalTracks int            `json:"total_tracks"`
}

type TrackDetail struct {
	TrackID         string  `json:"track_id"`
	State           string  `json:"state"`
	ObjectClass     string  `json:"object_class"`
	ClassConfidence float32 `json:"class_confidence"`

	ObservationCount int     `json:"observation_count"`
	Hits             int     `json:"hits"`
	Misses           int     `json:"misses"`
	FirstSeenNs      int64   `json:"first_seen_ns"`
	LastSeenNs       int64   `json:"last_seen_ns"`
	DurationSecs     float64 `json:"duration_secs"`

	AvgSpeedMps  float32   `json:"avg_speed_mps"`
	MaxSpeedMps  float32   `json:"max_speed_mps"`
	SpeedSamples []float32 `json:"speed_samples,omitempty"`

	// Implementable-now jitter/alignment metrics (§12.1)
	SpeedVariance     float32 `json:"speed_variance"`
	HeadingJitterDeg  float32 `json:"heading_jitter_deg"`
	SpeedJitterMps    float32 `json:"speed_jitter_mps"`
	AlignmentMeanDeg  float32 `json:"alignment_mean_deg"`
	MisalignmentRatio float32 `json:"misalignment_ratio"`

	StartX            float32 `json:"start_x"`
	StartY            float32 `json:"start_y"`
	EndX              float32 `json:"end_x"`
	EndY              float32 `json:"end_y"`
	TrackLengthMetres float32 `json:"track_length_metres"`

	AvgBBox      BBoxDims `json:"avg_bbox"`
	HeightP95Max float32  `json:"height_p95_max"`

	OcclusionCount int     `json:"occlusion_count"`
	MotionModel    string  `json:"motion_model"`
	Confidence     float32 `json:"confidence"`
}

type TrackMatching struct {
	ATotalTracks int         `json:"a_total_tracks"`
	BTotalTracks int         `json:"b_total_tracks"`
	MatchedPairs int         `json:"matched_pairs"`
	AOnlyTracks  int         `json:"a_only_tracks"`
	BOnlyTracks  int         `json:"b_only_tracks"`
	Matches      []MatchPair `json:"matches"`
}

type TrackSummary struct {
	TotalTracks        int               `json:"total_tracks"`
	ConfirmedTracks    int               `json:"confirmed_tracks"`
	TentativeTracks    int               `json:"tentative_tracks"`
	DeletedTracks      int               `json:"deleted_tracks"`
	FragmentationRatio float64           `json:"fragmentation_ratio"`
	ObservationCount   *DistStats        `json:"observation_count,omitempty"`
	TrackDurationSecs  *DistStats        `json:"track_duration_secs,omitempty"`
	TrackLengthMetres  *DistStats        `json:"track_length_metres,omitempty"`
	Occlusion          *OcclusionSummary `json:"occlusion"`

	// Implementable-now aggregate blocks (§12.1)
	Jitter    *JitterSummary    `json:"jitter,omitempty"`
	Alignment *AlignmentSummary `json:"alignment,omitempty"`
}