metadata.h

Public API

class MetadataEntry

Base abstract metadata entry type for every metadata that can be stored as OSF metadata.

Metadata object that is stored/serialized to OSF is a triplet: {id, type, buffer}

id - is a unique identifier per OSF file and used for references from other metadata objects or from messages (chunk.StampedMessage.id in chunk.fbs) to link messages with the streams.

type - string that is unique per OSF generation (i.e. v2) and used to link datum buffer representation to the concrete metadata object.

Type is specified when concrete metadata type class defined via MetadataTraits struct specialization, example:

template <>
struct MetadataTraits<MyMeta> {
    static const std::string type() {
        return "ouster/v1/something/MyMeta";
    }
};

buffer - byte representation of the metadata content whatever it is defined by concrete metadata type. Every metadata object should have a recipe how to serialize itself to the bytes buffer by overwriting the buffer() function. And the recipe how to recover itserf by providing static from_buffer(buf, type) function.

Subclassed by ouster::osf::MetadataEntryHelper< Extrinsics >, ouster::osf::MetadataEntryHelper< LidarScanStreamMeta >, ouster::osf::MetadataEntryHelper< LidarSensor >, ouster::osf::MetadataEntryHelper< StreamingInfo >, ouster::osf::MetadataEntryHelper< DerivedMetadataEntry >, ouster::osf::MetadataEntryRef

Public Types

using from_buffer_func = std::unique_ptr<MetadataEntry> (*)(const std::vector<uint8_t>&)

Function type to recover metadata object from buffer.

Public Functions

virtual std::string type() const = 0

Returns:

Type of the metadata, used to identify the object type in serialized OSF and as key in deserialization registry

virtual std::string static_type() const = 0

Returns:

Same as type with the difference that type() can be dynamic and static_type() should always be defined in compile time. NOTE: Introduced as a convenience/(HACK?) to simpler reconstruct and cast dynamic objects from MetadataEntryRef

virtual std::unique_ptr<MetadataEntry> clone() const = 0

Should be provided by derived class and is used in handling polymorphic objects and avoid object slicing

Returns:

Should return a clone of the current MetadataEntry

virtual std::vector<uint8_t> buffer() const = 0

Byte represantation of the internal derived metadata type, used as serialization function when saving to OSF file.

Returns:

The byte vector representation of the metadata.

virtual std::string repr() const

String representation of the internal metadata object, used in to_string() for debug/info outputs.

Returns:

The string representation for the internal metadata object.

virtual std::string to_string() const

String representation of the whole metadata entry with type and id.

Todo:

Figure out why we have both repr and to_string

Returns:

The string representation of the whole metadata entry.

void setId(uint32_t id)

Unique id used inside the flatbuffer metadata store to refer to metadata entries.

Parameters:

id – [in] The unique id to set.

template<typename T>
inline std::unique_ptr<T> as() const

Casting of the base class to concrete derived metadata entry type. Always creates new object with allocation via clone() if the pointer/ref is a polymorphic object, or as reconstruction from buffer() representation when it used from MetadataEntryRef (i.e. wrapper on underlying bytes)

Template Parameters:

T – The derived metadata type

Returns:

A unique pointer to the derived metadata object, nullptr on error.

flatbuffers::Offset<ouster::osf::gen::MetadataEntry> make_entry(flatbuffers::FlatBufferBuilder &fbb) const

Implementation details that emits buffer() content as proper Flatbuffer MetadataEntry object.

Parameters:

fbb – [in] The flatbuffer builder to use to make the entry.

Returns:

An offset into a flatbuffer for the new entry.

Public Static Functions

static std::unique_ptr<MetadataEntry> from_buffer(const std::vector<uint8_t> &buf, const std::string type_str)

Recover metadata object from the bytes representation if possible. If recovery is not possible returns nullptr

Parameters:

• buf – [in] The buffer to recover the metadata object from.

• type_str – [in] The type string from the derived type.

Returns:

A new object of the derived type cast as a MetadataEntry

static std::map<std::string, from_buffer_func> &get_registry()

Method to return the registry that holds from_buffer function by type string and is used during deserialization. The registry is a static variable defined within the get_registry method.

Returns:

The static registry used to register metadata types.

Related

uint32_t id() const

Unique id used inside the flatbuffer metadata store to refer to metadata entries.

Returns:

The unique id of this object.

class MetadataEntryRef : public ouster::osf::MetadataEntry

MetadataEntry wrapper for byte Flatbuffers bytes representation. Used during deserialization and acts as regular polymorphic metadata type (almost).

Doesn’t own the memory of the underlying buffer.

Reconstructs itself to the concrete metadata type with:

as_type() - using the stored type() to recofer deserialization function

as<MetadataDerived>() OR metadata_pointer_as<MetadataDerived>() - using the specified derived metadata class.

Public Functions

explicit MetadataEntryRef(const uint8_t *buf)

Creates the metadata reference from Flatbuffers v2::MetadataEntry buffer. No copy involved.

Parameters:

buf – [in] The buffer to create the MetadataEntryRef from.

virtual std::string type() const override

Return the type of the MetadataEntry.

Returns:

The type of the MetadataEntry.

virtual std::string static_type() const override

Return the type of the MetadataEntry.

Returns:

The type of the MetadataEntry.

virtual std::unique_ptr<MetadataEntry> clone() const override

Clone the MetadataEntry.

Returns:

The cloned MetadataEntry object.

virtual std::vector<uint8_t> buffer() const final

Return the raw underlying buffer for the MetadataEntryRef.

Returns:

The raw underlying byte vector.

std::unique_ptr<MetadataEntry> as_type() const

Reconstructs the object as concrete metadata of type() from the buffer() using registered deserialization function from_buffer() of current type

Returns:

The reconstructed object.

class MetadataStore

Collection of metadata entries, used as metadata provider in Reader and Writer.

Provide functions to retrieve concrete metadata types by id or by type.

Also can serialize itself to Flatbuffers collection of metadata.

Public Functions

uint32_t add(MetadataEntry &&entry)

Add a specified MetadataEntry to the store

Parameters:

entry – [in] The entry to add to the store.

Returns:

The metadata id of the entry added.

uint32_t add(MetadataEntry &entry)

Add a specified MetadataEntry to the store

Parameters:

entry – [in] The entry to add to the store.

Returns:

The metadata id of the entry added.

template<class MetadataEntryClass>
inline std::shared_ptr<MetadataEntryClass> get() const

Get the first specified MetadataEntry associated to the template parameter.

Template Parameters:

MetadataEntryClass – The metadata cpp type to try and retrieve.

Returns:

The MetadataEntry of type MetadataEntryClass if it exists.

template<class MetadataEntryClass>
inline size_t count() const

Count the number of specified MetadataEntry associated to the template parameter.

Template Parameters:

MetadataEntryClass – The metadata cpp type to try and count.

Returns:

The count type MetadataEntryClass.

template<class MetadataEntryClass>
inline std::shared_ptr<MetadataEntryClass> get(const uint32_t metadata_id) const

Get the specified MetadataEntry associated to the template parameter and metadata_id.

Template Parameters:

MetadataEntryClass – The metadata cpp type to try and retrieve.

Parameters:

metadata_id – [in] The id to try and return the associated entry.

Returns:

The MetadataEntryClass.

inline std::shared_ptr<MetadataEntry> get(const uint32_t metadata_id) const

Get the specified MetadataEntry associated to the metadata_id.

Parameters:

metadata_id – [in] The id to try and return the associated entry.

Returns:

The MetadataEntry.

template<class MetadataEntryClass>
inline std::map<uint32_t, std::shared_ptr<MetadataEntryClass>> find() const

Return a map containing all of the MetadataEntries that match the specified template class.

Template Parameters:

MetadataEntryClass – The metadata cpp type to try and retrieve.

Returns:

The MetadataEntry map.

size_t size() const

Return the number of MetadataEntries.

Returns:

The number of MetadataEntry objects.

const MetadataEntriesMap &entries() const

Return the entire map of MetadataEntry.

Returns:

The entire map of MetadataEnty objects.

std::vector<flatbuffers::Offset<ouster::osf::gen::MetadataEntry>> make_entries(flatbuffers::FlatBufferBuilder &fbb) const

Serialize the MetadataStore to the specified flatbuffer builder and return the resulting byte vector.

Parameters:

fbb – [in] The flatbuffer builder to use.

Returns:

The resulting serialized byte vector.

template<typename MetadataDerived, typename MetadataBase>
std::shared_ptr<MetadataDerived> ouster::osf::metadata_pointer_as(const std::shared_ptr<MetadataBase> &m)

Safe and convenient cast of shared_ptr<MetadataEntry> to concrete derived class using either shortcut (dynamic_pointer_cast) when it’s save to do so or reconstructs a new copy of the object from underlying data.

Template Parameters:

• MetadataDerived – The cpp type of the derived object.

• MetadataBase – The cpp type of the metadata base.

Parameters:

m – [in] The MetadataBase to convert to MetadataDerived.

Returns:

The MetadataBase cast as a MetadataDerived pointer.

Internal API

template<typename DerivedMetadataEntry>
class MetadataEntryHelper : public ouster::osf::MetadataEntry, private ouster::osf::RegisterMetadata<DerivedMetadataEntry>

Helper class used as base class for concrete derived metadata types and provides type()/static_type()/clone() functions as boilerplate.

Also registers the from_buffer() function for deserializer registry via RegisterMetadata helper trick.

Template Parameters:

DerivedMetadataEntry – The derived Metadata Entry type.

Public Functions

inline virtual std::string type() const override

Return the metadata type string for the specific derived class.

Returns:

The specific type string for the derived class.

inline virtual std::string static_type() const override

Return the metadata type string for the specific derived class.

Returns:

The specific type string for the derived class.

inline virtual std::unique_ptr<MetadataEntry> clone() const override

Clone the specific derived metadata object.

Returns:

The cloned MetadataEntry object.

template<class MetadataDerived>
struct RegisterMetadata

Registrar class helper to add static from_buffer() function of the concrete derived metadata class to the registry.

Template Parameters:

MetadataDerived – The derived subclass cpp type.

Public Static Functions

static inline bool register_type_decoder()

Register the specific derived class decoder into the global registrar.

Returns:

true If class has been registered successfully, false otherwise.

Public Static Attributes

static const bool registered_ = RegisterMetadata<MetadataDerived>::register_type_decoder()

If the derived class has been registered.

This line is incredibly IMPORTANT. This will statically run the registration for all derived classes before the class constructer is run.

Template Parameters:

MetadataDerived – The derived subclass cpp type.

template<typename MetadataDerived>
struct MetadataTraits

Need to be specialized for every derived MetadataEntry class that can be stored/recovered as metadata object.

See also

metadata_type(), MetadataEntry

Template Parameters:

MetadataDerived – The derived subclass cpp type.

Public Static Functions

static inline const std::string type()

Default type returning nullptr.

Todo:

Possible undefined behavior here.

Returns:

nullptr

template<typename StreamMeta, typename ObjectType>
struct MessageStream

Tag helper for Stream types that need to bind (link) together message ObjectType and the corresponding metadata entry (StreamMeta) that form together the stream definition.

template<typename MetadataDerived>
inline const std::string ouster::osf::metadata_type()

Helper function that returns the MetadataEntry type of concrete metadata.

Template Parameters:

MetadataDerived – The derived subclass cpp type.

Returns:

metadata type