occupancy_grid.h File Reference

Zero-copy 2-D occupancy / cost-map grid container with typed cell storage. More...

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

Include dependency graph for occupancy_grid.h:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Functions
struct	vlink::zerocopy::VLINK_EXPORT_AND_ALIGNED (8) AudioFrame final

Detailed Description

Zero-copy 2-D occupancy / cost-map grid container with typed cell storage.

OccupancyGrid is the canonical 2-D map message for VLink autonomous-driving stacks: local costmaps, global occupancy, lane-level reachability, signed distance fields, log-odds buffers, etc. Each grid carries the cell buffer, the world-to-grid transform, value range, default value, occupied / free thresholds, a 40-byte Header for sequencing, and a map identifier so that multiple map types can share one topic.

Cell-value semantics

CellType	C++ type	Bytes	Free	Occupied	Unknown
kCellInt8	int8_t	1	0	100	-1 (ROS nav_msgs convention)
kCellUint8	uint8_t	1	0	254	255
kCellUint16	uint16_t	2	0	65534	65535
kCellFloat32	float	4	<= ft	>= ot	NaN (ft / ot = thresholds)

Coordinate system

+y
 ^
 |   (origin_x, origin_y) lies at the bottom-left
 |   corner of the cell at column 0 / row 0.  The
 |   grid is rotated by origin_yaw radians (REP-103)
 |   around that origin.
 |
 +---->-->-->-->-->  +x
 origin_x,origin_y   each cell spans resolution metres
 
world(x, y) = origin + R(origin_yaw) * (column, row) * resolution

Wire format

OccupancyGrid is POD; memcpy is the canonical serialiser. The sizeof value is locked by static_assert and forms a permanent contract: vlink::zerocopy::* containers offer NO forward and NO backward binary compatibility – every field, including reserved bytes, is wire-locked.

static_assert(sizeof(OccupancyGrid) == 152, "Sizeof must be 152 bytes.");

Memory layout

Offset  Size  Field
------  ----  --------------------------------
     0    40  Header   header
    40     8  uint8_t* data_
    48     8  size_t   size_
    56     8  uint64_t update_time_ns_
    64    16  char     map_id_[16]
    80     4  uint32_t channel_
    84     4  uint32_t freq_
    88     4  uint32_t width_
    92     4  uint32_t height_
    96     4  uint32_t valid_cell_count_
   100     4  float    resolution_
   104     4  float    origin_x_
   108     4  float    origin_y_
   112     4  float    origin_z_
   116     4  float    origin_yaw_
   120     4  float    value_min_
   124     4  float    value_max_
   128     4  int32_t  default_value_
   132     4  float    occupied_threshold_
   136     4  float    free_threshold_
   140     1  CellType cell_type_
   141     1  bool     is_owner_
   142     2  uint16_t reserved_buf_
   144     4  uint32_t reserved_buf2_
   148     4  uint32_t reserved_buf3_
------  ----  --------------------------------
 Total   152  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | OccupancyGrid (152) | cell bytes (width*height*cell_size) | magic_end (4) ]

Reserved bytes

reserved_buf_, reserved_buf2_, reserved_buf3_ are exposed through get_reserved* helpers and survive clear() and the copy / move helpers. These slots MUST NOT be repurposed by application code: future library revisions may bind them to real fields, silently breaking peers that abused the slot.

Example

vlink::zerocopy::OccupancyGrid og;
og.set_width(400);
og.set_height(400);
og.set_resolution(0.05F);
og.set_origin_x(-10.0F);
og.set_origin_y(-10.0F);
og.set_cell_type(vlink::zerocopy::OccupancyGrid::kCellInt8);
og.set_default_value(-1);
og.set_occupied_threshold(0.65F);
og.set_free_threshold(0.20F);
og.create(400 * 400);
 
vlink::Bytes wire;
og >> wire;