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
- Variables
- func ComputeSpeedPercentiles(speedHistory []float32) (p50, p85, p95 float32)
- func SetLogWriters(ops, diag, trace io.Writer)
- func SortFeatureImportance(vector []float32) []string
- func SortedFeatureNames() []string
- type ClassificationFeatures
- type ClassificationResult
- type ClusterFeatures
- type NoiseCoverageMetrics
- type ObjectClass
- type OrientedBoundingBox
- type RunComparison
- type RunStatistics
- type TrackClassifier
- type TrackFeatures
- type TrackMatch
- type TrackMerge
- type TrackPoint
- type TrackQualityMetrics
- type TrackSplit
- type TrackState
- type TrackTrainingFilter
- type TrackedObject
- type TrainingDatasetSummary
- type WorldCluster
- type WorldPoint
Constants ¶
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)
const ( TrackTentative = l5tracks.TrackTentative TrackConfirmed = l5tracks.TrackConfirmed TrackDeleted = l5tracks.TrackDeleted )
Constants re-exported from l5tracks.
Variables ¶
var ComputeRunStatistics = l8analytics.ComputeRunStatistics
ComputeRunStatistics delegates to the canonical implementation in l8analytics.
var ComputeTemporalIoU = l8analytics.ComputeTemporalIoU
ComputeTemporalIoU delegates to the canonical implementation in l8analytics.
var ParseRunStatistics = l8analytics.ParseRunStatistics
ParseRunStatistics delegates to the canonical implementation in l8analytics.
Functions ¶
func ComputeSpeedPercentiles ¶
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 ¶
SetLogWriters configures the three logging streams for the l6objects package. Pass nil for any writer to disable that stream.
func SortFeatureImportance ¶
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).