l2frames

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

	// FrameChCapacity sets the buffered channel capacity for the frame
	// callback worker. Default 8 is adequate for live sensor input;
	// PCAP replay benefits from a larger buffer (e.g. 32) to absorb
	// short processing stalls without dropping frames.
	FrameChCapacity int
}

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
	PolarPoints    []PointPolar // sensor-polar view: all points in polar coordinates
	Points         []Point      // sensor-Cartesian view: all points in Cartesian coordinates
	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 Point struct {
	// 3D Cartesian coordinates (computed from spherical measurements)
	X float64 // X coordinate in meters (forward direction from sensor)
	Y float64 // Y coordinate in meters (right direction from sensor)
	Z float64 // Z coordinate in meters (upward direction from sensor)

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

	// Packet tracking for completeness validation
	UDPSequence     uint32 // UDP sequence number for gap detection
	RawBlockAzimuth uint16 // 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)
}