quantize.h File Reference

Header-only helpers for linear integer quantisation and dequantisation. More...

#include <limits>
#include <type_traits>
#include "./macros.h"

Include dependency graph for quantize.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
	vlink
	vlink::Quantize
	Stateless linear quantisation helpers.

Functions
template<typename QuantT , typename MinT , typename MaxT , typename ValueT >
QuantT	vlink::Quantize::encode (MinT quant_min, MaxT quant_max, ValueT value) noexcept
	Quantizes a value from a real range into an integral type. More...
template<typename ReturnT , typename MinT , typename MaxT , typename ValueT >
ReturnT	vlink::Quantize::decode (MinT quant_min, MaxT quant_max, ValueT value) noexcept
	Dequantizes an integral value into a real range. More...
template<typename QuantT , typename ExtentT , typename ValueT >
QuantT	vlink::Quantize::encode (ExtentT extent, ValueT value) noexcept
	Quantizes a value from [-extent,+extent] into a signed integral type. More...
template<typename ReturnT , typename ExtentT , typename ValueT >
ReturnT	vlink::Quantize::decode (ExtentT extent, ValueT value) noexcept
	Dequantizes a signed integral value from [-extent,+extent]. More...

Detailed Description

Header-only helpers for linear integer quantisation and dequantisation.

vlink::Quantize provides the small, deterministic numeric conversion used by compact containers such as zerocopy::PointCloud. It linearly maps a caller supplied real interval (quant_min, quant_max) to an integral storage interval and provides the inverse mapping for reads. The helpers are templates so the public API stays allocation-free, exception-free and independent of any particular point-cloud type.

Mapping model

Step	Behaviour
Encode	Map value from [quant_min,quant_max] into QuantT storage.
Decode	Map an integral storage value back with the same linear transform.
Rounding	Round half away from zero before casting to the storage type.
Type math	Use std::common_type_t<float,...> so all-integer inputs still divide in floating point.
Bad range	Return zero when any input is NaN or quant_max <= quant_min.
Saturation	Clamp encoded values to the storage limits when the scaled value overflows.

For signed storage types, the normal mapping interval is symmetric: [-std::numeric_limits<T>::max(),std::numeric_limits<T>::max()]. The most negative storage value, such as -32768 for int16_t, is reserved for negative saturation. It is accepted by decode, but because it sits one step below the normal interval it can decode slightly below quant_min. This keeps 0 centred for ranges like [-extent,+extent].

Typical usage

constexpr int extent = 100;
 
int16_t qx = vlink::Quantize::encode<int16_t>(extent, x);  // maps [-extent,+extent]
float x_out = vlink::Quantize::decode<float>(extent, qx);

Example

int16_t stored = vlink::Quantize::encode<int16_t>(-10, 10, 1.25f);
float value = vlink::Quantize::decode<float>(-10, 10, stored);