object_array.h File Reference

Zero-copy variable-length array of fixed-size 3-D detection / tracking records. More...

#include <cstdint>
#include <string_view>
#include "../base/bytes.h"
#include "./header.h"

Include dependency graph for object_array.h:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Detailed Description

Zero-copy variable-length array of fixed-size 3-D detection / tracking records.

ObjectArray is the canonical message produced by 3-D perception, sensor fusion, and multi-object tracking pipelines. It packs a homogeneous array of Object records, each capturing the pose, dimensions, kinematics, classification, identity, and covariance of one obstacle. A 40-byte Header prefix carries sequencing and dual-timestamp metadata.

Container vs. record layout

The container struct is 112 bytes; each Object record is 144 bytes. Both sizes are locked by static_assert. Object uses 4-byte alignment because its widest field is 4 bytes; with the wire envelope (magic 4 + version 4 + struct 112) the payload starts at offset 120, an 8-byte boundary, so the requirement is comfortably met and a typed objects() pointer stays safe on strict-alignment architectures (ARM, AArch64).

Object schema

Field	Type	Meaning
label	char[32]	Class name (e.g. "car", "pedestrian")
position[3]	float	Centre in metres (world frame)
yaw	float	Heading in radians (REP-103)
size[3]	float	Length, width, height in metres
yaw_rate	float	Angular velocity in rad/s
velocity[3]	float	Linear velocity in m/s
score	float	Detection confidence in [0, 1]
acceleration[3]	float	Linear acceleration in m/s^2
existence_probability	float	Existence probability in [0, 1]
position_covariance[6]	float	Upper triangle of 3x3 covariance
class_id	uint32_t	Numeric class identifier
track_id	uint32_t	Tracking id (0 = unassociated detection)
age	uint32_t	Tracking age in frames
num_observations	uint32_t	Cumulative observation count
motion_state	MotionState	Stationary / moving / stopped / parked
source_type	SourceType	LiDAR / camera / radar / fusion / ultrasonic
subtype_id	uint16_t	Fine-grained subtype
reserved_buf	uint32_t	Reserved (wire-locked)

Wire format

Both the container and the Object record are POD; memcpy is the canonical serialiser. The sizeof values are locked by static_assert and form a permanent contract: vlink::zerocopy::* containers offer NO forward and NO backward binary compatibility, and every field including reserved bytes is part of the wire contract.

static_assert(sizeof(ObjectArray) == 112, "Sizeof must be 112 bytes.");
static_assert(sizeof(ObjectArray::Object) == 144, "Sizeof must be 144 bytes.");

Memory layout

Offset  Size  Field
------  ----  --------------------------
     0    40  Header   header
    40     8  uint8_t* data_
    48     8  size_t   capacity_
    56     8  uint64_t update_time_ns_
    64    16  char     source_id_[16]
    80     4  uint32_t channel_
    84     4  uint32_t freq_
    88     4  uint32_t count_
    92     4  uint32_t pack_size_
    96     1  bool     is_owner_
    97     1  uint8_t  reserved_buf_
    98     2  uint16_t reserved_buf2_
   100     4  uint32_t reserved_buf3_
   104     4  uint32_t reserved_buf4_
   108     4  uint32_t reserved_buf5_
------  ----  --------------------------
 Total   112  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | ObjectArray (112) | Object[0..count) (count*144) | magic_end (4) ]

Reserved bytes

reserved_buf_, reserved_buf2_, reserved_buf3_, reserved_buf4_, reserved_buf5_ are exposed through get_reserved* helpers and survive clear() and the copy / move helpers so producers can stamp minor flags. None of these slots may be repurposed by application code: future library revisions may bind them to real fields, silently breaking peers that abused the slot.

Example

vlink::zerocopy::ObjectArray arr;
arr.create(256);
arr.set_source_id("fusion_v2");
 
vlink::zerocopy::ObjectArray::Object obj;
std::strncpy(obj.label, "car", sizeof(obj.label) - 1);
obj.position[0] = 12.0F;
obj.size[0]     = 4.5F;
obj.velocity[0] = 8.5F;
obj.class_id    = 1;
obj.track_id    = 42;
arr.push_value(obj);
 
vlink::Bytes wire;
arr >> wire;