label_semantics.hpp File Reference

Single source of truth for label encodings across the pipeline. More...

#include <cstdint>
#include <stdexcept>
#include <string>
#include <opencv2/core.hpp>

Include dependency graph for label_semantics.hpp:

Go to the source code of this file.

Namespaces
namespace	reusex
namespace	reusex::core

Functions
constexpr bool	reusex::core::is_valid_label (uint32_t label) noexcept
size_t	reusex::core::label_to_index (uint32_t label)
	Convert a point label to a zero-based vector index, replacing the error-prone bare label - 1 idiom used to index parallel arrays such as plane_normals.
uint32_t	reusex::core::api_to_point_label (int api_label)
	API (CV_32S, -1 = background) → point label (uint32_t, 0 = unlabeled).
int	reusex::core::point_label_to_api (uint32_t point_label)
	Point label (uint32_t, 0 = unlabeled) → API (CV_32S, -1 = background).
uint16_t	reusex::core::api_to_storage (int api_label)
	API label (CV_32S, -1 = background) → storage value (CV_16U, 0 = bg, label + 1).
int	reusex::core::storage_to_api (uint16_t storage_value)
	Storage value (CV_16U, 0 = bg, label + 1) → API label (CV_32S, -1 = background).
cv::Mat	reusex::core::storage_mat_to_api (const cv::Mat &storage)
	Convert a storage label image (CV_16U, 0 = bg) to an API label image (CV_32S, -1 = background) by subtracting the +1 offset.
cv::Mat	reusex::core::api_mat_to_storage (const cv::Mat &api)
	Convert an API label image (CV_32S, -1 = background) to a storage label image (CV_16U, 0 = bg) by adding the +1 offset.

Variables
constexpr uint32_t	reusex::core::kUnlabeled = 0
	Point-cloud convention: 0 means "unlabeled" in every CloudL (labels, planes, rooms, instances).
constexpr int	reusex::core::kBackgroundApi = -1
	ProjectDB segmentation API convention: -1 marks background/unlabeled in the CV_32S label images returned by ProjectDB.
constexpr uint16_t	reusex::core::kMaxStorableLabel = 65534
	Largest label that can be stored in the CV_16U PNG layer.

Detailed Description

Single source of truth for label encodings across the pipeline.

Three layers encode labels differently (see docs/STANDARDS.md §3.1):

| Layer | Type | Unlabeled/bg | Valid | |---------------------------------—|---------—|--------------------—|-------—| | segmentation_images storage (PNG) | CV_16U | 0 (stored label+1) | 1..65535 (label ≤ 65534) | | ProjectDB segmentation API | CV_32S | -1 | 0..N | | In-memory point labels (pcl::Label)| uint32_t | 0 | 1..N |

Conversions between layers MUST go through the helpers here; no inline offset arithmetic (label + 1, label - 1) or raw casts are allowed at call sites. Writing a label ≥ 65535 to storage throws instead of wrapping.

Definition in file label_semantics.hpp.