SDK Base Utils

Header helpers classes and functions

template<typename EventType> void Metavision::write_DAT_header(std::ostream &os, const GenericHeader::HeaderMap &header_map)

Writes the DAT header of a file.

Template Parameters

EventType – The type of events stored in the DAT file

Parameters

os – The stream used to store the DAT data
header_map – An optional map of data to be stored in the header

template<typename EventType> std::string Metavision::get_DAT_header_as_string(const GenericHeader::HeaderMap &header_map = GenericHeader::HeaderMap())

Convenience function to get the DAT header as string.

Template Parameters: EventType – The type of events stored in the DAT file
Parameters: header_map – Additional information to be stored in the header
Returns: The string representing the DAT header

inline GenericHeader Metavision::make_DAT_header_map_with_geometry(int width, int height)

Convenience function to create a DAT header map to be added in the header using the camera geometry.

Parameters

width – Width of the camera sensor
height – Height of the camera sensor

Returns

The DAT header map

class GenericHeader

A utility class to hold and format headers information.

A header is composed of fields composed of key (string) / value (string) pairs

Public Types

using HeaderMap = std::map<std::string, std::string>: Alias for the internal map holding the header information.

Public Functions

GenericHeader(): Default constructor.

GenericHeader(std::istream &stream)

Builds the header map by parsing the input stream.

The stream internal is expected to point to the start of the header (if any) This method effectively places the stream cursor at the end of header. The position of the cursor remains unchanged if no header is actually present.

Parameters: stream – The input stream to parse a header from

GenericHeader(const HeaderMap &header_map)

Builds the header map using a copy of the input HeaderMap.

Parameters: header_map – The header map to use for initialization

bool empty() const

Returns if the header is empty.

Returns: True if the header is empty, false otherwise

void add_date(): Adds the current date and time to the header (in the format Y-m-d H:M:S).

Note

The date is updated at each call to this method

void remove_date(): Removes the date if there was any in the header.

std::string get_date() const

Gets the date and time at which the associated file was recorded.

Returns: The current date and time in string format if it is found, or an empty string otherwise.

void set_field(const std::string &key, const std::string &value)

Adds a new field in the header.

Parameters

key – The key of the field in the header
value – The value of the field

void remove_field(const std::string &key): Remove the input field (if exists)

std::string get_field(const std::string &key) const

Gets the value associated to the input key.

Returns: The value associated to the input key if it exists, or an empty string otherwise

const HeaderMap &get_header_map() const

Gets the HeaderMap holding the header information.

Returns: The header map

std::string to_string() const

Serializes the header map.

Returns: The header in a string format

Various

template<class T, bool acquire_shared_ptr = false> class ObjectPool

Class that creates a reusable pool of heap allocated objects.

The ObjectPool allocates objects that are returned to the pool upon destruction. acquire is used to allocate or re-use a previously allocated object instance. The object are made available through a std::unique_ptr or a std::shared_ptr according to the template acquire_shared_ptr. The smart pointers are given a custom deleter, which automatically adds the object back to the pool upon destruction.

Template Parameters

T – the type of object stored
acquire_shared_ptr – if true, the object are wrapped by a std::shared_ptr, otherwise a std::unique_ptr is returned instead

Public Types

using value_type = T : The type of the stored object.

using ptr_type = typename std::conditional<acquire_shared_ptr, std::shared_ptr<T>, std::unique_ptr<T, Deleter>>::type: The type of the smart pointer used to store the object.

Public Functions

inline ObjectPool(): Default constructor that builds an unbounded object pool with an initial number of objects allocated make_unbounded.

inline void add(std::unique_ptr<T> t)

Adds an object to the pool.

Parameters: t – A unique_ptr storing the object

template<typename ...Args> inline ptr_type acquire(Args&&... args)

Allocates or re-use a previously allocated object.

Parameters: args – Optional arguments to be passed when allocating the object
Returns: A unique or shared pointer to the allocated object

inline bool empty() const

Checks if the pool is empty.

Returns: true if the pool is empty, false if the pool contains object ready to be re-used

inline size_t size() const

Gets the number of objects in the pool.

Returns: The number of previously allocated and ready to-reuse objects in the pool

inline bool is_bounded() const

Checks the memory pool type i.e. bounded or unbounded.

Returns: true if the memory pool is bounded, false if it is unbounded

template<typename ...Args> inline size_t arrange(size_t size, Args&&... args)

Ensure that the pool contains ‘size’ available objects, ready to be acquired.

Note

Only works for unbounded pool

Parameters

size – The maximum number of objects to be available
args – Optional arguments to be used when allocating the object

Returns

the number of newly allocated object in the pool

Public Static Functions

static inline ObjectPool<T, acquire_shared_ptr> make_bounded(size_t num_initial_objects = 64)

Creates an object pool with limited number of objects that can be allocated.

There won’t be memory allocation upon call to acquire if all objects in the memory pool are already used.

Parameters: num_initial_objects – Number of objects initially allocated in the pool
Returns: An object pool with bounded memory

template<typename ...Args> static inline ObjectPool<T, acquire_shared_ptr> make_bounded(size_t num_initial_objects, Args&&... args)

Creates an object pool with limited number of objects that can be allocated.

There won’t be memory allocation upon call to acquire if all objects in the memory pool are already used.

Parameters

num_initial_objects – Number of objects initially allocated in the pool
args – The arguments forwarded to the object constructor during allocation

Returns

An object pool with bounded memory

template<typename ...Args> static inline ObjectPool<T, acquire_shared_ptr> make_unbounded(size_t num_initial_objects = 64)

Creates an object pool with expendable memory usage.

A pool with unbounded memory will allocate a new object when all objects in the pool are already used and acquire is called.

Parameters: num_initial_objects – Number of objects initially allocated in the pool
Returns: An object pool with unbounded memory

template<typename ...Args> static inline ObjectPool<T, acquire_shared_ptr> make_unbounded(size_t num_initial_objects, Args&&... args)

Creates an object pool with expendable memory usage.

A pool with unbounded memory will allocate a new object when all objects in the pool are already used and acquire is called.

Parameters

num_initial_objects – Number of objects initially allocated in the pool
args – The arguments forwarded to the object constructor during allocation

Returns

An object pool with unbounded memory

template<typename T> using Metavision::SharedObjectPool = ObjectPool<T, true>

Convenience alias to use a ObjectPool returning shared pointers.

Template Parameters: T – the type of object stored in the pool

typedef long long Metavision::timestamp: Type to represent time in microseconds.

struct SoftwareInfo

Stores information about the version of the software.

Public Types

enum class VersionSuffix

Supported version suffixes.

Values:

enumerator NONE

enumerator DEV

Public Functions

SoftwareInfo(int version_major, int version_minor, int version_patch, const std::string &version_suffix_string, const std::string &vcs_branch, const std::string &vcs_commit, const std::string &vcs_date)

Constructor.

Parameters

version_major – Major version number
version_minor – Minor version number
version_patch – Patch version number
version_suffix_string – Version suffix string
vcs_branch – VCS branch name
vcs_commit – VCS commit’s hash
vcs_date – VCS commit’s date

int get_version_major() const: Returns major version number.

int get_version_minor() const: Returns minor version number.

int get_version_patch() const: Returns patch version number.

std::string get_version_suffix() const: Returns version suffix string.

std::string get_version() const: Returns version as a string.

std::string get_vcs_branch() const: Returns version control software (vcs) branch.

std::string get_vcs_commit() const: Returns version control software (vcs) commit.

std::string get_vcs_date() const: Returns version control software (vcs) commit’s date.

Logging

enum class Metavision::LogLevel

Enumeration used to control the level of logged messages that are allowed to pass through.

Values:

enumerator Debug: This level is reserved for internal debugging purposes

Note

These messages are simply ignored when the code is compiled in Release even if setLogLevel is called with the Debug level

enumerator Trace: This level should be used for external debugging purposes.

enumerator Info: This level should be used for general information for the user.

enumerator Warning: This level should be used when a potential problem could occur that requires the user attention.

enumerator Error: This level should be used when a problem occurs, possibly leading to a failure of the application.

class LogOptions

Struct that defines the settings used for the logging behaviors.

Public Functions

LogOptions(LogLevel level = LogLevel::Info, std::ostream &stream = std::cerr, bool level_prefix_padding = false)

Construct a LogOptions object.

Parameters

level – The current level of logging
stream – The stream that will be used to issue the logs
level_prefix_padding – If enabled, the [level] prefix is padded with whitespace to a fixed length

LogOptions &setLevel(const LogLevel &level)

Sets the current level of logging.

Any message that has a higher or equal level will be enabled to pass through, and any message that has a lower level will be ignored

Note

By default, the level is LogLevel::Info

Note

It is also possible to set the current level of logging by setting the environment variable MV_LOG_LEVEL with one of the following (string) value : DEBUG, TRACE, INFO, WARNING, ERROR. If the environment variable is set, it will have precedence over the value set by this function.

Note

The environment variable MV_LOG_LEVEL is only read once at initialization of the logging utility, if the value of the environment variable is changed after, its value won’t be reflected unless you explicitly call resetLogLevelFromEnv

Note

In Android the environment variable for logging must be set by using one of the following commands:

works until next reboot, has higher priority to persist property
```
adb shell setprop debug.metavision.log.level <LEVEL>
```

root permissions requested, works permanently

adb shell setprop persist.metavision.log.level <LEVEL>

Note

To reset a property in Android environment use the following command:

adb shell setprop \<property_name\> \"\"

Parameters: level – The minimum level of messages allowed to pass through
Returns: The current LogOptions object

LogLevel getLevel() const

Gets the current level of logging.

See also

setLevel

Returns: The current level of logging

LogOptions &setStream(std::ostream &stream)

Sets the current stream in which all messages are logged.

Note

By default, the stream is std::cerr.

Note

If you want to log in a file, you can pass your own file stream, but you have to manage its life time.

Note

It is also possible to set the current stream to point to a file by setting the environment variable MV_LOG_FILE with the path corresponding to the desired log file. If the environment variable is set, it will have precedence over the value set by this function.

Note

The environment variable MV_LOG_FILE is only read once at initialization of the logging utility, if the value of the environment variable is changed after, its value won’t be reflected unless you explicitly call resetLogStreamFromEnv

Parameters: stream – The stream in which all messages will be written
Returns: The current LogOptions object

std::ostream &getStream() const

Gets the current stream in which all messages are logged.

Returns: The current stream in which all messages are logged

LogOptions &setLevelPrefixPadding(bool is_padded)

Define if the [level] prefix should be padded with white spaces.

Returns: The current LogOptions object

bool isLevelPrefixPadding() const

Is the “[level]” prefix padded with white spaces.

Returns: a boolean that defines if the option is enabled

void Metavision::setLogOptions(LogOptions opts)

define global options to tweak logging behavior

See also

getLogOptions to retrieve current Log options

Parameters: opts – The LogOptions to be globally set

void Metavision::resetLogLevelFromEnv()

Resets the current level of logging value read from the environment variable MV_LOG_LEVEL.

See also

LogOptions::setLevel and getLogOptions

void Metavision::resetLogStreamFromEnv(): Resets the current logging stream read from the environment variable MV_LOG_FILE.

LogOptions Metavision::getLogOptions()

retrieve global logging options

See also

setLogOptions to set Log options

Returns: a copy of the global LogOptions object

template<LogLevel level> class LoggingOperation

Base class for any logging operation.

This is a base class easing the use of the logging system This class uses classical C++ techniques to easily provide modifiers to automatically add spaces between messages tokens or an end of line character when the operation is finished It is much more convenient to use one of the MV_LOG_DEBUG, MV_LOG_TRACE, MV_LOG_INFO, MV_LOG_WARNING or MV_LOG_ERROR functions to return an instance of this class

Template Parameters: level – The level of this logging operation

Public Functions

LoggingOperation(const LogOptions &opts = LogOptions(), const std::string &prefixFmt = std::string(), const std::filesystem::path &file = std::string(), int line = 0, const std::string &function = std::string())

Constructor.

Construct a LoggingOperation that will write in the stream message tokens, prefixed by the formatted prefixFmt

The prefixFmt can be any fixed string or a format string with the following known replacement tokens :

<LEVEL> : the level of the logging operation in upper case
<Level> : the level of the logging operation in camel case
<FILE> : the basename of the file where the logging operation is created
<LINE> : the line where the logging operation is created
<FUNCTION> : the function where the logging operation is created
<DATETIME:strftime_fmt> : the date and time formatted with a format as specified by std::strftime function (e.g. dHm), note that the formatted string can not exceed 1024 characters.

Note

The replacement in the prefix format only occurs once, i.e. each token is searched only once and not replaced multiple times.

Parameters

opts – The object that defines the general configuration for the logging mechanisms
prefixFmt – The prefix format to display
file – The file from which the logging operation was created
line – The line where the logging operation was created
function – The function in which the logging operation was created

LoggingOperation(const LoggingOperation&) = delete: Copy constructor A logging operation cannot be copy constructed.

LoggingOperation(LoggingOperation &&op)

Move constructor A logging operation can be move constructed.

Parameters: op – The logging operation to be move constructed from

LoggingOperation &operator=(const LoggingOperation&) = delete: Copy assignment A logging operation cannot be copy assigned.

LoggingOperation &operator=(LoggingOperation &&op)

Move assignment A logging operation can be move assigned.

Parameters: op – The logging operation to be move assigned from
Returns: The modified logging operation

~LoggingOperation(): Destructor.

void enableSpaceBetweenTokens(): Enables automatically adding spaces between message tokens.

Note

This feature is enabled by default

void disableSpaceBetweenTokens(): Disables automatically adding spaces between message tokens.

void enableEndOfLineAtDestruction(): Enables automatically adding an end of line token when this operation is destroyed.

Note

This feature is enabled by default

void disableEndOfLineAtDestruction(): Disables automatically adding an end of line token when this operation is destroyed.

std::filesystem::path file() const: Returns the name of the file associated to this logging operation.

int line() const: Returns the line associated to this logging operation.

std::string function() const: Returns the function associated to this logging operation.

std::string prefix() const: Returns the prefix associated to this logging operation.

template<typename T> void log(const T &t)

Logs the corresponding value.

Template Parameters: T – Type of the value to be logged
Parameters: t – Value to be logged

void log(bool val): Logs the corresponding value This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T> void log(const std::vector<T> &v): Logs the corresponding value This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void apply(std::ostream &(*manip)(std::ostream&))

Applies a stream manipulator.

Parameters: manip – Stream manipulator

Public Static Attributes

static constexpr LogLevel Level = level : The level of this operation.

MV_LOG_DEBUG(prefixFmt...)

Returns a logging operation of DEBUG level.

Convenience function to return a logging operation of DEBUG level using the current logging stream, an optional prefix format prefixFmt and automatically adding an end of line token at the end of the logging operation

Parameters

prefixFmt – (Optional) a format string that will be be output as the first message token

Returns

A logging operation of DEBUG level

MV_LOG_TRACE(prefixFmt...)

Returns a logging operation of TRACE level.

Convenience macro to return a logging operation of TRACE level using the current logging stream, an optional prefix format prefixFmt and automatically adding an end of line token at the end of the logging operation

Parameters

prefixFmt – (Optional) a format string that will be be output as the first message token

Returns

A logging operation of TRACE level

MV_LOG_INFO(prefixFmt...)

Returns a logging operation of INFO level.

Convenience function to return a logging operation of INFO level using the current logging stream, an optional prefix format prefixFmt and automatically adding an end of line token at the end of the logging operation

Parameters

prefixFmt – (Optional) a format string that will be be output as the first message token

Returns

A logging operation of INFO level

MV_LOG_WARNING(prefixFmt...)

Returns a logging operation of WARNING level.

Convenience function to return a logging operation of WARNING level using the current logging stream, an optional prefix format prefixFmt and automatically adding an end of line token at the end of the logging operation

Parameters

prefixFmt – (Optional) a format string that will be be output as the first message token

Returns

A logging operation of WARNING level

MV_LOG_ERROR(prefixFmt...)

Returns a logging operation of ERROR level.

Convenience function to return a logging operation of ERROR level using the current logging stream, an optional prefix format prefixFmt and automatically adding an end of line token at the end of the logging operation

Parameters

prefixFmt – (Optional) a format string that will be be output as the first message token

Returns

A logging operation of ERROR level

namespace Log

Functions

template<LogLevel Level> LoggingOperation<Level> &space(LoggingOperation<Level> &op)

Stream manipulator enabling the automatic addition of spaces between message tokens.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&space(LoggingOperation<Level> &&op)

Stream manipulator enabling the automatic addition of spaces between message tokens.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &no_space(LoggingOperation<Level> &op)

Stream manipulator disabling the automatic addition of spaces between message tokens.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&no_space(LoggingOperation<Level> &&op)

Stream manipulator disabling the automatic addition of spaces between message tokens.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &endline(LoggingOperation<Level> &op)

Stream manipulator enabling the automatic addition of an end of line token at the end of the operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&endline(LoggingOperation<Level> &&op)

Stream manipulator enabling the automatic addition of an end of line token at the end of the operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &no_endline(LoggingOperation<Level> &op)

Stream manipulator disabling the automatic addition of an end of line token at the end of the operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&no_endline(LoggingOperation<Level> &&op)

Stream manipulator disabling the automatic addition of an end of line token at the end of the operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &function(LoggingOperation<Level> &op)

Stream manipulator that outputs the function name associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&function(LoggingOperation<Level> &&op)

Stream manipulator that outputs the function name associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &file(LoggingOperation<Level> &op)

Stream manipulator that outputs the file name associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&file(LoggingOperation<Level> &&op)

Stream manipulator that outputs the file name associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &line(LoggingOperation<Level> &op)

Stream manipulator that outputs the line associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&line(LoggingOperation<Level> &&op)

Stream manipulator that outputs the line associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &prefix(LoggingOperation<Level> &op)

Stream manipulator that outputs the prefix associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation

template<LogLevel Level> LoggingOperation<Level> &&prefix(LoggingOperation<Level> &&op)

Stream manipulator that outputs the prefix associated to the logging operation.

Template Parameters: Level – The level of the logging operation
Parameters: op – The logging operation modified by this modifier
Returns: The modified logging operation