EVT3 Decoding Configuration

The event stream produced by an event-based camera (or read from a RAW file) can undergo data drop or data corruption that may lead to invalid events that will affect the application using them. In the case of EVT3 format, the data decoder can be configured to detect EVT3 protocol violation, inform the user that a problem occurred and make sure the decoded events are valid. Essentially, the robust decoder will discard events that are affected by data drop/corruption as explained in the next section.

Note

Data drop or corruption can have many root causes: bandwidth limitation between the camera and the application, sensor defects, faulty hardware, corrupted raw file etc. In the case of bandwidth issue, the first counter-measure is to check if the event rate produced by the sensor can be reduced. To do so, check your lighting, focus, and sensor settings (biases, ROI, ESP…) as explained in the section First recording from live camera with Metavision Studio.

Protocol violations and default behaviour

The following violation can be detected in the EVT3 stream:

Name	Violation Description	Mitigation/fix	Log Level
NonMonotonicTimeHigh	Time-high words received are non-monotonic (they are decreasing at some point)	events with decreasing time-high are dropped	Error
InvalidVectBase	The VectBase is not set or out of bound (it would generate invalid events)	events are dropped until VectBase is set or valid	Error
PartialVect_12_12_8	Vect12 word not followed by a vect12 and a vect8	sequence is dropped up until we reach a valid event	Warning
PartialContinued_12_12_4	Continued12 word not followed by a continued12 and a continued4	sequence is dropped up until we reach a valid event	Warning
NonContinuousTimeHigh	Time-high are increased by more that 1	None	Warning
MissingYAddr	No Y coordinate was provided	events are dropped until Y address is set	Warning

Decoder configuration and tuning for violations

Because verifying all EVT3 protocol violations during decoding will impact performances, user can configure it by defining some environment variables (in order of priority):

• when MV_FLAGS_EVT3_ROBUST_DECODER is set, all errors are checked (best reliability)

• when MV_FLAGS_EVT3_UNSAFE_DECODER is set, no error is checked (best performance)

• by default, only NonMonotonicTimeHigh and InvalidVectBase are checked (best trade-off)

For example, here is ow to launch Metavision Studio with the robust decoder:

Linux

$ export MV_FLAGS_EVT3_ROBUST_DECODER=1
$ metavision_studio
  [SERVER] - stderr - [HAL][INFO] Using EVT3 Robust decoder.

Windows

> set MV_FLAGS_EVT3_ROBUST_DECODER=1
> metavision_studio
  [SERVER] - stderr - [HAL][INFO] Using EVT3 Robust decoder.

By default, when an EVT3 violation happens, user is notified with the log message mentioned in the previous section. In addition, the following callback mechanism on the decoder API can be used for custom actions:

auto decoder = device.get_facility<I_Decoder>();
evt3_decoder->add_protocol_violation_callback([](Metavision::decoder::evt3::ProtocolViolation protocol_violation){
    // EVT3 violation has been detected.
    // Violation types are described in hal/cpp/include/metavision/hal/utils/decoder_protocol_violation.h
});

As NonMonotonicTimeHigh is the most impactful violation, it is possible to set the environment variable MV_FLAGS_EVT3_THROW_ON_NON_MONOTONIC_TIME_HIGH so the EVT3 decoder will raise an exception on this protocol violation.

Here is an example:

Linux

$ export MV_FLAGS_EVT3_THROW_ON_NON_MONOTONIC_TIME_HIGH=1
$ metavision_viewer
  Simple viewer to stream events from a file or device, using the SDK driver API.
  [....]
  [HAL][INFO] Decoder will raise exception upon EVT3 Non Monotonic Time High violation
  Camera has been opened successfully.
  [....]
  [HAL][ERROR] EVT3 Protocol violation detected : NonMonotonicTimeHigh
  terminate called after throwing an instance of 'Metavision::decoder::evt3::ProtocolViolation'
  Aborted (core dumped)

Windows

> set MV_FLAGS_EVT3_THROW_ON_NON_MONOTONIC_TIME_HIGH=1
> metavision_viewer
  Simple viewer to stream events from a file or device, using the SDK driver API.
  [....]
  [HAL][INFO] Decoder will raise exception upon EVT3 Non Monotonic Time High violation
  Camera has been opened successfully.
  [....]
  [HAL][ERROR] EVT3 Protocol violation detected : NonMonotonicTimeHigh
  terminate called after throwing an instance of 'Metavision::decoder::evt3::ProtocolViolation'

Event Stream decoding in Metavision Studio

In Metavision Studio, when an error is raised by an EVT3 protocol violation (NonMonotonicTimeHigh or InvalidVectBase), a pop-up will be shown to inform the user of the problem:

When this error happens:

• if you were recording the stream, you should stop the recording and discard it as the data quality will not be optimal

• you should try to reduce the event rate (visible in the right-hand panel of Studio). To do so, check your lighting, focus, and sensor settings (biases, ROI, ESP…) as explained in the section First recording from live camera with Metavision Studio.

If you want to disable EVT3 violation detection, you can use the unsafe decoder (setting MV_FLAGS_EVT3_UNSAFE_DECODER) so that no error check will be performed. Note that doing so, you take the risk of decoding bad quality data that could lead to an application crash.