Get Started with HAL API using Python

The sample metavision_hal_get_started.py shows how to use Python HAL API to read events from a live camera or from a RAW file.

The source code of this sample can be found in <install-prefix>/share/metavision/hal/python_samples/metavision_get_started when installing Metavision SDK from installer or packages. For other deployment methods, check the page Path of Samples.

Note

This guide focuses on the HAL API, the most fundamental API available in the SDK, designed for managing event-based devices. Employing this class provides granular control over the device, enabling tasks such as the retrieval of data buffers and the decoding of events. Depending on your requirements, you might find it more convenient to utilize a higher-level API. The EventsIterator class offers a more streamlined approach, as illustrated in the Get Started using Python API guide.

Expected Output

The sample prints the size (number of CD events) of each buffer it receives from a live camera or from a RAW file and shows the timestamp of the first and last events of that buffer.

Example of the output when launched on the file laser.raw from our Sample Recordings:

$ python metavision_hal_get_started.py -i laser.raw
New buffer of size 288 with timestamp range: (6384,6392)
New buffer of size 288 with timestamp range: (6392,6400)
New buffer of size 291 with timestamp range: (6400,6406)
New buffer of size 292 with timestamp range: (6407,6414)
New buffer of size 288 with timestamp range: (6414,6422)
New buffer of size 293 with timestamp range: (6422,6435)
New buffer of size 288 with timestamp range: (6435,6445)
New buffer of size 298 with timestamp range: (6445,6455)
(...)

How to start

To start the sample based on the live stream from your camera, run:

python metavision_hal_get_started.py

Note that to keep this code simple, we did not include a mechanism for the user to close the camera. With this implementation, press CONTROL + C to stop the program. This action will be caught by the KeyboardInterrupt exception as mentioned in the Code Overview section below.

To start the sample based on recorded data, provide the full path to a RAW (here, we use the file spinner.raw from our Sample Recordings):

python metavision_hal_get_started.py -i spinner.raw

Code Overview

This sample code is a very basic example of the HAL Python API but it can serve as a foundational code template to help you get started. Let’s review the various steps required to stream from a live camera or read a RAW file:

• First, we create an instance of the device object using DeviceDiscovery

  if args.event_file_path:
      device = DeviceDiscovery.open_raw_file(args.event_file_path)
  else:
      device = DeviceDiscovery.open("")
  

  Then, we will access the features of the device through the Python binding of the device facilities.

• The core idea for retrieving CD events involves setting up a callback with the CD event decoder. This setup ensures that as soon as the events are captured from the camera, they will be processed by this callback. To do so, we use get_i_event_cd_decoder to retrieve the facility and then call add_event_buffer_callback to register the function print_cd_events as a callback.

  i_cddecoder = device.get_i_event_cd_decoder()
  i_cddecoder.add_event_buffer_callback(print_cd_events)
  

  Note

  The callback function must be defined with a parameter that will receive the event buffer:

  def print_cd_events(event_buffer):
      # read/process the events from the buffer (e.g. event_buffer[0]["x"])
  

• Next, we need a stream decoder that will receive raw data from your device, and dispatch parts of the buffer to instances of our decoders for specific event types (in this simple example, we handle only CD events with the CD decoder instantiated earlier)

  i_eventsstreamdecoder = device.get_i_events_stream_decoder()
  

• Then, we use the I_EventsStream to start streaming:

  i_eventsstream = device.get_i_events_stream()
  i_eventsstream.start()
  

• Finally, we will check if some events are available byt calling i_eventsstream.poll_buffer(), fetch the buffers of events with i_eventsstream.get_latest_raw_data and trigger the decoding with calls to i_eventsstreamdecoder.decode(raw_data) that will in turn call the CD events callback defined earlier:

  ret = i_eventsstream.poll_buffer()
  if ret < 0:
      i_eventsstream.stop()
      break
  elif ret > 0:
      raw_data = i_eventsstream.get_latest_raw_data()
      if raw_data is not None:
          i_eventsstreamdecoder.decode(raw_data)
  

Like mentioned above, we did not include a mechanism for the user to close the camera. So to stop the program, we expect the user to press CONTROL + C. This action will be caught by the KeyboardInterrupt exception which allows us to continue the program and properly stop the camera with i_eventsstream.stop().