A point-cloud frame: points plus the sensor/host state snapshots and frame metadata recorded with them. More...

#include <voyant_frame.hpp>

Classes
struct	SyntheticFrameDesc
	Identity and timeline of a synthetic() frame; zeros are valid. More...
struct	StatelessFrameDesc

Public Member Functions
	VoyantFrame ()=default
	An empty frame that carries no state; see the class docs.
const std::vector< PointData > &	points () const
std::vector< PointData > &	points ()
size_t	nPoints () const
size_t	nValidPoints () const
	Count of valid returns (see isValidPoint()); computed per call.
bool	carriesState () const
std::optional< SensorState >	sensorState () const
std::optional< HostState >	hostState () const
uint32_t	frameIndex () const
	Device frame counter.
int64_t	timestampSeconds () const
	Whole seconds of the frame-start time since the Unix epoch.
int32_t	timestampNanoseconds () const
	Sub-second remainder of the frame-start time, in nanoseconds (0..=999999999).
double	timestamp () const
std::string	deviceId () const
VoyantFrame	withPoints (std::vector< PointData > points) const
std::optional< VoyantFrame >	withSdl (const SdlCommandParams &params) const
	A new frame whose SDL state reads as if the sensor had applied params (status Applied); everything else carries over, like withPoints().
std::vector< VoyantVec3 >	xyz () const
std::string	describe () const
	A one-screen summary of the frame and its state snapshots.

Static Public Member Functions
static std::optional< VoyantFrame >	synthetic (std::vector< PointData > points, const SyntheticFrameDesc &desc)
	Build a frame of generated data — a simulated scene, a scripted test cloud — that records and replays like a real log.
static std::optional< VoyantFrame >	synthetic (std::vector< PointData > points)
	synthetic() with an all-default identity: Unknown source, zeroed timeline.
static std::optional< VoyantFrame >	stateless (std::vector< PointData > points, const StatelessFrameDesc &desc)
	Build a frame from points that arrived without the sensor's heartbeat — a bag, a CSV — so it declares no state.
static std::optional< VoyantFrame >	stateless (std::vector< PointData > points)
	stateless() with an all-default identity: Unknown source, zeroed timeline.

Private Member Functions
VoyantFrameMeta	toMeta () const
	This frame's transfer fields with n_points refreshed from the vector.

Private Attributes
VoyantFrameMeta	meta_ {}
std::vector< PointData >	points_

Friends
class	CarbonClient
class	VoyantPlayback
class	VoyantRecorder

Detailed Description

A point-cloud frame: points plus the sensor/host state snapshots and frame metadata recorded with them.

Produced by CarbonClient (live) and VoyantPlayback (recordings); consumed by VoyantRecorder. Points are freely editable — filter or modify points() (or derive a copy with withPoints()) and record the result; the state snapshots, timestamps and frame identity always carry over from the source frame, so edited points can never be paired with mismatched state.

A default-constructed frame carries no state, records as an honest stateless entry, and reports sensorState()/hostState() as nullopt; stateless() is the same but keeps the timeline and device identity, for points ingested from outside the API. synthetic() builds a state-carrying frame, and that one may name only a software source — user code can never claim a real sensor's measurements.

Constructor & Destructor Documentation

◆ VoyantFrame()

VoyantFrame::VoyantFrame ( )

default

An empty frame that carries no state; see the class docs.

Member Function Documentation

◆ carriesState()

bool VoyantFrame::carriesState ( ) const

inline

Whether this frame carries real sensor and host state. False for a recording converted from the pre-v1.0.0 format, which stored none, and for stateless() frames; sensorState()/hostState() then return nullopt rather than zeros that look like readings. Points, identity and timestamps stay real — except on a default-constructed frame, which leaves them unset.

◆ describe()

std::string VoyantFrame::describe ( ) const

inline

A one-screen summary of the frame and its state snapshots.

◆ deviceId()

std::string VoyantFrame::deviceId ( ) const

inline

Formatted device ID, e.g. "CAR-30-005". Recorded frames carry a real one whether or not carriesState(); a frame built from scratch reports an unset device.

◆ frameIndex()

uint32_t VoyantFrame::frameIndex ( ) const

inline

Device frame counter.

◆ hostState()

std::optional< HostState > VoyantFrame::hostState ( ) const

inline

Host-side context stamped when this frame was published (snapshot age, ramp drops, time sync), or nullopt when the frame carries none.

◆ nPoints()

size_t VoyantFrame::nPoints ( ) const

inline

◆ nValidPoints()

size_t VoyantFrame::nValidPoints ( ) const

inline

Count of valid returns (see isValidPoint()); computed per call.

◆ points() [1/2]

std::vector< PointData > & VoyantFrame::points ( )

inline

◆ points() [2/2]

const std::vector< PointData > & VoyantFrame::points ( ) const

inline

◆ sensorState()

std::optional< SensorState > VoyantFrame::sensorState ( ) const

inline

Sensor state snapshotted at this frame's heartbeat, in physical units, or nullopt when the frame carries none. Converted on each call — hoist out of loops.

◆ stateless() [1/2]

std::optional< VoyantFrame > VoyantFrame::stateless ( std::vector< PointData > points )

inlinestatic

stateless() with an all-default identity: Unknown source, zeroed timeline.

◆ stateless() [2/2]

std::optional< VoyantFrame > VoyantFrame::stateless	(	std::vector< PointData >	points,
		const StatelessFrameDesc &	desc )

inlinestatic

Build a frame from points that arrived without the sensor's heartbeat — a bag, a CSV — so it declares no state.

synthetic() but for carriesState() false: timeline and identity record and replay the same way. desc may name a real sensor, which synthetic()'s must not — the frame claims no measurements, so naming the sensor the points came from is provenance, not a claim about state. Returns nullopt on an unrecognized desc.source; an out-of-epoch timestamp clamps rather than failing.

◆ synthetic() [1/2]

std::optional< VoyantFrame > VoyantFrame::synthetic ( std::vector< PointData > points )

inlinestatic

synthetic() with an all-default identity: Unknown source, zeroed timeline.

◆ synthetic() [2/2]

std::optional< VoyantFrame > VoyantFrame::synthetic	(	std::vector< PointData >	points,
		const SyntheticFrameDesc &	desc )

inlinestatic

Build a frame of generated data — a simulated scene, a scripted test cloud — that records and replays like a real log.

desc.source becomes deviceId(), the marker for synthetic data. The frame is state-carrying, so give each frame of a sequence its own timeline; unauthored state fields hold defaults, not measurements (a zeroed FPGA temperature reads -273.15 °C). Returns nullopt on a real sensor id, an unrecognized one, or a timestamp outside the epoch (seconds >= 0, nanoseconds 0..=999999999).

◆ timestamp()

double VoyantFrame::timestamp ( ) const

inline

Frame-start time as fractional seconds since the Unix epoch. Convenient, but a double quantizes a present-day epoch to a few hundred nanoseconds — use timestampSeconds()/timestampNanoseconds() for the exact recorded value.

◆ timestampNanoseconds()

int32_t VoyantFrame::timestampNanoseconds ( ) const

inline

Sub-second remainder of the frame-start time, in nanoseconds (0..=999999999).

◆ timestampSeconds()

int64_t VoyantFrame::timestampSeconds ( ) const

inline

Whole seconds of the frame-start time since the Unix epoch.

◆ toMeta()

VoyantFrameMeta VoyantFrame::toMeta ( ) const

inlineprivate

This frame's transfer fields with n_points refreshed from the vector.

◆ withPoints()

VoyantFrame VoyantFrame::withPoints ( std::vector< PointData > points ) const

inline

A new frame holding points; state, timestamps, frame index and identity carry over unchanged, so it records exactly like this one. This frame is not modified.

◆ withSdl()

std::optional< VoyantFrame > VoyantFrame::withSdl ( const SdlCommandParams & params ) const

inline

A new frame whose SDL state reads as if the sensor had applied params (status Applied); everything else carries over, like withPoints().

params is the struct CarbonClient::sendSdl() takes (hfov_deg == 0 builds a static line; ramp_length is firmware-fixed and ignored), field-range checked but not put through sendSdl()'s send-time checks, so a scene may declare a configuration a real sensor would refuse. Returns nullopt on a rejected value or a frame that carries no state. This frame is not modified.

On a simulator identity the measured chirp bandwidth is also set to what params commands — it otherwise stays at its power-up 0, which the DSP reads as an invalid bandwidth and drops every point on. A real sensor's is left alone.

◆ xyz()

std::vector< VoyantVec3 > VoyantFrame::xyz ( ) const

inline

Cartesian positions in meters, index-aligned with points() — hoist the result rather than calling this per point. Sensor frame: +x forward, +y left, +z up, derived from the stored spherical coordinates. Every point is projected, but only a valid return's result is a position: a dropped point may carry any range, including a placeholder the datum offset leaves negative, so check isValidPoint() before using one — the sign alone says nothing about whether a measurement happened.

◆ CarbonClient

friend class CarbonClient

friend

◆ VoyantPlayback

friend class VoyantPlayback

friend

◆ VoyantRecorder

friend class VoyantRecorder

friend

Member Data Documentation

◆ meta_

VoyantFrameMeta VoyantFrame::meta_ {}

private

◆ points_

std::vector<PointData> VoyantFrame::points_

private

The documentation for this class was generated from the following file:

/usr/include/voyant_api/voyant_frame.hpp

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ VoyantFrame()

Member Function Documentation

◆ carriesState()

◆ describe()

◆ deviceId()

◆ frameIndex()

◆ hostState()

◆ nPoints()

◆ nValidPoints()

◆ points() [1/2]

◆ points() [2/2]

◆ sensorState()

◆ stateless() [1/2]

◆ stateless() [2/2]

◆ synthetic() [1/2]

◆ synthetic() [2/2]

◆ timestamp()

◆ timestampNanoseconds()

◆ timestampSeconds()

◆ toMeta()

◆ withPoints()

◆ withSdl()

◆ xyz()

Friends And Related Symbol Documentation

◆ CarbonClient

◆ VoyantPlayback

◆ VoyantRecorder

Member Data Documentation

◆ meta_

◆ points_