field.h

Class

class Field : public ouster::FieldView

RAII memory-owning container for arbitrary typed and sized arrays and POD structs with optional type checking

For usage examples, check unit tests

Public Functions

Field() noexcept

Default constructor, representing invalid Field

~Field()

Field destructor

Field(const FieldDescriptor &desc, FieldClass field_class = {})

Constructs Field from FieldDescriptor

Parameters:
Field(const Field &other)

Copy constructor

Parameters:

other – [in] Field to copy

Field &operator=(const Field &other)

Copy assignment constructor

Parameters:

other – [in] Field to copy

Field(Field &&other) noexcept

Move constructor

Parameters:

other – [in] Field to steal resource from

Field &operator=(Field &&other) noexcept

Move assignment constructor

Parameters:

other – [in] Field to steal resource from

FieldClass field_class() const

Get field class

Returns:

FieldClass

void swap(Field &other) noexcept

Swaps two Fields

Parameters:

other – [in] Field to swap resources with

bool operator==(const Field &other) const

Equality operator

Returns:

true if type, shape and memory contents are equal to other

class FieldView

Non-owning wrapper over a memory pointer that allows for type safe conversion to typed pointer, eigen array or ArrayView

Subclassed by ouster::Field

Public Functions

FieldView() noexcept

Default constructor for empty FieldView

FieldView(void *ptr, const FieldDescriptor &desc)

Initialize FieldView with a pointer and a descriptor

Parameters:

  • ptr – [in] Memory pointer.

  • desc – [in] Field descriptor.

template<typename T = void>
inline T *get()

Returns arbitrary pointer type

Throws:

std::invalid_argument – on type mismatch unless FieldView was constructed typeless (with type void) or dereference type is void*

Template Parameters:

T – pointer type

Returns:

typed pointer to the memory

template<typename T>
inline operator T*()

Arbitrary type ptr conversion

Throws:

std::invalid_argument – on type mismatch unless FieldView was constructed with void ptr or the requested ptr type is void*

template<typename T>
inline operator const T*() const

Arbitrary type const ptr conversion

Throws:

std::invalid_argument – on type mismatch unless FieldView was constructed with void ptr or the requested ptr type is void*

template<typename T, int Dim>
inline operator ArrayView<T, Dim>()

Arbitrary type ArrayView conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

template<typename T, int Dim>
inline operator ConstArrayView<T, Dim>() const

Arbitrary type const ArrayView conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

template<typename T>
inline operator Eigen::Ref<img_t<T>>()

Arbitrary type Eigen 2D array conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

template<typename T>
inline operator Eigen::Ref<const img_t<T>>() const

Arbitrary type const Eigen 2D array conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

template<typename T>
inline operator Eigen::Ref<Eigen::Array<T, Eigen::Dynamic, 1>>()

Arbitrary type const Eigen 1D array conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

template<typename T>
inline operator Eigen::Ref<const Eigen::Array<T, Eigen::Dynamic, 1>>() const

Arbitrary type const Eigen 1D array conversion

Throws:

  • std::invalid_argument – on type mismatch

  • std::invalid_argument – on dimensional shape mismatch

explicit operator bool() const noexcept

Bool conversion

Returns:

true if FieldView is owning a resource

template<typename ...Args>
inline FieldView subview(Args... idx) const

Get a subview

Operates similarly to numpy ndarray bracket operator, returning a sliced, potentially sparse subview

The following two snippets are functionally equivalent 

std::vector<int> data(100*100*100);
FieldView view(data.data(), fd_array<int>(100, 100, 100));
// get a slice of all elements in the first dimension with second
// and third pinned to 10 and 20 respectively
FieldView subview = view.subview(keep(), 10, 20);


import numpy as np
arr = np.ndarray(shape=(100,100,100), dtype=np.int32)
subview = arr[:,10,20]
Throws:

std::invalid_argument – If FieldView ran out of dimensions to subview or if FieldView cannot subview over the shape limits

Parameters:

idx – [in] parameter pack of int indices or idx_range (keep())

Returns:

FieldView subview

template<typename ...Args>
inline FieldView reshape(Args... dims) const

Reshape field view to a different set of dimensions

Throws:

  • std::invalid_argument – on trying to reshape a sparse FieldView

  • std::invalid_argument – on flattened dimension size not matching the original view size

Parameters:

dims – [in] new dimensions

Returns:

reshaped FieldView with new dimensions

size_t bytes() const noexcept

Returns the number of allocated bytes in memory

Returns:

size in bytes

size_t size() const

Returns size in elements, or 1 if field is not an array

Returns:

size in elements

bool matches(const FieldDescriptor &d) const noexcept

returns true if FieldView matches descriptor

Parameters:

d – [in] descriptor to check

Returns:

true if matched, otherwise false

const FieldDescriptor &desc() const

Get descriptor of the underlying memory

Returns:

FieldDescriptor

const std::vector<size_t> &shape() const

Get shape of the stored array, if present

shorthand for desc().shape

Returns:

vector of dimensions

sensor::ChanFieldType tag() const

Get type tag, if applicable

Returns:

ChanFieldType

bool sparse() const

Check if the FieldView is not contiguous

Returns:

true if sparse

Structs

struct FieldDescriptor

Helper struct used by FieldView and Field to describe field contents. Unlike FieldType this fully describes a Field’s dimensions rather than abstract away the lidar width and height or packet count.

Public Functions

size_t bytes() const

Calculates the size in bytes of the described field

Returns:

type size in bytes

size_t size() const

Get array size in elements, or 1 if shape is not present

Returns:

size in elements

sensor::ChanFieldType tag() const

Get type tag, if can be translated to ChanFieldType, otherwise returns ChanFieldType::UNREGISTERED

Returns:

ChanFieldType

void swap(FieldDescriptor &other)

Swaps descriptors

Parameters:

other – [inout] Handle to swapped FieldDescriptor.

template<typename T>
inline bool eligible_type() const

Check if the type is eligible for conversion

Returns:

true if eligible, otherwise false.

bool is_type_compatible(const FieldDescriptor &other) const noexcept

Check if descriptor types are compatible

Parameters:

other – [in] A constant of type FieldDescriptor.

Returns:

true if compatible, otherwise false.

size_t ndim() const noexcept

Return number of dimensions of the described field

Returns:

number of dimensions.

Public Members

size_t type

type hash of the described field

std::vector<size_t> shape

vector of array dimensions of the described field, if present

std::vector<size_t> strides

vector of stride offsets of the described field, if present

size_t element_size

size of the underlying type, in bytes

Public Static Functions

template<typename T>
static inline size_t type_hash()

Get type hash

warning: different platforms produce different values

Returns:

hash value

template<typename T = void>
static inline FieldDescriptor memory(size_t bytes)

Get a field descriptor for a chunk of typed memory

useful when storing arbitrary sized structs.

Template Parameters:

T – Type of memory to be stored; this gets used by safety checks.

Parameters:

bytes – [in] Number of bytes in memory.

Returns:

FieldDescriptor

template<typename T, class ContainerT = std::initializer_list<size_t>>
static inline FieldDescriptor array(const ContainerT &shape)

Get a field descriptor for an array

Template Parameters:

T – Array type

Parameters:

shape – [in] Shape vector of array dimensions.

Returns:

FieldDescriptor

template<class ContainerT = std::initializer_list<size_t>>
static inline FieldDescriptor array(sensor::ChanFieldType tag, const ContainerT &shape)

Get a field descriptor for an array

Parameters:

  • tag – [in] Tag of array type.

  • shape – [in] Vector of array dimensions.

Returns:

FieldDescriptor

Functions

Field ouster::destagger(const ouster::sensor::sensor_info &info, const FieldView &field, bool inverse = false)

Destagger or restagger a field according to the provided sensor info.

Throws:

std::invalid_argument – if the pixel_shift_by_row height does not match the field

Parameters:

  • info – [in] sensor info to use to stagger/destagger

  • field – [in] field to stagger/destagger

  • inverse – [in] if true, stagger the data rather than destagger

Returns:

the staggered/destaggered field

FieldView ouster::uint_view(const FieldView &other)

Acquire a uintXX_t reinterpreted view of the matching type size. Useful for memory related operations like parsing and compression.

WARNING: reinterprets the type skipping type safety checks, exercise caution

Throws:

  • std::invalid_argument – if other is not an array view

  • std::invalid_argument – if other is an array view of custom POD types that do not match any uintXX_t dimensions

Parameters:

other – [in] view to interpret

Returns:

reinterpreted view of uint8_t, uint16_t, uint32_t or uint64_t type