lidar_scan.h

LidarScan
Destagger
XYZLut
ScanBatcher

LidarScan 

class ouster::LidarScan

Data structure for efficient operations on aggregated lidar data.

Stores each field (range, intensity, etc.) contiguously as a H x W block of 4-byte unsigned integers, where H is the number of beams and W is the horizontal resolution (e.g. 512, 1024, 2048).

Note: this is the “staggered” representation where each column corresponds to a single measurement in time. Use the destagger() function to create an image where columns correspond to a single azimuth angle.

Public Types

using raw_t = uint32_t

Deprecated:

using ts_t = std::chrono::nanoseconds

Deprecated:

template<typename T> using Header = Eigen::Array<T, Eigen::Dynamic, 1>: Header typedef.

using Points = Eigen::Array<double, Eigen::Dynamic, 3>: XYZ coordinates with dimensions arranged contiguously in columns.

using Field = sensor::ChanField 

Deprecated:

FieldIter = decltype(field_types_)::const_iterator: An STL Iterator of the field types

Public Functions

LidarScan(): The default constructor creates an invalid 0 x 0 scan.

LidarScan(size_t w, size_t h)

Initialize a scan with fields configured for the LEGACY udp profile.

Parameters

w – [in] horizontal resoulution, i.e. the number of measurements per scan.
h – [in] vertical resolution, i.e. the number of channels.

LidarScan(size_t w, size_t h, sensor::UDPProfileLidar profile)

Initialize a scan with the default fields for a particular udp profile.

Parameters

w – [in] horizontal resoulution, i.e. the number of measurements per scan.
h – [in] vertical resolution, i.e. the number of channels.
profile – [in] udp profile.

template<typename Iterator> inline LidarScan(size_t w, size_t h, Iterator begin, Iterator end)

Initialize a scan with a custom set of fields.

Template Parameters

Iterator – A standard template iterator for the custom fields.

Parameters

w – [in] horizontal resoulution, i.e. the number of measurements per scan.
h – [in] vertical resolution, i.e. the number of channels.
begin – [in] begin iterator of pairs of channel fields and types.
end – [in] end iterator of pairs of channel fields and types.

LidarScan(const LidarScan &other)

Initialize a lidar scan from another lidar scan.

Parameters: other – [in] The other lidar scan to initialize from.

LidarScan(LidarScan &&other)

Initialize a lidar scan from another lidar scan.

Parameters: other – [in] The other lidar scan to initialize from.

LidarScan &operator=(const LidarScan &other)

Copy via Move semantic.

Parameters: other – [in] The lidar scan to copy from.

LidarScan &operator=(LidarScan &&other)

Copy via Move semantic.

Parameters: other – [in] The lidar scan to copy from.

~LidarScan(): Lidar scan destructor.

sensor::ShotLimitingStatus shot_limiting() const: Get frame shot limiting status

sensor::ThermalShutdownStatus thermal_shutdown() const: Get frame thermal shutdown status

std::vector<LidarScan::ts_t> timestamps() const

Access timestamps as a vector.

Deprecated:: See timestamp() instead

Returns: copy of the measurement timestamps as a vector.

BlockHeader &header(size_t m_id)

Access measurement block header fields.

Deprecated:: Please see status(), measurement_id(), and timestamp() instead

Returns: the header values for the specified measurement id.

const BlockHeader &header(size_t m_id) const

Access measurement block header fields.

Deprecated:: Please see status(), measurement_id(), and timestamp() instead

Returns: the header values for the specified measurement id.

template<typename T = uint32_t, typename std::enable_if<std::is_unsigned<T>::value, T>::type = 0> Eigen::Ref<img_t<T>> field(sensor::ChanField f)

Access a lidar data field.

Throws: std::invalid_argument – if T does not match the runtime field type.
Template Parameters: T – The type parameter T must match the dynamic type of the field. See the constructor documentation for expected field types or query dynamically for generic operations.
Parameters: f – [in] the field to view.
Returns: a view of the field data.

template<typename T = uint32_t, typename std::enable_if<std::is_unsigned<T>::value, T>::type = 0> Eigen::Ref<const img_t<T>> field(sensor::ChanField f) const

Access a lidar data field.

Throws: std::invalid_argument – if T does not match the runtime field type.
Template Parameters: T – The type parameter T must match the dynamic type of the field. See the constructor documentation for expected field types or query dynamically for generic operations.
Parameters: f – [in] the field to view.
Returns: a view of the field data.

sensor::ChanFieldType field_type(sensor::ChanField f) const

Get the type of the specified field.

Parameters: f – [in] the field to query.
Returns: the type tag associated with the field.

FieldIter begin() const: A const forward iterator over field / type pairs.

FieldIter end() const: A const forward iterator over field / type pairs.

Eigen::Ref<Header<uint64_t>> timestamp()

Access the measurement timestamp headers.

Returns: a view of timestamp as a w-element vector.

Eigen::Ref<const Header<uint64_t>> timestamp() const

Access the measurement timestamp headers.

Returns: a view of timestamp as a w-element vector.

Eigen::Ref<Header<uint16_t>> measurement_id()

Access the measurement id headers.

Returns: a view of measurement ids as a w-element vector.

Eigen::Ref<const Header<uint16_t>> measurement_id() const

Access the measurement id headers.

Returns: a view of measurement ids as a w-element vector.

Eigen::Ref<Header<uint32_t>> status()

Access the measurement status headers.

Returns: a view of measurement statuses as a w-element vector.

Eigen::Ref<const Header<uint32_t>> status() const

Access the measurement status headers.

Returns: a view of measurement statuses as a w-element vector.

bool complete(sensor::ColumnWindow window) const

Assess completeness of scan.

Parameters: window – [in] The column window to use for validity assessment
Returns: whether all columns within given column window were valid

Public Members

std::ptrdiff_t w = {0}: Pointer offsets to deal with strides.

Warning

Members variables: use with caution, some of these will become private.

std::ptrdiff_t h = {0}: Pointer offsets to deal with strides.

Warning

Members variables: use with caution, some of these will become private.

std::vector<BlockHeader> headers = {}

Vector containing the header definitions.

Deprecated:: BlockHeader is deprecated in favor of Header

Warning

Members variables: use with caution, some of these will become private.

uint64_t frame_status = {0}: Frame status - information from the packet header which corresponds to a frame

Warning

Member variables: use with caution, some of these will become private.

int32_t frame_id = {-1}: The current frame ID.

Warning

Members variables: use with caution, some of these will become private.

Public Static Attributes

static constexpr int N_FIELDS = 4

Deprecated:: Number of fields now varies by lidar profile or constructor provided arguments. Use N_FIELDS with caution even when working with legacy lidar profile data, and do not use for all non-legacy lidar profile formats.

static constexpr Field RANGE = sensor::RANGE

Deprecated:

static constexpr Field INTENSITY = sensor::SIGNAL

Deprecated:

static constexpr Field AMBIENT = sensor::NEAR_IR

Deprecated:

static constexpr Field REFLECTIVITY = sensor::REFLECTIVITY

Deprecated:

Friends

friend bool operator==(const LidarScan &a, const LidarScan &b)

Equality for scans.

Parameters

a – [in] The first scan to compare.
b – [in] The second scan to compare.

Returns

if a == b.

struct BlockHeader

Measurement block information, other than the channel data.

Deprecated:: BlockHeaders are deprecated in favor of Header. See timestamp(), measurement_id(), and status()

LidarScan::Points cartesian(const LidarScan &scan, const XYZLut &lut)

Convert LidarScan to Cartesian points.

Parameters

scan – [in] a LidarScan.
lut – [in] lookup tables generated by make_xyz_lut.

Returns

Cartesian points where ith row is a 3D point which corresponds to ith pixel in LidarScan where i = row * w + col.

LidarScan::Points cartesian(const Eigen::Ref<const img_t<uint32_t>> &range, const XYZLut &lut)

Convert a staggered range image to Cartesian points.

Parameters

range – [in] a range image in the same format as the RANGE field of a LidarScan.
lut – [in] lookup tables generated by make_xyz_lut.

Returns

Cartesian points where ith row is a 3D point which corresponds to ith pixel in LidarScan where i = row * w + col.

bool operator==(const LidarScan::BlockHeader &a, const LidarScan::BlockHeader &b)

Equality for column headers.

Deprecated:: BlockHeaders are deprecated

Parameters

a – [in] The first column header to compare.
b – [in] The second column header to compare.

Returns

if a == b.

bool operator==(const LidarScan &a, const LidarScan &b)

Equality for scans.

Parameters

a – [in] The first scan to compare.
b – [in] The second scan to compare.

Returns

if a == b.

inline bool operator!=(const LidarScan &a, const LidarScan &b)

NOT Equality for scans.

Parameters

a – [in] The first scan to compare.
b – [in] The second scan to compare.

Returns

if a != b.

Destagger 

template<typename T> inline img_t<T> destagger(const Eigen::Ref<const img_t<T>> &img, const std::vector<int> &pixel_shift_by_row, bool inverse)

Generate a destaggered version of a channel field.

In the default staggered representation, each column corresponds to a single timestamp. In the destaggered representation, each column corresponds to a single azimuth angle, compensating for the azimuth offset of each beam.

Destaggering is used for visualizing lidar data as an image or for algorithms that exploit the structure of the lidar data, such as beam_uniformity in ouster_viz, or computer vision algorithms.

Template Parameters

T – the datatype of the channel field.

Parameters

img – [in] the channel field.
pixel_shift_by_row – [in] offsets, usually queried from the sensor.
inverse – [in] perform the inverse operation.

Returns

destaggered version of the image.

template<typename T> inline img_t<T> stagger(const Eigen::Ref<const img_t<T>> &img, const std::vector<int> &pixel_shift_by_row)

Generate a staggered version of a channel field.

Template Parameters

T – the datatype of the channel field.

Parameters

img – [in] the channel field.
pixel_shift_by_row – [in] offsets, usually queried from the sensor.

Returns

staggered version of the image.

XYZLut 

struct ouster::XYZLut

Lookup table of beam directions and offsets.

Public Members

LidarScan::Points direction: Lookup table of beam directions.

LidarScan::Points offset: Lookup table of beam offsets.

XYZLut ouster::make_xyz_lut(size_t w, size_t h, double range_unit, const mat4d &beam_to_lidar_transform, const mat4d &transform, const std::vector<double> &azimuth_angles_deg, const std::vector<double> &altitude_angles_deg)

Generate a set of lookup tables useful for computing Cartesian coordinates from ranges.

The lookup tables are:

direction: a matrix of unit vectors pointing radially outwards.
offset: a matrix of offsets dependent on beam origin distance from lidar origin.

Each table is an n x 3 array of doubles stored in column-major order where each row corresponds to the nth point in a lidar scan, with 0 <= n < h*w.

Projections to XYZ made with this XYZLut will be in the coordinate frame defined by transform*beam_to_lidar_transform.

Parameters

w – [in] number of columns in the lidar scan. e.g. 512, 1024, or 2048.
h – [in] number of rows in the lidar scan.
range_unit – [in] the unit, in meters, of the range, e.g. sensor::range_unit.
beam_to_lidar_transform – [in] transform between beams and lidar origin. Translation portion is in millimeters.
transform – [in] additional transformation to apply to resulting points.
azimuth_angles_deg – [in] azimuth offsets in degrees for each of h beams.
altitude_angles_deg – [in] altitude in degrees for each of h beams.

Returns

xyz direction and offset vectors for each point in the lidar scan.

inline XYZLut ouster::make_xyz_lut(const sensor::sensor_info &sensor)

Convenient overload that uses parameters from the supplied sensor_info. Projections to XYZ made with this XYZLut will be in the sensor coordinate frame defined in the sensor documentation.

Parameters: sensor – [in] metadata returned from the client.
Returns: xyz direction and offset vectors for each point in the lidar scan.

ScanBatcher 

class ouster::ScanBatcher

Parse lidar packets into a LidarScan.

Make a function that batches a single scan (revolution) of data to a LidarScan.

Public Functions

ScanBatcher(size_t w, const sensor::packet_format &pf)

Create a batcher given information about the scan and packet format.

Parameters

w – [in] number of columns in the lidar scan. One of 512, 1024, or 2048.
pf – [in] expected format of the incoming packets used for parsing.

ScanBatcher(const sensor::sensor_info &info)

Create a batcher given information about the scan and packet format.

Parameters: info – [in] sensor metadata returned from the client.

bool operator()(const uint8_t *packet_buf, LidarScan &ls)

Add a packet to the scan.

Parameters

packet_buf – [in] the lidar packet.
ls – [in] lidar scan to populate.

Returns

true when the provided lidar scan is ready to use.

Public Members

sensor::packet_format pf: The packet format object used for decoding.

lidar_scan.h

LidarScan

Destagger

XYZLut

ScanBatcher

LidarScan 

Destagger 

XYZLut 

ScanBatcher 