navmap_ros Namespace Reference

Conversions between core NavMap and ROS-level structures. More...

Namespaces
namespace	io
	IO helpers to persist NavMap objects to/from disk.

Classes
struct	BuildParams
	Parameters controlling NavMap construction from point clouds. More...
struct	ViewpointFilterStats
	Points removed by filter_with_viewpoints(). More...

Typedefs
using	Triangle = Eigen::Vector3i

Functions
bool	build_navmap_from_mesh (const pcl::PointCloud< pcl::PointXYZ > &cloud, const std::vector< Eigen::Vector3i > &triangles, const std::string &frame_id, navmap_ros_interfaces::msg::NavMap &out_msg, navmap::NavMap *out_core_opt)
pcl::PointCloud< pcl::PointXYZ >	filter_with_viewpoints (const pcl::PointCloud< pcl::PointWithViewpoint > &input_points, const BuildParams &params, ViewpointFilterStats *stats=nullptr)
	Clean a cloud with the sensor position of each point (vp_x, vp_y, vp_z).
navmap::NavMap	from_msg (const NavMap &msg)
navmap::NavMap	from_msg (const NavMap &msg, std_msgs::msg::Header &header)
navmap::NavMap	from_msg (const navmap_ros_interfaces::msg::NavMap &msg)
	Backward-compatible overload (ignores message header).
navmap::NavMap	from_msg (const navmap_ros_interfaces::msg::NavMap &msg, std_msgs::msg::Header &header)
	Reconstruct a core navmap::NavMap from the ROS transport message.
void	from_msg (const navmap_ros_interfaces::msg::NavMapLayer &msg, navmap::NavMap &nm)
	Backward-compatible overload (ignores message header).
void	from_msg (const navmap_ros_interfaces::msg::NavMapLayer &msg, navmap::NavMap &nm, std_msgs::msg::Header &header)
	Import a single NavMapLayer message into a NavMap.
navmap::NavMap	from_occupancy_grid (const nav_msgs::msg::OccupancyGrid &grid)
	Backward-compatible overload (ignores grid header).
navmap::NavMap	from_occupancy_grid (const nav_msgs::msg::OccupancyGrid &grid, std_msgs::msg::Header &header)
	Build a navmap::NavMap from a nav_msgs::msg::OccupancyGrid using a regular triangular surface with shared vertices.
navmap::NavMap	from_pointcloud2 (const sensor_msgs::msg::PointCloud2 &pc2, navmap_ros_interfaces::msg::NavMap &out_msg, BuildParams params)
	Build a NavMap surface from a ROS sensor_msgs::msg::PointCloud2.
navmap::NavMap	from_points (const pcl::PointCloud< pcl::PointWithViewpoint > &input_points, navmap_ros_interfaces::msg::NavMap &out_msg, BuildParams params)
	Build a NavMap from a cloud with the sensor position of each point.
navmap::NavMap	from_points (const pcl::PointCloud< pcl::PointXYZ > &input_points, navmap_ros_interfaces::msg::NavMap &out_msg, BuildParams params)
	Build a NavMap from an unorganized point cloud (multi-level grid triangulation).
navmap::NavMap	from_regular_grid (const pcl::PointCloud< pcl::PointXYZ > &grid_points, navmap_ros_interfaces::msg::NavMap &out_msg, BuildParams params)
	Build a NavMap surface from an organized (grid-shaped) PCL point cloud.
navmap_ros_interfaces::msg::NavMapLayer	to_layer_update_msg (const navmap::NavMap &nm, const std::string &layer, const std_msgs::msg::Header &header=std_msgs::msg::Header(), float max_sparse_fraction=0.25f)
	Layer update with only what changed since the layer's last clear_changes().
navmap_ros_interfaces::msg::NavMap	to_msg (const navmap::NavMap &nm)
	Backward-compatible overload (no header provided).
navmap_ros_interfaces::msg::NavMapLayer	to_msg (const navmap::NavMap &nm, const std::string &layer)
	Backward-compatible overload (no header provided).
navmap_ros_interfaces::msg::NavMapLayer	to_msg (const navmap::NavMap &nm, const std::string &layer, const std_msgs::msg::Header &header)
	Convert a single layer from a NavMap into a ROS message.
navmap_ros_interfaces::msg::NavMap	to_msg (const navmap::NavMap &nm, const std_msgs::msg::Header &header)
	Convert a core navmap::NavMap into its compact ROS transport message.
nav_msgs::msg::OccupancyGrid	to_occupancy_grid (const navmap::NavMap &nm)
	Backward-compatible overload.
nav_msgs::msg::OccupancyGrid	to_occupancy_grid (const navmap::NavMap &nm, const std_msgs::msg::Header &header)
	Convert a navmap::NavMap back to nav_msgs::msg::OccupancyGrid.

Variables
constexpr std::uint8_t	FREE_SPACE
	Known free.
constexpr std::uint8_t	INSCRIBED_INFLATED_OBSTACLE
	The robot would touch an obstacle.
constexpr std::uint8_t	LETHAL_OBSTACLE
	Obstacle.
constexpr std::uint8_t	MAX_NON_OBSTACLE
	Highest traversable cost.
constexpr std::uint8_t	NO_INFORMATION
	Unknown, not observed.

Detailed Description

Conversions between core NavMap and ROS-level structures.

Typedef Documentation

Triangle

using Triangle = Eigen::Vector3i

Function Documentation

build_navmap_from_mesh()

bool build_navmap_from_mesh	(	const pcl::PointCloud< pcl::PointXYZ > &	cloud,
		const std::vector< Eigen::Vector3i > &	triangles,
		const std::string &	frame_id,
		navmap_ros_interfaces::msg::NavMap &	out_msg,
		navmap::NavMap *	out_core_opt )

filter_with_viewpoints()

pcl::PointCloud< pcl::PointXYZ > filter_with_viewpoints	(	const pcl::PointCloud< pcl::PointWithViewpoint > &	input_points,
		const BuildParams &	params,
		ViewpointFilterStats *	stats = nullptr )

Clean a cloud with the sensor position of each point (vp_x, vp_y, vp_z).

• Free-space carving (carve_free_space): each ray counts a pass in the occupied voxels it crosses under their highest point, from its viewpoint up to a margin before its point that grows as the ray grazes (v / sin(elevation), at most for 15 degrees). Passes along a planar voxel (under 15 degrees, a wall) do not count. Voxels with at least two passes and more than carve_ratio passes per hit are dropped.
• Seen from below (drop_seen_from_below): in each XY cell and thin level (as in from_points; up to two steps tall: a ceiling, a slab), a point whose ray climbs both the level's plane and the horizontal by more than 1 degree is seen from below. Walls, faces steeper than max_slope_deg and tall levels (a slope's face, a table over a floor) are left out. It is dropped unless the level has something not seen from below under it, as it still takes free height. A level seen only from below is dropped when most of it lies over a lower level of its cell (a ceiling over the floor it was seen from); otherwise it stays (the crest of a slope seen from its foot).

from_msg() [1/6]

navmap::NavMap from_msg

(

const NavMap &

msg

)

from_msg() [2/6]

navmap::NavMap from_msg	(	const NavMap &	msg,
		std_msgs::msg::Header &	header )

from_msg() [3/6]

navmap::NavMap from_msg

(

const navmap_ros_interfaces::msg::NavMap &

msg

)

Backward-compatible overload (ignores message header).

from_msg() [4/6]

navmap::NavMap from_msg	(	const navmap_ros_interfaces::msg::NavMap &	msg,
		std_msgs::msg::Header &	header )

Reconstruct a core navmap::NavMap from the ROS transport message.

Parameters

[in]	msg	Input navmap_ros_interfaces::msg::NavMap message.
[out]	header	Header extracted from the message.

Returns

A core navmap::NavMap equivalent to the content of msg.

• Intended to be the inverse of navmap_ros::to_msg for a round-trip without loss.
• Assumes that the message is internally consistent (sizes and indices match).

Exceptions

std::runtime_error

If the message describes inconsistent geometry or layer sizes.

from_msg() [5/6]

void from_msg	(	const navmap_ros_interfaces::msg::NavMapLayer &	msg,
		navmap::NavMap &	nm )

Backward-compatible overload (ignores message header).

from_msg() [6/6]

void from_msg	(	const navmap_ros_interfaces::msg::NavMapLayer &	msg,
		navmap::NavMap &	nm,
		std_msgs::msg::Header &	header )

Import a single NavMapLayer message into a NavMap.

If the layer already exists in nm, it is overwritten. Otherwise, it is created. Performs type dispatch based on the message field type.

Parameters

[in]	msg	Input NavMapLayer message.
[in,out]	nm	Destination NavMap (must already have navcels sized correctly).
[out]	header	Header extracted from the message.

• Exactly one of the arrays data_u8, data_f32, data_f64 or data_i16 must be set.
• With indices, only those NavCels are written (sparse update of an existing layer of the same type); without them, the whole layer is replaced, with its metadata.
• A message whose geometry_id is set and differs from nm.geometry_id() is rejected.

Exceptions

std::runtime_error

If the message belongs to another geometry, a sparse update does not match its layer, or the type is unsupported.

from_occupancy_grid() [1/2]

navmap::NavMap from_occupancy_grid

(

const nav_msgs::msg::OccupancyGrid &

grid

)

Backward-compatible overload (ignores grid header).

from_occupancy_grid() [2/2]

navmap::NavMap from_occupancy_grid	(	const nav_msgs::msg::OccupancyGrid &	grid,
		std_msgs::msg::Header &	header )

Build a navmap::NavMap from a nav_msgs::msg::OccupancyGrid using a regular triangular surface with shared vertices.

Parameters

[in]	grid	Input ROS OccupancyGrid (row-major, width×height, resolution and origin).
[out]	header	Header to assign to the resulting message.

Returns

A core navmap::NavMap with:

• Vertices: (W+1) * (H+1) laid on the grid plane, with Z = grid.info.origin.position.z.
• Triangles: 2 * W * H (two per cell), using diagonal pattern = 0.
• One surface whose frame matches grid.header.frame_id, and grid metadata filled.
• A per-NavCel layer named "occupancy" of type uint8, with values mapped as: -1 → 255 (unknown), 0..100 → 0..254 (linear scaling).

• Vertex layout follows the grid indexation with shared vertices across adjacent cells.
• Triangle winding and diagonal split are deterministic (pattern = 0).
• If width == 0 or height == 0, the returned map contains no triangles.

Note

The grid origin pose may contain a rotation. The vertex Z is taken from the origin Z; handling of non-zero yaw/roll/pitch (if any) is implementation-defined in the builder.

from_pointcloud2()

navmap::NavMap from_pointcloud2	(	const sensor_msgs::msg::PointCloud2 &	pc2,
		navmap_ros_interfaces::msg::NavMap &	out_msg,
		BuildParams	params )

Build a NavMap surface from a ROS sensor_msgs::msg::PointCloud2.

Parameters

[in]	pc2	Input PointCloud2 message (expects fields x, y, z).
[out]	out_msg	Output transport message mirroring the created NavMap.
[in]	params	Meshing and filtering parameters (see ::BuildParams).

Returns

The constructed navmap::NavMap.

• The cloud is decoded to pcl::PointXYZ and processed as in navmap_ros::from_points.
• Non-Cartesian fields present in pc2 are ignored by this overload.
• The resulting NavMap is exported to out_msg for downstream publication or storage.

Note

If the message is empty or lacks the required fields, no geometry is produced.

Exceptions

std::runtime_error

If decoding fails or meshing cannot be completed.

from_points() [1/2]

navmap::NavMap from_points	(	const pcl::PointCloud< pcl::PointWithViewpoint > &	input_points,
		navmap_ros_interfaces::msg::NavMap &	out_msg,
		BuildParams	params )

Build a NavMap from a cloud with the sensor position of each point.

Same as the PointXYZ overload, on the cloud cleaned by filter_with_viewpoints().

from_points() [2/2]

navmap::NavMap from_points	(	const pcl::PointCloud< pcl::PointXYZ > &	input_points,
		navmap_ros_interfaces::msg::NavMap &	out_msg,
		BuildParams	params )

Build a NavMap from an unorganized point cloud (multi-level grid triangulation).

Parameters

[in]	input_points	Point set in world coordinates (pcl::PointXYZ).
[out]	out_msg	Output transport message mirroring the created NavMap.
[in]	params	Meshing and filtering parameters (see ::BuildParams).

Returns

The constructed navmap::NavMap (empty if nothing could be meshed).

• Points are binned in XY cells of params.resolution. In each cell, points closer than max(min_clearance, max_dz) in z form one level. Its height at the cell centre comes from a robust plane fit of its upper face (points above a gap of max_dz / 2, e.g. a slab seen from above and below); a face whose spread around the plane exceeds max_dz is clutter and keeps a high top (an obstacle). Stacked floors give several vertices per cell.
• Enclosed empty regions up to max_hole_area are filled by interpolating the levels present around most of their border.
• Vertices of neighbouring cells are linked to the closest level within max_dz + tan(max_slope_deg) * distance, only when the choice is mutual.
• Each grid quad gets at most the two triangles of one diagonal per connected level, so every edge has at most two triangles (manifold), and no triangle steeper than max_slope_deg is created.
• Surfaces are the connected components; max_surfaces and min_surface_area drop the smaller ones together with their triangles and vertices.
• Adds per-triangle layers "elevation" (mean vertex height) and "support" (points behind the weakest vertex, up to 255; 0 = interpolated over a hole). Frame id is "map".

from_regular_grid()

navmap::NavMap from_regular_grid	(	const pcl::PointCloud< pcl::PointXYZ > &	grid_points,
		navmap_ros_interfaces::msg::NavMap &	out_msg,
		BuildParams	params )

Build a NavMap surface from an organized (grid-shaped) PCL point cloud.

Unlike navmap_ros::from_points – which discovers connectivity by neighbor search over an otherwise-unstructured point set, a heuristic that needs either a generous params.neighbor_radius (at real cost in redundant, overlapping triangles) or leaves gaps on an evenly-sampled surface even when every cell is individually navigable – this overload takes a cloud whose grid connectivity is already known (row-major, cloud.width x cloud.height, exactly as PCL's own "organized point cloud" convention) and builds the two triangles per grid cell directly from the (i, j) indices, the same deterministic scheme navmap_ros::from_occupancy_grid already uses. No neighbor search, no possibility of a meshing-artifact gap: the only triangles skipped are ones that fail the slope filter (params.max_slope_deg) or reference a non-finite vertex, i.e. every remaining hole is a real "not navigable here" gap, not a search-radius artifact.

Parameters

[in]	grid_points	Organized point set (cloud.height must be > 1); row j, column i is at index j * cloud.width + i.
[out]	out_msg	Output transport message mirroring the created NavMap.
[in]	params	Only params.max_slope_deg and params.max_surfaces apply here; the neighbor-search/edge-length/angle fields are meaningless without a search step and are ignored.

Returns

The constructed navmap::NavMap; empty if grid_points is not organized (height <= 1) or is smaller than 2x2.

to_layer_update_msg()

navmap_ros_interfaces::msg::NavMapLayer to_layer_update_msg	(	const navmap::NavMap &	nm,
		const std::string &	layer,
		const std_msgs::msg::Header &	header = std_msgs::msg::Header(),
		float	max_sparse_fraction = 0.25f )

Layer update with only what changed since the layer's last clear_changes().

Sparse (indices + values) when few NavCels changed one by one; the full layer when the whole layer changed, nothing did, or more than max_sparse_fraction of it did. Carries the geometry id, so a receiver can reject an update for another map. Does not clear the changes.

Exceptions

std::runtime_error

If the layer does not exist.

to_msg() [1/4]

NavMap to_msg

(

const navmap::NavMap &

nm

)

Backward-compatible overload (no header provided).

The returned message header will be default-constructed.

to_msg() [2/4]

navmap_ros_interfaces::msg::NavMapLayer to_msg	(	const navmap::NavMap &	nm,
		const std::string &	layer )

Backward-compatible overload (no header provided).

to_msg() [3/4]

navmap_ros_interfaces::msg::NavMapLayer to_msg	(	const navmap::NavMap &	nm,
		const std::string &	layer,
		const std_msgs::msg::Header &	header )

Convert a single layer from a NavMap into a ROS message.

Parameters

[in]	nm	Input NavMap.
[in]	layer	Name of the layer to export.
[in]	header	Header to assign to the resulting message.

Returns

A NavMapLayer message containing the layer values and metadata.

• The returned message contains the layer name, type tag, and exactly one populated data array whose length equals the number of NavCels in nm.
• The function performs a type-safe extraction (U8/F32/F64).

Exceptions

std::runtime_error

If the layer does not exist or has an unsupported type.

to_msg() [4/4]

NavMap to_msg	(	const navmap::NavMap &	nm,
		const std_msgs::msg::Header &	header )

Convert a core navmap::NavMap into its compact ROS transport message.

Parameters

[in]	nm	Core NavMap to be serialized into a ROS message.
[in]	header	Header to assign to the resulting message.

Returns

A navmap_ros_interfaces::msg::NavMap containing geometry (vertices, triangles), surfaces metadata and user-defined layers.

• Intended to be lossless with respect to the information represented in the message.
• The ordering of vertices/triangles/layers in nm is preserved in the resulting message.

Note

This function does not perform IO; it only builds the message in-memory.

to_occupancy_grid() [1/2]

nav_msgs::msg::OccupancyGrid to_occupancy_grid

(

const navmap::NavMap &

nm

)

Backward-compatible overload.

to_occupancy_grid() [2/2]

nav_msgs::msg::OccupancyGrid to_occupancy_grid	(	const navmap::NavMap &	nm,
		const std_msgs::msg::Header &	header )

Convert a navmap::NavMap back to nav_msgs::msg::OccupancyGrid.

Parameters

[in]

nm

Core NavMap to be rasterized as an occupancy grid.

Returns

A ROS OccupancyGrid populated from nm.

Two paths are considered:

• Fast exact path: If the first surface encodes valid grid metadata (GridMeta) and there is a per-NavCel "occupancy" layer of type U8 with size 2 * W * H, the function reconstructs an OccupancyGrid exactly (linear inverse mapping 0..254 → 0..100, 255 → -1).
• Generic fallback: If the exact path is not applicable, the function samples cell centers via a navcel-locator (e.g., locate_navcel) and reads "occupancy" values to populate the grid.

Note

The fallback path assumes the presence of an "occupancy" layer. The precise sampling strategy (bounds, resolution, and handling of cells without a containing navcel) is implementation-defined.

Warning

If the map does not carry grid metadata or the "occupancy" layer is missing, the result may be incomplete or implementation-defined.

Variable Documentation

FREE_SPACE

std::uint8_t FREE_SPACE

constexpr

Known free.

INSCRIBED_INFLATED_OBSTACLE

std::uint8_t INSCRIBED_INFLATED_OBSTACLE

constexpr

The robot would touch an obstacle.

LETHAL_OBSTACLE

std::uint8_t LETHAL_OBSTACLE

constexpr

Obstacle.

MAX_NON_OBSTACLE

std::uint8_t MAX_NON_OBSTACLE

constexpr

Highest traversable cost.

NO_INFORMATION

std::uint8_t NO_INFORMATION

constexpr

Unknown, not observed.