SDK Base Utils
Header helpers classes and functions
-
template<typename
EventType
>
voidMetavision
::
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::stringMetavision
::
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
Metavision
::
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
-
using
Various
-
template<class
T
, boolacquire_shared_ptr
= false>
classMetavision
::
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 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_typeacquire
(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_tarrange
(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
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
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
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
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
Metavision
::
SoftwareInfo
Stores information about the version of the software.
Public Types
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.
-
enumerator
-
class
Metavision
::
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
- 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
-
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
>
classMetavision
::
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
See also
MV_LOG_DEBUG, MV_LOG_TRACE, MV_LOG_INFO, MV_LOG_WARNING, MV_LOG_ERROR
- Template Parameters
level – The level of this logging operation
Public Functions
-
LoggingOperation
(const LogOptions &opts = LogOptions(), const std::string &prefixFmt = std::string(), const std::string &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 formattedprefixFmt
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::string
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
>
voidlog
(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
>
voidlog
(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
-
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
Metavision
::
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
-
template<LogLevel