SDK Driver Camera Features

class Metavision::AntiFlickerModule

Facility class to handle anti-flicker configuration on the hardware side.

Public Functions

AntiFlickerModule(I_AntiFlickerModule *afk): Constructor.

~AntiFlickerModule(): Destructor.

void enable(bool b)

Toggles anti-flicker activation.

Note

When anti-flicker is inactive, all the events generated by the sensor are transmitted. Potential bandwidth limitation might occur.

Parameters: b – Desired state. b = true means anti-flicker active, and b = false means anti-flicker inactive.

bool is_enabled(): Gives the anti-flicker filter state.

void set_frequency_band(uint32_t min_freq, uint32_t max_freq)

Sets anti-flicker parameters.

Defines the frequency band to be kept or removed in the range [50 - 500] Hz

Parameters

min_freq – Lower frequency of the band (in Hz)
max_freq – Higher frequency of the band (in Hz)

Throws

exception – if frequencies are outside of the range [min_supported_freq, max_supported_freq] Hz

void set_filtering_mode(I_AntiFlickerModule::AntiFlickerMode mode)

Sets the anti-flicker filtering mode.

Parameters: mode – Anti-flicker mode

I_AntiFlickerModule *get_facility() const: Gets corresponding facility in HAL library.

class Metavision::Biases

Facility class to handle biases.

Public Functions

Biases(I_LL_Biases *i_ll_biases): Constructor.

~Biases(): Destructor.

void set_from_file(const std::string &biases_filename)

Sets camera biases from a bias file at biases_filename.

Throws: CameraException – in case of failure. This could happen for example if given path does not exists.
Parameters: biases_filename – Path to the bias file used to configure the camera

void save_to_file(const std::string &dest_file) const

Save the current biases into a file.

Parameters: dest_file – the destination file

I_LL_Biases *get_facility() const: Get corresponding facility in HAL library.

enum Metavision::CameraErrorCode::Enum

Values:

enumerator CameraError: Base Metavision SDK Driver camera error.

enumerator FailedInitialization: Camera failed initialization.

enumerator CameraNotFound: Failed initialization due to a camera not found.

enumerator InternalInitializationError: Metavision SDK Driver Internal Initialization problem.

enumerator RuntimeError: Camera runtime errors.

enumerator BiasesError: Fails to set biases.

enumerator CameraNotInitialized: Error due to a non initialized camera.

enumerator InvalidRawfile: Invalid RAW file.

enumerator DataTransferFailed: Error while retrieving data from source.

enumerator RoiError: Fails to set ROI.

enumerator UnsupportedFeature: Error while trying to use a feature unsupported by the camera.

enumerator FirmwareIsNotUpToDate: Device firmware is not up to date.

enumerator DeprecatedFeature: Error while trying to use a deprecated feature.

enumerator InvalidArgument: Errors related to invalid arguments.

enumerator FileDoesNotExist: File does not exist.

enumerator NotARegularFile: File is not a regular file.

enumerator WrongExtension: File extension is not the one expected.

enumerator CouldNotOpenFile: Could not open file.

class Metavision::CameraException : public std::system_error

Class for all exceptions thrown by Metavision SDK Driver.

Public Functions

CameraException(CameraErrorCodeType e)

Creates an exception of type e with default error message.

See also

CameraErrorCode

Parameters: e – Camera error code

CameraException(CameraErrorCodeType e, std::string additional_info)

Creates an exception of type e with an error description in additional_info.

See also

CameraErrorCode

Parameters

e – Camera error code
additional_info – error description

class Metavision::CameraGeneration

Facility class to handle camera generation.

Public Functions

virtual ~CameraGeneration()

Destructor.

Deletes a CameraGeneration class instance.

short version_major() const: Returns the major version of the camera’s generation.

short version_minor() const: Returns the minor version of the camera’s generation.

bool operator==(const CameraGeneration &c) const: overrides “equal to” operator

bool operator!=(const CameraGeneration &c) const: overrides “not equal to” operator

bool operator<(const CameraGeneration &c) const: overrides “less than” operator

bool operator<=(const CameraGeneration &c) const: overrides “less than or equal to” operator

bool operator>(const CameraGeneration &c) const: overrides “greater than” operator

bool operator>=(const CameraGeneration &c) const: overrides “greater than or equal to” operator

Private &get_pimpl(): For internal use.

class Metavision::CD

Facility class to handle CD events.

Public Functions

virtual ~CD()

Destructor.

Deletes a CD class instance.

CallbackId add_callback(const EventsCDCallback &cb)

Subscribes to CD events.

Registers a callback that will be called each time a buffer of eventCD has been decoded.

See also

EventsCDCallback

Parameters: cb – Callback to call each time a buffer of eventCD has been decoded
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::DATEventFileReader : public Metavision::EventFileReader 

Public Functions

virtual bool seekable() const override

Queries whether the event file supports seeking.

Returns: true if seek is supported, false otherwise

class Metavision::ERCCounter

Facility class to handle ERCCounter events.

Public Functions

virtual ~ERCCounter()

Destructor.

Deletes a ERCCounter class instance.

CallbackId add_callback(const EventsERCCounterCallback &cb)

Subscribes to CDCount events.

Registers a callback that will be called each time a buffer of EventERCCounter has been decoded.

See also

EventsERCCounterCallback

Parameters: cb – Callback to call each time a buffer of EventERCCounter has been decoded
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::ErcModule

Facility class for Event Rate Controller (ERC) commands.

Public Functions

ErcModule(I_ErcModule *erc): Constructor.

~ErcModule(): Destructor.

bool enable(bool b)

Toggles ERC activation.

Note

When ERC is inactive, all the events generated by the sensor are transmitted. Potential bandwidth limitation might occur.

Parameters: b – Desired state. b = true means ERC active, and b = false means ERC inactive.
Returns: true on success

bool is_enabled()

Returns ERC activation state.

Returns: The ERC state

void set_cd_event_rate(uint32_t events_per_sec)

Sets the target CD event rate of the ERC.

Note

Event rate is computed by ERC block as the number of events generated by the sensor divided by the count period.

Parameters: events_per_sec – Event rate expressed in events per second

uint32_t get_cd_event_rate()

Gets the CD event rate set point of the ERC.

Note

See set_cd_event_rate to define the event rate target.

Returns: The event rate expressed in events per second

I_ErcModule *get_facility() const: Gets corresponding facility in HAL library.

class Metavision::EventTrailFilterModule

Facility class to handle event trail filter module configuration on the hardware side.

The types of event trail filter are Spatio-Temporal Contrast (STC) and Trail.

Public Functions

EventTrailFilterModule(I_EventTrailFilterModule *noise_filter): Constructor.

~EventTrailFilterModule(): Destructor.

std::set<I_EventTrailFilterModule::Type> get_available_types() const

Returns the set of available types of filters.

Returns: set of available types of filters

bool enable(bool state)

Enables the EventTrailFilterModule. Filtering type and threshold should be set before hand.

Parameters: state – If true, enables the module. If false, disables it
Returns: true on success

I_EventTrailFilterModule *get_facility() const: Gets corresponding facility in HAL library.

class Metavision::EventFileReader

Abstract class used for reading event based file.

Subclassed by Metavision::DATEventFileReader, Metavision::HDF5EventFileReader, Metavision::RAWEventFileReader

Public Types

template<typename EventType> using EventsBufferReadCallback = std::function<void(const EventType*, const EventType*)>

Alias for the “reading callback” used when a buffer of events has been read.

The callback will be called with two pointers which represent the range of events that were just read

Template Parameters: EventType – Type of event read

template<typename EventFrameType> using EventFrameReadCallback = std::function<void(const EventFrameType&)>

Alias for the “reading callback” used when an event frame has been read.

The callback will be called with a reference to the event frame that was read

Template Parameters: EventFrameType – Type of event frame read

using SeekCompletionCallback = std::function<void(timestamp)>

Alias for the “seeking callback” used when a seek operation successfully completed.

The callback will be called with a timestamp representing the actual timestamp at which the reader has seeked to

Public Functions

EventFileReader(const std::string &path)

Builds an EventFileReader.

Parameters: path – Path to the event based file to read

virtual ~EventFileReader(): Destructs an EventFileReader.

const std::string &get_path() const

Gets the path of the event based file.

Returns: Path of the file

size_t add_read_callback(const EventsBufferReadCallback<EventCD> &cb)

Adds a “reading callback” called when a buffer of events has been read.

Parameters: cb – Callback to be called
Returns: Id of the added callback, see remove_callback

size_t add_read_callback(const EventsBufferReadCallback<EventExtTrigger> &cb): Adds a “reading callback” called when a buffer of events has been read This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

size_t add_read_callback(const EventsBufferReadCallback<EventERCCounter> &cb): Adds a “reading callback” called when a buffer of events has been read This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

size_t add_read_callback(const EventFrameReadCallback<RawEventFrameHisto> &cb): Adds a “reading callback” called when a histogram has been read This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

size_t add_read_callback(const EventFrameReadCallback<RawEventFrameDiff> &cb): Adds a “reading callback” called when a diff histogram has been read This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool has_read_callbacks() const

Checks if “reading callbacks” have been added.

Returns: true if callbacks have been added, false otherwise

bool read()

Reads block of events from the input stream.

Returns: true if some events could be read, false otherwise

virtual bool seekable() const = 0

Queries whether the event file supports seeking.

Returns: true if seek is supported, false otherwise

size_t add_seek_callback(const SeekCompletionCallback &cb)

Adds a “seeking callback” called when a seek operation successfully completed.

Parameters: cb – Callback to be called
Returns: Id of the added callback, see remove_callback

bool has_seek_callbacks() const

Checks if “seeking callbacks” have been added.

Returns: true if callbacks have been added, false otherwise

bool get_seek_range(timestamp &min_t, timestamp &max_t) const

Gets the allowed seek range timestamps.

Parameters

min_t – Reference to the minimum timestamp to seek to
max_t – Reference to the maximum timestamp to seek to

Returns

true if the seek range could be determined, false otherwise

timestamp get_duration() const

Gets the duration of the file.

Returns: Duration or -1 if not available

bool seek(timestamp t)

Seeks to a specified timestamp.

Parameters: t – Timestamp to seek to
Returns: true if the seek was successful, false otherwise

void remove_callback(size_t id)

Removes one callback.

Parameters: id – Id of the callback to remove (see add_read_callback, add_seek_callback)

std::unordered_map<std::string, std::string> get_metadata_map() const

Gets the metadata map of the file.

Returns: Metadata, if available

Private &get_pimpl(): For internal use.

class Metavision::EventFileWriter

Abstract class used for reading event based file.

Subclassed by Metavision::HDF5EventFileWriter, Metavision::RAWEventFileWriter

Public Functions

EventFileWriter(const std::string &path = std::string())

Builds an EventFileWriter.

Parameters: path – Path to the event based file to read

virtual ~EventFileWriter(): Destructs an EventFileWriter.

void open(const std::string &path)

Open the writer with specified path.

Parameters: path – Path to the file to write

void close(): Close the writer.

bool is_open() const

Check that the writer is currently opened and ready to write data.

Returns: true if the writer is opened and ready, false otherwise

void flush()

Try to flush any data not yet written to disk.

The underlying implementation will do its best to flush any data not yet written but it’s not guaranteed that all data will be written after this call (a library or the OS might prevent completely flushing that data at this point). If no more data will be added, closing the writer is the only way to make sure the data is fully written to disk.

const std::string &get_path() const

Gets the path of the event based file.

Returns: Path of the file

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

Adds metadata to the file.

Warning

Calling this function after some data has been added may throw an exception in some implementation

Parameters

key – Metatadata key to be added
value – Metadata value to be added

void add_metadata_map_from_camera(const Camera &camera)

Adds metadata to the file from a Camera instance.

Warning

Calling this function after some data has been added may throw an exception in some implementation

Parameters: camera – Camera instance to build metadata from

void remove_metadata(const std::string &key)

Removes metadata from the file.

Parameters: key – Metadata key to be removed

bool add_events(const EventCD *begin, const EventCD *end)

Adds a buffer of events to be written.

Warning

The events must be chronologically ordered inside the buffer, and in between calls. An exception will be thrown if the first event of the added buffer is older than the timestamp of the last event of the last added buffer.

Parameters

begin – Pointer to the beginning of the buffer
end – Pointer to the end of the buffer

bool add_events(const EventExtTrigger *begin, const EventExtTrigger *end): Adds a buffer of events to be written This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Private &get_pimpl(): For internal use.

class Metavision::ExtTrigger

Facility class to handle External Triggers events.

Public Functions

virtual ~ExtTrigger()

Destructor.

Deletes an ExtTrigger class instance.

CallbackId add_callback(const EventsExtTriggerCallback &cb)

Subscribes to external trigger events.

Registers a callback that will be called each time a buffer of external trigger event has been decoded.

See also

EventsExtTriggerCallback

Parameters: cb – Callback to call each time a buffer of ext trigger event has been decoded
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::FileConfigHints

Class represented by a map of string key/value pair, used to control how a file is read by the Camera class.

Note

Some keys can be ignored when not applicable to the file format

Public Functions

inline explicit FileConfigHints()

Constructor.

By default, if applicable, the file will be read using a maximum memory footprint of 12Mo, with real time playback speed and time shifting enabled

inline bool real_time_playback() const

Gets the real-time playback status.

Returns: true if enabled, false otherwise

inline FileConfigHints &real_time_playback(bool enabled)

Named constructor for the real time playback status.

Parameters: enabled – true if the setting should be enabled, false otherwise
Returns: FileConfigHints& Reference to the modified config

inline bool time_shift() const

Gets the timeshift status.

Returns: true if enabled, false otherwise

inline FileConfigHints &time_shift(bool enabled)

Named constructor for the time shift status.

Parameters: enabled – true if the setting should be enabled, false otherwise
Returns: FileConfigHints& Reference to the modified config

inline size_t max_memory() const

Gets the maximum memory used (if applicable) setting.

Returns: Maximum memory used

inline FileConfigHints &max_memory(std::size_t max_memory)

Named constructor for the max memory setting.

Parameters: max_memory – Maximum memory that should be used when reading the file (if applicable)
Returns: FileConfigHints& Reference to the modified config

inline size_t max_read_per_op() const

Gets the maximum read size (if applicable) setting.

Returns: Maximum read size in bytes

inline FileConfigHints &max_read_per_op(std::size_t max_read_per_op)

Named constructor for the max read size per read operation.

Parameters: max_read_per_op – Maximum size of data read per read operation
Returns: FileConfigHints& Reference to the modified config

template<typename T> inline void set(const std::string &key, const T &value)

Sets a value for a named key in the config dictionary.

Parameters

key – Key of the config
value – Value of the config

inline void set(const std::string &key, const std::string &value): Sets a value for a named key in the config dictionary 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> inline T get(const std::string &key, const T &def = T()) const

Gets the (typed) value for a named key in the config dictionary if it exists and can be extracted from the corresponding value safely or the provided default value.

Template Parameters

T – type of the value to return as

Parameters

key – Name of the config key
def – Default value if the config key is not found

Returns

Value of the config

class Metavision::FrameDiff

Facility class to handle RawEventFrameDiff.

Public Functions

virtual ~FrameDiff()

Destructor.

Deletes a FrameDiff class instance.

CallbackId add_callback(const RawEventFrameDiffCallback &cb)

Subscribes to FrameDiff events.

Registers a callback that will be called each time a RawEventFrameDiff has been decoded.

See also

RawEventFrameDiffCallback

Parameters: cb – Callback to call each time a RawEventFrameDiff has been decoded
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::FrameHisto

Facility class to handle RawEventFrameHisto.

Public Functions

virtual ~FrameHisto()

Destructor.

Deletes a FrameHisto class instance.

CallbackId add_callback(const RawEventFrameHistoCallback &cb)

Subscribes to Histogram events.

Registers a callback that will be called each time a RawEventFrameHisto has been decoded.

See also

RawEventFrameHistoCallback

Parameters: cb – Callback to call each time a RawEventFrameHisto has been decoded
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::Geometry

Facility class to get the geometry of a Device.

Public Functions

Geometry(I_Geometry *geom): Constructor.

~Geometry(): Destructor.

int width() const: Width of the sensor.

int height() const: Height of the sensor.

I_Geometry *get_facility() const: Gets corresponding facility in HAL library.

class Metavision::HDF5EventFileReader : public Metavision::EventFileReader 

Public Functions

virtual bool seekable() const override

Queries whether the event file supports seeking.

Returns: true if seek is supported, false otherwise

class HDF5EventFileWriter : public Metavision::EventFileWriter 

class Metavision::OfflineStreamingControl

Facility class to control offline streaming features.

Public Functions

bool is_ready() const

Checks if all features of the offline streaming control are ready.

Note

You should make sure this function returns true before making any other calls

Returns: true if all features are ready, false otherwise

bool seek(Metavision::timestamp ts)

Seek to a specified timestamp.

Parameters: ts – Timestamp to seek to
Returns: True if seeking succeeded, false otherwise

Metavision::timestamp get_seek_start_time() const

Gets the first reachable timestamp that can be seeked to.

Returns: Metavision::timestamp First timestamp to seek to

Metavision::timestamp get_seek_end_time() const

Gets the last reachable timestamp that can be seeked to.

Returns: Metavision::timestamp Last timestamp to seek to

Metavision::timestamp get_duration() const

Gets the duration of the recording.

Returns: Metavision::timestamp Duration of the recording

Private &get_pimpl(): For internal use.

class Metavision::RawData

Facility class to handle RAW data.

Public Functions

virtual ~RawData()

Destructor.

Deletes a RawData class instance.

CallbackId add_callback(const RawDataCallback &cb)

Subscribes to RAW data callback.

Registers a callback that will be called each time a buffer of RAW data has been received.

See also

RawDataCallback

Note

This callback is always called after all events callbacks have been called, with the raw data buffer used to decode the events that are passed to the events callback.

Parameters: cb – Callback to call each time a buffer of RAW data has been received
Returns: ID of the added callback

bool remove_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Private &get_pimpl(): For internal use.

class Metavision::RAWEventFileReader : public Metavision::EventFileReader 

Public Functions

virtual bool seekable() const override

Queries whether the event file supports seeking.

Returns: true if seek is supported, false otherwise

class RAWEventFileWriter : public Metavision::EventFileWriter 

class Metavision::Roi

Facility class to handle a Region Of Interest (ROI)

Public Functions

Roi(I_ROI *roi): Constructor.

~Roi(): Destructor.

void set(Window roi)

Sets an hardware ROI on the sensor.

When an ROI is set successfully, no events will be output by the sensor outside of this ROI. Since this is a hardware ROI, there is no processing added to filter the events. Setting an ROI will unset any previously set ROI.

Parameters: roi – The ROI to set on the sensor

void set(const std::vector<bool> &cols, const std::vector<bool> &rows)

Sets multiple ROIs from row and column binary maps.

The binary maps (std::vector<bool>) arguments must have the sensor’s dimension

Warning

For a pixel to be enabled, it must be enabled on both its row and column

Parameters

cols – Vector of boolean of size sensor’s width representing the binary map of the columns to enable
rows – Vector of boolean of size sensor’s height representing the binary map of the rows to enable

Throws

an – exception if the size of either cols or rows arguments do not match the sensor geometry

void set(const std::vector<Window> &windows)

Sets multiple hardware ROI from Roi::Window vector.

Parameters: windows – A vector of ROIs to set
Throws: an – exception if the size of the vector is higher than the maximum supported number of windows (see I_ROI::get_max_supported_windows_count)

void unset(): Unsets any set ROI on the sensor.

I_ROI *get_facility() const: Gets corresponding facility in HAL library.

struct Window

Basic struct used to set a hardware region of interest (ROI) - a window - on the sensor.

This struct defines an ROI of with*height pixels going from [x, y] to [x + width -1, y + height -1]

Public Members

int x = 0: ROI top left column coordinate of the ROI.

int y = 0: ROI top left row coordinate of the ROI.

int width = 0: Width of the ROI.

int height = 0: Height of the ROI.

class Metavision::TriggerOut

Trigger out signal handler class.

The trigger out is a signal generator. Its purpose is to synchronize two (or more) devices.

The configurable signal through this interface is a periodic 1 microsecond pulse.

Public Functions

TriggerOut(I_TriggerOut *i_trigger_out): Constructor.

virtual ~TriggerOut(): Destructor.

void set_pulse_period(uint32_t period_us)

Sets the trigger out signal pulse period.

By default, the system has a period of 100 us meaning that, when enabled, a pulse of 1 microsecond will occur every 100us.

Parameters: period_us – the signal period in microseconds.

void set_duty_cycle(double period_ratio)

Sets the duty cycle of the trigger out signal i.e. the pulse duration.

The duty cycle represents the part of the signal during which its value is 1 (0 otherwise). Duty cycle represents the quantity pulse_width_us/period_us and thus must be in the range [0, 1]. The period is set with set_pulse_period.

Setting a duty cycle of 0.5 (50%) means that the value of the signal is 1 during the first half of each period, and 0 during the second half.

Parameters: period_ratio – Ratio representing pulse_width_us/period_us which must be in the range [0, 1] (value is clamped in this range otherwise)

void enable(): Enables the trigger out signal.

void disable(): Disables the trigger out signal.

I_TriggerOut *get_facility() const: Get corresponding facility in HAL library.