Event File Format-V0 3

Event File Format-V0 3




Document Version 0.3

Event File Format Specification


  1. Event File Format Overview

 This document provides specification for the different file storing event data. Event file contain: Contrast Detection (CD) events plus some other optional events.


  1. Contrast Detection event

For each pixel event, X & Y coordinates of the pixel (2D event) that triggered the event are stored in the file as well its timestamp and the polarity of the event:

  • “1” increase of pixel illumination
  • “0” decrease of pixel illumination

Timestamp is provided in microsecond unit and is “relative”: timestamp counter is set to 0 when camera is started


  1. External Trigger events

 These optional events are inserted in the file when and external trigger signal is sent to the camera. Polarity indicates rising or falling edge of the trigger input signal. Timestamp of this event as well as the channel ID (Camera may have different trigger input) are provided.


  1. IMU events

Some camera (optional) have an embedded “Inertial Measurement Unit” (IMU) providing accelerometer and gyro information. The IMU information: linear acceleration and rotation speed are embedded in these events.


  1. USB packet info events”

 USB packet info events are events added by the driver (not provided by the camera itself) and encoded as “OTHERS” event (event extension type). These events are inserted by the driver at the beginning and at the end of each USB packet transporting camera events. These events provide the number of events in the USB packet as well the arrival system time. This time is the system epoch time (starting on January 1st, 1970 for Linux) expressed in microseconds.

Warning: These USB packet info events will be deprecated in future version. Do not use in new development


  1. File type

There are three different file formats: “raw “, “dat” and “csv” event file. Raw files contain “native” data provided by the camera and may contain any type of event embedded in a single file while “dat” and “csv” file contain only decoded 2D CD events.

Raw file is the Prophesee native and smaller file format. The drawback is that it must be decoded before processing, and it does not allow easy seek in the file

Dat and csv files are decoded files, so it is easy to seek in these files, and it does not require decoding. Drawback is that these files are bigger. Csv files may be huge, but provide an easy way to display events using spreadsheet program (Excel).


  1. Raw File Format

”raw” format is used to store events streamed by the event camera. No processing or decoding is performed, “raw sensor data” is stored using Prophesee proprietary EVT2.0 raw format. 

Raw file is binary little-endian format preceded by an ASCII text header. File extension is .raw


  1. Raw File Format header

File header is composed of text lines starting with “%”(0x25) followed by a space (0x20), a keyword, a space (0x20), a value and New line NL / Line Feed (0x0A)


  1. Header keywords & values

Keyword

Value

Date

Recording date, format: YYY-MM-DD HH:MM:SS

camera_maker

Company Name of the Camera maker

camera_model

Name of Camera Model

width

Horizontal resolution => x valid coordinate between 0 and width -1

height

Vertical resolution => y valid coordinate between 0 and height -1

firmware_version

Camera Firmware Version (depends on camera model / maker)

data_format

Event format coding: default: EVT2.0

manual_events

NO value. This keyword indicates file contain USB packet information. Will de deprecated in future versions of raw files

serial_number

Camera serial number

subsystem_ID

Subsystem ID: Camera maker specific

system_ID

System ID: Camera maker specific


  1. Header example:

 Raw file header or a stream recorded with Prophesee Camera EVK-V1 using PPS3MVCD sensor

% Date 2020-03-05 11:35:05

% camera_maker Prophesee

% camera_model EVK-V1 Gen 3.1 CD

% width: 640

% height 480

% firmware_version 3.3.0

% data_format evt 2.0

% manual_events

% serial_number 00001087

% subsystem_ID 2418019330

% system_ID 28


  1. Binary Event Data

 Each raw event data EVT2.0 is represented in one 32 bit words: 4 bytes: Byte 0 to 3. 

Byte 3

Byte 2

Byte 1

Byte 0

31                              24 23                             16 15                              8  7                                   0


  1. Event Time Encoding 

 All events are timestamped with a micro-second precision. Timestamp are encoded with 34 bits providing a rollout after:  2^34µs = 4 hours and 46 minutes.

 In order to minimize the amount of information stored with each event, the event timestamp is encoded in two parts. Lower 6 significant bits (0..5) of the micro-second timestamp are directly encoded into the CD or Trigger event, while the 28 most significant bits (6..33) of the timestamp are stored in a dedicated EVT_TIME_HIGH event. To rebuild the full event timestamp, the lower bits of the timestamp embedded in the event must be concatenated with the last EVT_TIME_HIGH event information.


Event time base

                                                                                        5                                0

Event time high

27                                                                                0

Full resolution timestamp

33                                                                                6  5                                0

In order to properly compute full resolution timestamp, the first event type in the stream is a EVT_TIME_HIGH event

                                                                               

  1. Event types

A four bits “type field” (bit 28..31) encodes the event type. Four types are used:

Byte 3

Byte 2

Byte 1

Byte 0

Event

Type


31          28 27        

                                                                                                                          0

Event Type

 Description 

Value

CD_LOW

CD event: decrease in illumination (polarity '0') 

'0000' (0)

CD_HIGH

CD event, increase in illumination (polarity '1') 

'0001' (1)

EVT_TIME_HIGH

 Timer high bits 

'1000' (8)

EXT_TRIGGER

 External trigger event

'1010' (10, 0x0A)

IMU_EVT

 Inertial Measurement Unit” event providing accelerometer and gyro information. 

'1101' (13, 0x0D)

OTHERS

 Used for extension (e.g. USB packet info or MIPI event)

'1110' (14, 0x0E)

CONTINUED

 Extra data to previous event

'1111' (15, 0x0F)

 



  1. CD Events

 For CD events, X, Y coordinates and timestamp information are provided in the 28 lower bits. X and Y are encoded with 11 bits providing up to 2048 x 2048 resolution. Lower part of timestamp is provided on 6 bits. 

31                              24 23                             16 15                              8  7                                   0

Byte 7

Byte 6

Byte 5

Byte 4

Event type

‘0000’ or

‘0001’

Low part of timestamp (5..0)

X

Y

31                28 27                22 21                                      11 10                                                   0

Lower bit of CD type provides the polarity information:

  • Event Type = CD_LOW = 0: decrease of illumination, polarity = 0
  • Event Type = CD_HIGH = 1: increase of illumination, polarity = 1


  1. EVT_TIME_HIGH event

 Event Timer High events provides the 28 bits of the high part of the timestamp

31                              24 23                             16 15                              8  7                                   0

Byte 7

Byte 6

Byte 5

Byte 4

‘1000’

High part of timestamp (bits 33..6)

31          28 27                                                                                                                                   0


  1. EXT_TRIGGER event

External Trigger event information is composed of the low part of the timestamp as well as the trigger channel ID indicating the trigger source: coded on five bits and the edge of the trigger coded on one bit.

31                              24 23                             16 15                              8  7                                   0

Byte 7

Byte 6

Byte 5

Byte 4

‘1010’

Lower part of timestamp (5..0)

Unused

Trigger channel ID

Unused

edge

31        28 27                     22 21                                 13 12                  8 7                     1       0

Edge:

  • 0: Falling edge
  • 1: Rising edge

Trigger channel ID for EVK-V1

  • 0: Main Trigger
  • 6: Loopback Trigger
  • 7: Auxiliary Trigger

Trigger channel ID for CCAM5 / EVK-V3

  • 0: Main Trigger
  • 1: Loopback Trigger


  1. IMU_EVT event

Inertial Measurement Unit (IMU) events provide accelerometer and gyroscope information. The three axis orientation is provided in the following figure:


These events are composed of six 32-bit words; the first being an IMU_EVT, followed by 5 CONTINUED events.

Each of the 6 events provides 6 DOF measurements encoded in a 16-bit signed word:

  • X translation acceleration
  • Y translation acceleration
  • Z translation acceleration

Translation acceleration is provided in “g” unit (g = 9.81 m/s²) with a full scale of +/- 2 g è 16,384 LSB/g

  • Angular velocity around X axis
  • Angular velocity around Y axis
  • Angular velocity around Z axis

Angular velocity is provided in “degree per second” with a full scale of +/- 250°/s è 131 LSB/(°/s)

‘1101’

IMU_EVT

Lower part of time stamp (5..0)

Unused

X translation acceleration (16 bit)

0

‘1111’

CONTINUED

Lower part of time stamp (5..0)

Unused

Y translation acceleration (16 bit)

0

‘1111’

CONTINUED

Lower part of time stamp (5..0)

Unused

Z translation acceleration (16 bit)

0

‘1111’

CONTINUED

Lower part of time stamp (5..0)

Unused

Angular velocity around X axis (16bit)

0

‘1111’

CONTINUED

Lower part of time stamp (5..0)

Unused

Angular velocity around Y axis (16bit)

0

‘1111’

CONTINUED

Lower part of time stamp (5..0)

Unused

Angular velocity around Z axis (16bit)

0

31        28 27                     22 21             17 16                                                               1       0


  1. USB packet info event

USB packet info provides information on USB transport layer while the stream has been recorded. If the file contains such events, it is indicated in the header with the “manual_events” keyword.

This USB packet info event is encoded as one OTHER event type followed by 4 CONTINUED events (five 32bit words). Sub-type is USB_PACKET_INFO = 0xFE.

 These USB packet info events are inserted at the start and at the end of “regular events” sequences. A first one indicates the start of the sequence, the second the end of the sequence. Sequence size corresponds to the USB packet size when the stream has been recorded.

These events contain:

  1. “flag” bit: Start (flag =1) or End (flag=0) of sequence
  2. “sequence count” The size of the sequence: Number of events in the sequence expressed in number of 32 bits words (excluding USB packet info events). Sequence count encoded on 32 bit.
  3. “arrival system time”: Provide system epoch time when the sequence has been received: (USB packet arrival). It is encoded on 64 bits. (time origin is January 1st, 1970 for Linux system). 

USB packet info “Start”

Sequence of regular events

USB packet info “End”

USB packet info “Start”

Sequence of regular events

…



‘1110’

OTHERS

Unused

Event sub-type: USB_PACKET_INFO = 0xFE

‘1111’

CONTINUED

12 most significant bits of the sequence count

(bits 31..20)

flag

Unused

‘1111’

CONTINUED

8 most significant bits of the arrival system time (bits 63..56)

20 least significant bits of the sequence count (bits 19..0) 

‘1111’

CONTINUED

28 middle significant bits of the arrival system time (bits (55..28)

‘1111’

CONTINUED

28 least significant bits of the arrival system time (bits 27..0)

31                28 27                                          20  19                                   16    15    14                                           0

Note: “Sequence count” and “Arrival system time “values for start and end have the same value.


  1. MIPI end of frame event

 MIPI end of frame provides information on MIPI transport layer while the stream has been recorded.  This event is inserted at the end of each MIPI frame.

 This type of event is present only in case event data has been transmitted over MIPI interface. It is encoded as a single OTHER event.

It is encoded as a Monitoring Event: class = 0, and the Sub-type is MIPI_END_FRAME = 0x19

‘1110’

OTHERS

Lower part of timestamp (5..0)

Unused

Class ‘0’

Event sub-type: MIPI_END_FRAME = 0x19

31                28 27                      22  21                                                  17    16       15                                            0



  1. Dat File Format

”dat” format contains decoded event. dat file is a binary little-endian format file. It is composed of three sections:

  1. ASCII text Header
  2. Binary event type and size information
  3. Binary event data

. “dat” files contains only 2D CD event. File extension is .dat


  1. Dat File Format header

File header is composed of text lines starting with “%”(0x25) followed by a space (0x20), a keyword, a space (0x20) a value and New line NL / Line Feed (0x0A)

  1. Header keywords & values

Keyword

Value

Data file containing

Type of event: CD (Only CD type is supported)

Version

Format version: currently: 2

Date

Recording date, format: YYY-MM-DD HH:MM:SS

Width

Horizontal resolution => x valid coordinate between 0 and width - 1

Height

Vertical resolution => y valid coordinate between 0 and height - 1


  1. Header example:

Raw file header or a stream recorded with Prophesee Camera EVK-V1 using PPS3MVCD sensor

% Data file containing CD events

% Version 2 

% Date 2020-03-05 11:35:05

% Width: 640

% Height 480


  1. Binary event type & Size

  This information is provided as two bytes: First one indicates event type: Only CD type is supported. The second provide the Event size: Always 8

First Byte

Event Type

  0 (0x00): CD event 

Second Byte

Decoded Event Size (in Byte)

8




  1. Binary event data

 Each decoded Event Data 2.0 is represented as two 32 bit words: 8 bytes: Byte 0 to 7. They are stored in incremental value of timestamp

First 4 bytes: 32 bit words contain event timestamp with one micro-second precision providing a rollout after:  2^32µs = 1,2 hours. 

31                              24 23                             16 15                              8  7                                   0

Byte 3

Byte 2

Byte 1

Byte 0

timestamp


Next 4 bytes contain event X, Y coordinates and polarity information. X and Y are encoded with 14 bits: X[13..0] and Y[27..0]. Polarity is encoded on 4 bits: [31..28]. Only 0 & 1 values are used.

 Up to 16384 x 16384 resolution is supported. 

31                              24 23                             16 15                              8  7                                   0

Byte 7

Byte 6

Byte 5

Byte 4

polarity

Y

X

31          28 27                                                          14  13                                                              0




  1. csv File Format

”csv” format is the ASCII version of the CD event .dat file, embedded in an Excel csv compatible format. All data are stored as ASCII characters. “csv” file contains only CD event

  • Separator is “;”
  • File extension is .csv

There is one line per event with the following format:

 Timestamp_value ;  X  ;  Y  ;  Polarity

Timestamp: whole number value in µs

X: whole number of pixel horizontal coordinate: [0.. width - 1]

Y: whole number of pixel vertical coordinate: [0.. height - 1]

Polarity: whole number indicating illumination change polarity




All rights reserved © 2020 Prophesee - This document contains proprietary and confidential information of Prophesee S.A. and is subject to confidentiality obligations. This document is not to be copied in whole or part, disclosed or otherwise disseminated to any third parties without the prior written acceptance of a duly authorized representative of Prophesee S.A.