Opening a Camera

In the Connecting to Devices guide, we explained how cameras are detected and how camera plugin are required. Let’s now see how to open a camera with the SDK.

Using HAL C++ API

A camera can be opened using the function Metavision::DeviceDiscovery::open():

device = Metavision::DeviceDiscovery::open(serial_number);

The serial_number can be given in the following forms:

  • Empty String: this will use the first available plugin compatible with a connected device

  • DeviceID: this will open the specified device using the first compatible plugin

  • Name:DeviceID: this will open the specified device using the first plugin with matching Integrator or Plugin name

  • IntegratorName:PluginName:DeviceID: this will open the specified device ID using the specified plugin. The fields IntegratorName or PluginName can be empty, and if so, are ignored.

The first plugin that fulfills the requirements of the Integrator’s name and the Plugin’s name and that is able to open the DeviceID is used to open the device. As a camera device may be supported by several plugins, you may want to specify the plugin to be used by Integrator or Plugin name.

Additionally, the camera initialization process can be customized by supplying a configuration structure to the Metavision::DeviceDiscovery::open() function. This configuration structure is encapsulated in an instance of the Metavision::DeviceConfig class, allowing users to specify parameters tailored to their specific application requirements.

For example, the following code excerpt shows how to select the EVT 2.1 encoding format:

Metavision::DeviceConfig device_config;
device_config.set_format("EVT21");
device = Metavision::DeviceDiscovery::open(serial, device_config);

See also

The same mechanism can also be utilized to disable the camera biases ranges by invoking the following command: device_config.enable_biases_range_check_bypass(true).

A simple example demonstrating how to discover and open cameras with this HAL C++ API can be found in the metavision_hal_ls sample.

Using HAL Python API

The HAL Python API is a binding of the C++ API so the usage is similar:

device = DeviceDiscovery.open(serial_number)

The description given above for the C++ API is valid also for this Python API.

A simple example demonstrating how to discover and open cameras with this HAL Python API can be found in the metavision_hal_get_started sample.

Using SDK Stream C++ API

The HAL API shown above is an excellent starting point for programming event-based sensors. It provides fine-grained control and direct access to all the features of the sensor and camera.

However, if your goal is to build a more comprehensive application including functionalities like display, data conversion, and other high-level features, you may want to consider our other APIs. These APIs are built on top of HAL and add an abstraction layer, simplifying development while still providing powerful capabilities. For more details, see our SDK Architecture page, which explains this layered approach.

So for C++ development, we recommend the SDK Stream module, which offers a more user-friendly interface. This module simplifies access to the camera and data through the Camera class, making it easier to get started and implement complex workflows.

Essentially, the simplest way to open a device with the Camera class is to let the class find the first available device:

camera = Metavision::Camera::from_first_available();

To see the Camera class in action, you can follow the tutorial Get Started using C++.

Using SDK Stream Python API

The SDK Stream Python API is a binding of the SDK Stream C++ API so the usage is similar:

camera = Camera.from_serial(serial_number)

To see this Camera class in action, see our Python Get started guide or the metavision_camera_stream_slicer Python sample.

Using SDK Core Python API

In addition to the SDK Stream Python class Camera mentioned in the previous sections, the SDK also provides another class for opening cameras: EventsIterator.

The EventsIterator class was developed prior to the binding of the C++ Camera class and has therefore been widely used in various samples and tutorials. While newer implementations may favor the Camera class for its streamlined interface, the EventsIterator remains a robust and well-documented choice for accessing event-based data.

To us this API, the following statement will establish a connection to the first available device:

mv_iterator = EventsIterator("")

To see the EventsIterator class in action, explore the code samples section. There, you can find a variety of examples that utilize this class, demonstrating its functionality in different contexts and providing practical implementations to help you get started.

Going Further

To learn how to tune your sensor, start your device and retrieve the event stream, refer to our other programming guides: