HAL Python bindings API

The Device object of metavision_hal allows allows a user to access the camera features by requesting access to a facility using one of the call listed below. Not that facilities availability depends on the device type (camera or RAW file) and on the Prophesee sensor generation.

Facility Name

Method

Camera (sensor)

availability

RAW File

availability

Anti-flicker

get_i_antiflicker_module()

Gen4.1 only

No

General Decoder

get_i_decoder()

Yes

Yes

Device Control

get_i_device_control()

Yes

No

Event Rate Control (ERC)

get_i_erc()

Gen4 and Gen4.1

No

CD Event Decoder

get_i_event_cd_decoder()

Yes

Yes

Ext. Trigger Decoder

get_i_event_ext_trigger_decoder()

Yes

Yes

Event Rate Noise Filter

get_i_event_rate()

Gen3.1 only

No

Events Stream

get_i_events_stream()

Yes

Yes

Geometry

get_i_geometry()

Yes

Yes

HAL Software Info

get_i_hal_software_info()

Yes

Yes

Hardware Identification

get_i_hw_identification()

Yes

Yes

Hardware Register

get_i_hw_register()

Yes

No

Biases

get_i_ll_biases()

Yes

No

Monitoring

get_i_monitoring()

Yes

No

Noise Filter (STC, Trail)

get_i_noisefilter_module()

Gen4.1 only

No

Plugin Software Info

get_i_plugin_software_info()

Yes

Yes

ROI

get_i_roi()

Yes

No

Trigger In

get_i_trigger_in()

Yes

No

Trigger Out

get_i_trigger_out()

Yes

No

Those methods can be used with an SDK Core EventsIterator that can be constructed from a HAL device. Here is an example where we create an event iterator on a camera on which we disabled ERC:

from metavision_core.event_io.raw_reader import initiate_device
from metavision_core.event_io import EventsIterator

# first we create a HAL device
device = initiate_device(path=args.input_path)
if device.get_i_erc():  # we test if the facility is available on this device before using it
    device.get_i_erc().enable(False)

# now we can create an EventsIterator from the Device
mv_iterator = EventsIterator.from_device(device=device)
for evs in mv_iterator:
    any_algo.process_events(evs)

# Note that it is not recommended to leave a device in the global scope. So either create the HAL device in a
# function or delete it explicitly afterwards. Otherwise, it could result in an undefined behaviour.
del device
class metavision_hal.DeviceConfig

Device’s configuration’s options.

property event_format

Switch the event format if supported.

class metavision_hal.DeviceDiscovery

Discovery of connected device.

static list()List[str]

Lists serial numbers of available sources, including remote cameras.

static list_available_sources()List[Metavision::CameraDescription]

Lists available sources, including remote cameras.

static list_available_sources_local()List[Metavision::CameraDescription]

Lists only local available sources.

static list_available_sources_remote()List[Metavision::CameraDescription]

Lists only remote available sources.

static list_local()List[str]

Lists serial numbers of local available sources.

static list_remote()List[str]

Lists serial numbers of remote available sources.

static open(*args, **kwargs)

Overloaded function.

  1. open(serial: str) -> Metavision::Device

Builds a new Device.

serial

Serial number of the camera to open. If it is an empty string, the first available camera will be opened

return

A new Device

  1. open(serial: str, config: Metavision::DeviceConfig) -> Metavision::Device

Builds a new Device.

serial

Serial number of the camera to open. If it is an empty string, the first available camera will be opened

config

Configuration used to build the camera

return

A new Device

static open_raw_file(*args, **kwargs)

Overloaded function.

  1. open_raw_file(raw_file: str) -> Metavision::Device

Builds a new Device from file.

raw_file

Path to the file to open

return

A new Device

  1. open_raw_file(raw_file: str, file_config: Metavision::RawFileConfig) -> Metavision::Device

Builds a new Device from file.

raw_file

Path to the file to open

file_config

Configuration describing how to read the file (see RawFileConfig)

return

A new Device

class metavision_hal.DeviceRoi

Defines a simple rectangular region.

to_string(self: metavision_hal.DeviceRoi)str

Returns the ROI as a string.

return

Human readable string representation of an ROI

class metavision_hal.I_AntiFlickerModule

Anti-flicker module.

Note

This feature is available only on Gen4.1 sensors

disable(self: metavision_hal.I_AntiFlickerModule)None

Disables the anti-flicker filter.

enable(self: metavision_hal.I_AntiFlickerModule)None

Enables the anti-flicker filter.

set_frequency(self: metavision_hal.I_AntiFlickerModule, frequency_center: int, bandwidth: int, stop: bool)None

Sets anti-flicker parameters.

Defines the frequency band to be kept or removed: [frequency_center - bandwidth/2, frequency_center + bandwidth/2] This frequency range should be in the range [50 - 500] Hz

frequency_center

Center of the frequency band (in Hz)

bandwidth

Range of frequencies around the frequency_center (in Hz)

stop

If true, band-stop (by default); if false, band-pass

note

band-stop removes all frequencies between min and max. band-pass removes all events outside of the band sequence defined :runtime: exception if frequency band is not in the range [50 - 500] Hz

set_frequency_band(self: metavision_hal.I_AntiFlickerModule, min_freq: int, max_freq: int, stop: bool)None

Sets anti-flicker parameters.

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

min_freq

Lower frequency of the band (in Hz)

max_freq

Higher frequency of the band (in Hz)

stop

If true, band-stop; if false, band-pass

note

band-stop removes all frequencies between min and max. band-pass removes all events outside of the band sequence defined :runtime: exception if frequencies are outside of the range [50 - 500] Hz

class metavision_hal.I_Decoder

Interface for decoding events.

This class is meant to receive raw data from the camera, and dispatch parts of the buffer to instances of I_EventDecoder for specific event types.

add_time_callback(self: metavision_hal.I_Decoder, cb: object)None

Adds a function that will be called from time to time, giving current timestamp.

cb

Callback to add

return

ID of the added callback

note

This method is not thread safe. You should add/remove the various callback before starting the streaming

note

It’s not allowed to add/remove a callback from the callback itself

decode(self: metavision_hal.I_Decoder, RawData: numpy.ndarray[numpy.uint8])None

Decodes raw data. Identifies the events in the buffer and dispatches it to the instance Event Decoder corresponding to each event type

Parameters

RawData – Numpy array of Events

get_last_timestamp(self: metavision_hal.I_Decoder)int

Gets the timestamp of the last event.

return

Timestamp of the last event

remove_callback(self: metavision_hal.I_Decoder, callback_id: int)bool

Removes a previously registered time callback.

callback_id

Callback ID

return

true if the callback has been unregistered correctly, false otherwise.

note

This method is not thread safe. You should add/remove the various callback before starting the streaming

class metavision_hal.I_DeviceControl

Facility that controls camera mode and allows to start, reset and stop it.

reset(self: metavision_hal.I_DeviceControl)None

Restarts the device and the connection with it.

set_mode_master(self: metavision_hal.I_DeviceControl)bool

Sets the camera as master.

The camera sends clock signal to another device
warning

This function must be called before starting the camera

return

true on success

set_mode_slave(self: metavision_hal.I_DeviceControl)bool

Sets the camera as slave.

The camera receives the clock from another device
warning

This function must be called before starting the camera

return

true on success

set_mode_standalone(self: metavision_hal.I_DeviceControl)bool

Sets the camera in standalone mode.

The camera does not interact with other devices.
warning

This function must be called before starting the camera

return

true on success

start(self: metavision_hal.I_DeviceControl)None

Starts the generation of events from the camera side.

warning

All triggers will be disabled at stop. User should re-enable required triggers before start.

stop(self: metavision_hal.I_DeviceControl)None

Stops the generation of events from the camera side.

class metavision_hal.I_Erc

Interface for Event Rate Controller (ERC) commands.

Note

This feature is available on Gen4 sensors and newer

enable(self: metavision_hal.I_Erc, b: bool)None

Toggles ERC activation.

b

Desired state. b = true means ERC active, and b = false means ERC inactive.

note

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

get_cd_event_rate(self: metavision_hal.I_Erc)int

Gets the CD event rate set point of the ERC.

return

The event rate expressed in events per second

note

See set_cd_event_rate to define the event rate target.

get_td_event_rate(self: metavision_hal.I_Erc)None
Note

get_td_event_rate() is deprecated since version 2.2.0 and will be removed in later releases. Please use get_cd_event_rate instead

is_enabled(self: metavision_hal.I_Erc)bool

Returns ERC activation state.

return

The ERC state

set_cd_event_rate(self: metavision_hal.I_Erc, events_per_sec: int)None

Sets the target CD event rate of the ERC.

events_per_sec

Event rate expressed in events per second

note

Event rate is computed by ERC block as the number of events generated by the sensor divided by the count period. To get the count period value, see get_count_period.

note

This method and set_cd_event_count operate over the same register. It is Expected that after parameterizing ERC using event rate, result of get_cd_event_count also changes.

set_td_event_rate(self: metavision_hal.I_Erc, arg0: int)None
Note

set_td_event_rate(…) is deprecated since version 2.2.0 and will be removed in later releases. Please use set_cd_event_rate instead

class metavision_hal.I_EventRateNoiseFilterModule

Interface for accessing the sensor level event rate based on noise filtering of a sensor.

This sensor level noise filter is based on the event rate only. If enabled, the sensor will transfer data if and only if the event rate is above a given event rate. It avoids streaming background noise information without relevant activity information.

note

This feature is available only on Gen3.1 sensors

enable(self: metavision_hal.I_EventRateNoiseFilterModule, enable_filter: bool)None

Enables/disables the noise filter.

enable_filter

Whether to enable the noise filtering

get_event_rate_threshold(self: metavision_hal.I_EventRateNoiseFilterModule)int

Gets the event rate threshold in Kevt/s below which no events are streamed.

return

Event rate threshold in Kevt/s

set_event_rate_threshold(self: metavision_hal.I_EventRateNoiseFilterModule, threshold_Kev_s: int)bool

Sets the event rate threshold. Below this threshold, no events are streamed.

threshold_Kev_s

Event rate threshold in Kevt/s

return

true if the input value was correctly set (i.e. it falls in the range of acceptable values for the sensor)

class metavision_hal.I_EventsStream

Class for getting buffers from cameras or files.

get_byte_size_events(self: metavision_hal.I_EventsStream)None

get_byte_size_events() is deprecated since version 2.2.0 and will be removed in later releases.

get_latest_raw_data(self: metavision_hal.I_EventsStream)numpy.ndarray[numpy.uint8]

Gets latest raw data from the event buffer.

Gets raw data from the event buffer received since the last time this function was called.

Returns

Numpy array of Events

log_raw_data(self: metavision_hal.I_EventsStream, f: str)bool

Enables the logging of the stream of events in the input file f.

This methods first writes the header retrieved through I_HW_Identification. Buffers of data are then written each time get_latest_raw_data is called (i.e. in the same thread it is called). :f: The file to log into

return

true if the file could be opened for writing, false otherwise or if the file name f is the same as the one read from

warning

The writing of each buffer of event will have to be triggered by calls to get_latest_raw_data

poll_buffer(self: metavision_hal.I_EventsStream)int

Returns a value that informs if some events are available in the buffer from the camera or the file.

return

Value that informs if some events are available in the buffer - 1 if there are events available - 0 if no events are available - -1 if an error occurred or no more events will ever be available (like when reaching end of file)

set_byte_size_events(self: metavision_hal.I_EventsStream, arg0: int)None

set_byte_size_events() is deprecated since version 2.2.0 and will be removed in later releases.

start(self: metavision_hal.I_EventsStream)None

Starts streaming events.

stop(self: metavision_hal.I_EventsStream)None

Stops streaming events.

stop_log_raw_data(self: metavision_hal.I_EventsStream)None

Stops logging RAW data.

Does nothing if no recording has been started

wait_next_buffer(self: metavision_hal.I_EventsStream)int

Returns a value that informs if some events are available in the buffer from the camera and blocks waiting until more events are available.

return

Value that informs if some events are available in the buffer - 1 if there are events available - -1 if an error occurred or no more events will ever be available (like when reaching end of file)

class metavision_hal.I_Geometry

Class to access information on the size of the sensor.

get_height(self: metavision_hal.I_Geometry)int

Returns height of the sensor in pixels.

return

Sensor’s height

get_width(self: metavision_hal.I_Geometry)int

Returns width of the sensor in pixels.

return

Sensor’s width

class metavision_hal.I_HALSoftwareInfo

Class that provides information about the HAL software.

get_software_info(self: metavision_hal.I_HALSoftwareInfo)metavision_sdk_base.SoftwareInfo

Gets plugin’s software information.

return

The plugin’s software information

class metavision_hal.I_HW_Identification

Facility to provide information about the available system.

get_available_raw_format(self: metavision_hal.I_HW_Identification)List[str]

Returns the name of the available RAW format.

return

The available format

note

Currently the available formats are: - EVT2 - EVT3

get_connection_type(self: metavision_hal.I_HW_Identification)str

Returns the connection with the camera as a string.

return

A string providing the type of connection with the available camera

get_integrator(self: metavision_hal.I_HW_Identification)str

Returns the integrator name.

return

Name of the integrator

get_manufacturer(self: metavision_hal.I_HW_Identification)None
Note

get_manufacturer() is deprecated since version 2.2.0 and will be removed in later releases. Please use get_integrator instead

get_sensor_info(self: metavision_hal.I_HW_Identification)Metavision::I_HW_Identification::SensorInfo

Returns the detail about the available sensor.

return

The sensor information

get_serial(self: metavision_hal.I_HW_Identification)str

Returns the serial number of the camera.

return

Serial number as a string

get_system_id(self: metavision_hal.I_HW_Identification)int

Returns the system id of the camera.

return

The system id as an integer

note

This number can be used to check the compatibility of biases file

get_system_info(self: metavision_hal.I_HW_Identification)dict

Returns all available information.

return

Map of key-value

note

The purpose of this function is mainly for debug and display system information The class provides a basic implementation that can be enriched by inherit class

get_system_version(self: metavision_hal.I_HW_Identification)int

Returns the version number for this system.

return

System version as an integer

class metavision_hal.I_HW_Register

Interface facility for writing/reading hardware registers.

read_register(*args, **kwargs)

Overloaded function.

  1. read_register(self: metavision_hal.I_HW_Register, address: int) -> int

Reads register.

address

Address of the register to read

return

Value read

  1. read_register(self: metavision_hal.I_HW_Register, address: str) -> int

Reads register.

address

Address of the register to read

return

Value read

  1. read_register(self: metavision_hal.I_HW_Register, address: str, bitfield: str) -> int

Reads register.

address

Address of the register to read

bitfield

Bit field of the register to read

return

Value read

write_register(*args, **kwargs)

Overloaded function.

  1. write_register(self: metavision_hal.I_HW_Register, address: int, v: int) -> None

Writes register.

address

Address of the register to write

v

Value to write

  1. write_register(self: metavision_hal.I_HW_Register, address: str, v: int) -> None

Writes register.

address

Address of the register to write

v

Value to write

  1. write_register(self: metavision_hal.I_HW_Register, address: str, bitfield: str, v: int) -> None

Writes register.

address

Address of the register to write

bitfield

Bit field of the register to write

v

Value to write

class metavision_hal.I_LL_Biases

Interface facility for Lower Level Biases.

get(self: metavision_hal.I_LL_Biases, bias_name: str)int

Gets bias value.

bias_name

Name of the bias whose value to get

return

The bias value

get_all_biases(self: metavision_hal.I_LL_Biases)dict

Gets all biases values.

return

A map containing the biases values

set(self: metavision_hal.I_LL_Biases, bias_name: str, bias_value: int)bool

Sets bias value.

bias_name

Bias to set

bias_value

Value to set the bias to

return

true on success

class metavision_hal.I_Monitoring

Interface facility to monitor sensor parameters (such as temperature and illumination)

get_illumination(self: metavision_hal.I_Monitoring)int

Gets illumination.

return

Sensor’s illumination (in lux)

get_temperature(self: metavision_hal.I_Monitoring)int

Gets temperature.

return

Sensor’s temperature (in C)

class metavision_hal.I_NoiseFilterModule

Noise filter module.

Note

This feature is available only on Gen4.1 sensors

disable(self: metavision_hal.I_NoiseFilterModule)None

Disables filtering.

No events are removed by this filter anymore.

enable_stc(self: metavision_hal.I_NoiseFilterModule, threshold: int)None

Enables the NoiseFilterModule in the mode STC

This filter keeps the second event within a burst of events with the same polarity

Parameters

threshold (int) – Delay (in microseconds) between two bursts of events

enable_trail(self: metavision_hal.I_NoiseFilterModule, threshold: int)None

Enables the NoiseFilterModule in the mode Trail

This filter keeps the first event within a burst of events with the same polarity

Parameters

threshold (int) – Delay (in microseconds) between two bursts of events

class metavision_hal.I_PluginSoftwareInfo

Provides information about the Plugin software.

get_plugin_name(self: metavision_hal.I_PluginSoftwareInfo)str

Gets plugin name.

return

The plugin name

get_software_info(self: metavision_hal.I_PluginSoftwareInfo)metavision_sdk_base.SoftwareInfo

Gets HAL’s software information.

return

HAL’s software information

class metavision_hal.I_ROI

Interface facility for ROI (Region Of Interest)

create_ROI(self: metavision_hal.I_ROI, roi: Metavision::DeviceRoi)List[int]

Creates a rectangular ROI in bitword register format.

roi

ROI’s geometry to transform to bitword register format

return

The ROI in bitword register format

create_ROIs(self: metavision_hal.I_ROI, roi_list: list)List[int]

Creates several rectangular ROIs in bitword register format

Parameters

vroi (list) – Vector of ROI to transform to bitword register format

Returns

The ROIs in bitword register format

enable(self: metavision_hal.I_ROI, enable: bool)None

Applies ROI.

state

If true, enables ROI. If false, disables it

warning

At least one ROI should have been set before calling this function

set_ROI(self: metavision_hal.I_ROI, roi: Metavision::DeviceRoi, enable: bool = True)None

Sets an ROI from DeviceRoi geometry The ROI input is translated into a bitword (register format) and then programmed in the sensor.

roi

ROI to set

enable

If true, applies ROI

set_ROIs(*args, **kwargs)

Overloaded function.

  1. set_ROIs(self: metavision_hal.I_ROI, roi_list: list, enable: bool = True) -> None

  2. set_ROIs(self: metavision_hal.I_ROI, cols_to_enable: list, rows_to_enable: list, enable: bool = True) -> None

set_ROIs_from_bitword(*args, **kwargs)

Overloaded function.

  1. set_ROIs_from_bitword(self: metavision_hal.I_ROI, vroiparams: List[int], enable: bool = True) -> None

Sets an ROI from bitword (register format)

vroiparams

ROI to set

enable

If true, applies ROI. If false, disables it

  1. set_ROIs_from_bitword(self: metavision_hal.I_ROI, roi_list: list, enable: bool = True) -> None

set_ROIs_from_file(self: metavision_hal.I_ROI, file_path: str, enable: bool = True)None

Sets union of several ROIs from a file with CSV format "x y width height".

file_path

Path to the CSV file with ROIs

enable

If true, applies ROI. If false, disables it

class metavision_hal.I_TriggerIn

Interface to handle external trigger signals.

disable(self: metavision_hal.I_TriggerIn, channel: int)bool

Disables external trigger monitoring.

channel

External trigger’s address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)

return

true if trigger was successfully disabled, false otherwise

enable(self: metavision_hal.I_TriggerIn, channel: int)bool

Enables external trigger monitoring.

channel

External trigger’s address (0 for Gen3/Gen3.1 sensors, 1 for Gen4/Gen4.1 sensors)

return

true if trigger was successfully enabled, false otherwise

warning

Trigger monitoring is disabled by default on camera start. So you need to call enable() to start detecting signal.

class metavision_hal.I_TriggerOut

Internal interface for trigger out signal configuration.

Note

The trigger out signal is a binary signal

disable(self: metavision_hal.I_TriggerOut)None

Disables the trigger out.

enable(self: metavision_hal.I_TriggerOut)bool

Enables the trigger out.

return

true if trigger was successfully enabled, false otherwise

loopback(self: bool)None

loopback() is deprecated since version 2.2.0 and will be removed in later releases.

set_duty_cycle(self: metavision_hal.I_TriggerOut, period_ratio: float)None

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_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.

period_ratio

the ratio representing pulse_width_us/period_us which must be in the range [0,1] (value is clamped in this range otherwise)

set_period(self: metavision_hal.I_TriggerOut, period_us: int)None

Sets the trigger out signal period (in us)

period_us

the period to set (in us)

class metavision_hal.RawFileConfig

RAW files configuration’s options.

property do_time_shifting

Take the first timer high of the file as origin of time.

max_events_per_buffer(self: metavision_hal.RawFileConfig)None

max_events_per_buffer() is deprecated since version 2.2.0 and will be removed in later releases.

property n_events_to_read

Number of events_byte_size blocks to read. At each read, n_events_to_read_*sizeof(RAW_event) bytes are read. :warning: sizeof(RAW_event) is defined by the events format contained in the RAW file read.

property n_read_buffers

The maximum number of buffers to allocate and use for reading. Each buffer contains at most n_events_to_read_ RAW events. The maximum memory allocated to read the RAW file will be read_buffers_count_ * n_events_to_read_ * sizeof(RAW_event). One can use this parameters to have a finer control on offline memory usage

class metavision_hal.RawFileHeader

A dedicated class to handle RAW file headers and handle easily their mandatory fields.

get_integrator_name(self: metavision_hal.RawFileHeader)str

Gets the integrator name of the source used to generate the RAW file.

return

Returns the integrator name if any, or an empty string otherwise

get_plugin_name(self: metavision_hal.RawFileHeader)str

Gets the name of the plugin to use to read the RAW file.

return

Returns the name of the plugin if any, or an empty string otherwise

set_integrator_name(self: metavision_hal.RawFileHeader, integrator_name: str)None

Sets the name of the integrator of the source used to generate the RAW file.

integrator_name

Name of the integrator

set_plugin_name(self: metavision_hal.RawFileHeader, plugin_name: str)None

Sets the name of the plugin to use to read the RAW file.

plugin_name

Name of the plugin

class metavision_hal.SensorInfo

Information about the type of sensor available.

Examples for Gen3.1 Sensor: - major_version = 3 - minor_version = 1

as_string(self: metavision_hal.SensorInfo)str
Returns the sensor’s information
return

The sensor’s version as a string

property major_version

Sensor Generation.

property minor_version

Sensor Revision.

metavision_hal.get_hal_software_info()metavision_sdk_base.SoftwareInfo
class metavision_hal.ConnectionType

Members:

MIPI_LINK

USB_LINK

NETWORK_LINK

PROPRIETARY_LINK