l6objects

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 25, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package l6objects owns Layer 6 (Objects) of the LiDAR data model.

Responsibilities: track classification (vehicle, pedestrian, noise), quality assessment, and taxonomy management.

Dependency rule: L6 may depend on L1-L5. No SQL/database code is allowed in this package.

Type definitions: This package defines local copies of types from the parent lidar package to avoid import cycles. Some fields (e.g., speedHistory in TrackedObject) are intentionally unexported to maintain encapsulation while remaining accessible within the package for internal computations.

See docs/lidar/architecture/lidar-data-layer-model.md for the full layer model.

Index

Constants

View Source
const (
	// Height thresholds (metres)
	BirdHeightMax       = 0.5 // Birds are typically small
	PedestrianHeightMin = 1.0 // Pedestrians are at least 1 m tall
	PedestrianHeightMax = 2.2 // Pedestrians are typically under 2.2 m
	VehicleHeightMin    = 1.2 // Vehicles are at least 1.2 m
	VehicleLengthMin    = 3.0 // Vehicles are at least 3 m long
	VehicleWidthMin     = 1.5 // Vehicles are at least 1.5 m wide

	// Bus thresholds (very large vehicles)
	BusLengthMin = 7.0 // Buses/coaches are typically ≥ 7 m
	BusWidthMin  = 2.3 // Buses are typically ≥ 2.3 m wide

	// Truck thresholds (medium-large vehicles, smaller than buses)
	TruckLengthMin = 5.5 // Trucks are typically ≥ 5.5 m
	TruckWidthMin  = 2.0 // Trucks are typically ≥ 2.0 m wide
	TruckHeightMin = 2.0 // Trucks tend to be taller than cars

	// Cyclist thresholds
	CyclistHeightMin = 1.0  // Seated cyclist ≥ 1 m
	CyclistHeightMax = 2.0  // Cyclist ≤ 2 m
	CyclistSpeedMin  = 2.0  // Faster than walking (≥ 2 m/s ≈ 7.2 km/h)
	CyclistSpeedMax  = 10.0 // Slower than most motor vehicles (≤ 10 m/s ≈ 36 km/h)
	CyclistWidthMax  = 1.2  // Narrow profile
	CyclistLengthMax = 2.5  // Bike ≤ 2.5 m

	// Motorcyclist thresholds (similar to cyclist but faster)
	MotorcyclistSpeedMin  = 5.0  // Faster than cyclists (≥ 5 m/s ≈ 18 km/h)
	MotorcyclistSpeedMax  = 30.0 // Up to highway speed (≤ 30 m/s ≈ 108 km/h)
	MotorcyclistWidthMax  = 1.2  // Narrow profile
	MotorcyclistLengthMin = 1.5  // Motorcycle ≥ 1.5 m
	MotorcyclistLengthMax = 3.0  // Motorcycle ≤ 3.0 m

	// Speed thresholds (m/s)
	BirdSpeedMax       = 1.0 // Birds detected at low speeds
	PedestrianSpeedMax = 3.0 // Pedestrians walk up to ~3 m/s (10.8 km/h)
	VehicleSpeedMin    = 5.0 // Vehicles typically move faster than 5 m/s
	StationarySpeedMax = 0.5 // Stationary threshold

	// Confidence levels
	HighConfidence   = 0.85
	MediumConfidence = 0.70
	LowConfidence    = 0.50
)

Classification thresholds (configurable for tuning)

View Source
const (
	TrackTentative = l5tracks.TrackTentative
	TrackConfirmed = l5tracks.TrackConfirmed
	TrackDeleted   = l5tracks.TrackDeleted
)

Constants re-exported from l5tracks.

Variables

View Source
var ComputeRunStatistics = l8analytics.ComputeRunStatistics

ComputeRunStatistics delegates to the canonical implementation in l8analytics.

View Source
var ComputeTemporalIoU = l8analytics.ComputeTemporalIoU

ComputeTemporalIoU delegates to the canonical implementation in l8analytics.

View Source
var ParseRunStatistics = l8analytics.ParseRunStatistics

ParseRunStatistics delegates to the canonical implementation in l8analytics.

Functions

func ComputeSpeedPercentiles

func ComputeSpeedPercentiles(speedHistory []float32) (p50, p85, p95 float32)

ComputeSpeedPercentiles computes speed percentiles from a track's speed history. Uses floor-based indexing for percentiles. For small arrays (n<3), all percentiles may return similar values. For production use with precise percentile requirements, consider using linear interpolation between neighbouring values.

func SetLogWriters

func SetLogWriters(ops, diag, trace io.Writer)

SetLogWriters configures the three logging streams for the l6objects package. Pass nil for any writer to disable that stream.

func SortFeatureImportance

func SortFeatureImportance(vector []float32) []string

SortFeatureImportance returns feature names sorted by absolute contribution to classification. This is a placeholder for future ML model feature importance.

func SortedFeatureNames

func SortedFeatureNames() []string

SortedFeatureNames returns the canonical feature names in the order they should appear in an exported feature vector (for ML training).

Types

type ClassificationFeatures

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
	MaxSpeed float32 // Max speed
	P50Speed float32 // Median speed
	P85Speed float32 // 85th percentile speed
	P95Speed float32 // 95th percentile speed

	// Temporal features
	ObservationCount int
	DurationSecs     float32
}

ClassificationFeatures holds the features used for classification.

type ClassificationResult

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

ClassificationResult holds the result of track classification.

type ClusterFeatures

type ClusterFeatures struct {
	PointCount     int
	BBoxLength     float32
	BBoxWidth      float32
	BBoxHeight     float32
	HeightP95      float32
	IntensityMean  float32
	IntensityStd   float32
	Elongation     float32 // length / width (clamped to avoid Inf)
	Compactness    float32 // points / bbox_volume (clamped)
	VerticalSpread float32 // std-dev of Z
}

ClusterFeatures captures per-cluster spatial and intensity features. These are extracted from a single frame's cluster for use in classification and ML feature-vector export.

func ExtractClusterFeatures

func ExtractClusterFeatures(cluster WorldCluster, points []WorldPoint) ClusterFeatures

ExtractClusterFeatures computes features from a cluster and its constituent points.

type NoiseCoverageMetrics

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 == "dynamic"
	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, ...]
}

NoiseCoverageMetrics quantifies "unknown" classification coverage. Scaffolding for coverage analysis.

func ComputeNoiseCoverageMetrics

func ComputeNoiseCoverageMetrics(tracks []*TrackedObject) *NoiseCoverageMetrics

ComputeNoiseCoverageMetrics calculates coverage metrics for a set of tracks. Placeholder implementation.

type ObjectClass

type ObjectClass string

ObjectClass represents the classification of a tracked object.

const (
	// ClassCar indicates a car or small/medium vehicle
	ClassCar ObjectClass = "car"
	// ClassTruck indicates a truck or medium-large vehicle
	ClassTruck ObjectClass = "truck"
	// ClassBus indicates a bus or large vehicle (length > 7 m)
	ClassBus ObjectClass = "bus"
	// ClassPedestrian indicates a pedestrian or person
	ClassPedestrian ObjectClass = "pedestrian"
	// ClassCyclist indicates a cyclist
	ClassCyclist ObjectClass = "cyclist"
	// ClassMotorcyclist indicates a person on a motorcycle
	ClassMotorcyclist ObjectClass = "motorcyclist"
	// ClassBird indicates a bird or small flying object
	ClassBird ObjectClass = "bird"
	// ClassDynamic indicates an unclassified dynamic object
	ClassDynamic ObjectClass = "dynamic"

	// Aliases
	ClassPed = ClassPedestrian // Short-form alias
)

type OrientedBoundingBox

type OrientedBoundingBox = l4perception.OrientedBoundingBox

OrientedBoundingBox represents a 7-DOF (7 Degrees of Freedom) 3D bounding box.

type RunComparison

type RunComparison = l8analytics.RunComparison

RunComparison shows differences between two analysis runs.

type RunStatistics

type RunStatistics = l8analytics.RunStatistics

RunStatistics is now canonical in l8analytics; this alias preserves backward compatibility.

type TrackClassifier

type TrackClassifier struct {
	ModelVersion    string
	MinObservations int // Minimum observations before classification
}

TrackClassifier performs rule-based classification of tracked objects. This can be replaced with an ML model in future iterations.

func NewTrackClassifier

func NewTrackClassifier() *TrackClassifier

NewTrackClassifier creates a new track classifier.

func NewTrackClassifierWithMinObservations

func NewTrackClassifierWithMinObservations(minObservations int) *TrackClassifier

NewTrackClassifierWithMinObservations creates a new classifier with an explicit minimum-observation threshold.

func (*TrackClassifier) Classify

func (tc *TrackClassifier) Classify(track *TrackedObject) ClassificationResult

Classify determines the object class for a tracked object. Returns the classification result with class, confidence, and features used.

func (*TrackClassifier) ClassifyAndUpdate

func (tc *TrackClassifier) ClassifyAndUpdate(track *TrackedObject)

ClassifyAndUpdate classifies a track and updates its classification fields. This should be called periodically or when track state changes.

func (*TrackClassifier) ClassifyFeatures

func (tc *TrackClassifier) ClassifyFeatures(features ClassificationFeatures) ClassificationResult

ClassifyFeatures classifies an object from pre-built feature values. Use this when the full TrackedObject is unavailable — e.g. during VRLOG replay where only aggregate metrics (bbox, speed, observation count) are stored in the recorded FrameBundle tracks.

type TrackFeatures

type TrackFeatures struct {
	ClusterFeatures // latest observation features

	// Kinematic features
	AvgSpeedMps       float32
	MaxSpeedMps       float32
	SpeedVariance     float32
	TrackDurationSecs float32
	TrackLengthMeters float32
	HeadingVariance   float32
	OcclusionRatio    float32

	// Speed percentiles
	SpeedP50 float32
	SpeedP85 float32
	SpeedP95 float32
}

TrackFeatures aggregates cluster features across a track's lifetime and adds kinematic features. This struct is the primary input for ML-based classification training data export.

func ExtractTrackFeatures

func ExtractTrackFeatures(track *TrackedObject) TrackFeatures

ExtractTrackFeatures computes the full feature vector for a tracked object, combining the latest cluster-level features with kinematic history.

func (TrackFeatures) ToVector

func (f TrackFeatures) ToVector() []float32

ToVector converts TrackFeatures to a flat float32 slice in canonical order. The order matches SortedFeatureNames().

type TrackMatch

type TrackMatch = l8analytics.TrackMatch

TrackMatch represents a matched track between two runs.

type TrackMerge

type TrackMerge = l8analytics.TrackMerge

TrackMerge represents a suspected track merge between runs.

type TrackPoint

type TrackPoint = l5tracks.TrackPoint

TrackPoint represents a single point in a track's history.

type TrackQualityMetrics

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)
}

TrackQualityMetrics provides per-track quality assessment.

func ComputeTrackQualityMetrics

func ComputeTrackQualityMetrics(track *TrackedObject) *TrackQualityMetrics

ComputeTrackQualityMetrics extracts quality metrics from a TrackedObject.

type TrackSplit

type TrackSplit = l8analytics.TrackSplit

TrackSplit represents a suspected track split between runs.

type TrackState

type TrackState = l5tracks.TrackState

TrackState represents the lifecycle state of a track.

type TrackTrainingFilter

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)
}

TrackTrainingFilter defines criteria for selecting high-quality tracks for ML training.

func DefaultTrackTrainingFilter

func DefaultTrackTrainingFilter() *TrackTrainingFilter

DefaultTrackTrainingFilter returns sensible defaults for high-quality training tracks.

type TrackedObject

type TrackedObject = l5tracks.TrackedObject

TrackedObject is the canonical tracking object type from l5tracks.

func FilterTracksForTraining

func FilterTracksForTraining(tracks []*TrackedObject, filter *TrackTrainingFilter) []*TrackedObject

FilterTracksForTraining selects tracks that meet training data quality criteria.

type TrainingDatasetSummary

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"`
}

TrainingDatasetSummary provides statistics about a curated training dataset.

func SummarizeTrainingDataset

func SummarizeTrainingDataset(tracks []*TrackedObject) *TrainingDatasetSummary

SummarizeTrainingDataset generates statistics for a curated training dataset.

type WorldCluster

type WorldCluster = l4perception.WorldCluster

WorldCluster represents a cluster of world points.

type WorldPoint

type WorldPoint = l4perception.WorldPoint

WorldPoint represents a point in Cartesian world coordinates (site frame).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL