Data Formats Reference

Event-camera data appears in different formats at different stages: the sensor's raw output, the standard event stream, and human-readable text. This page summarizes the four formats we deal with. For the event principle see Fundamentals, and for encode/decode APIs see Toolkit API.

Format quick reference

Format	What it is	When you encounter it	Conversion tool
RAW8	MIPI raw packet (on-board record)	Recorded by evs_live_player on carrier boards like RDK X5	raw8_to_evt2
EVT2	Standard event stream (Metavision-compatible)	Standard input/output of host software and algorithm libraries	evt2_to_csv / MultiVision Studio
HVEventsFormat	64-bit compact event encoding (our optimized format)	Efficient storage/transport inside the Toolkit	Toolkit encode/decode API
CSV	Human-readable text (x,y,p,t)	Offline analysis, Python/MATLAB processing	evt2_to_csv

---

EVT2 (standard event stream)

EVT2 is the standard event-stream format compatible with the Metavision SDK; our Windows host software (MultiVision Studio) and Ubuntu algorithm library both use it as their standard input/output. Header structure:

struct EVT2Header {
    std::string format_line;    // format line
    std::string integrator;     // integrator name
    std::string date;           // creation date
    uint32_t width;             // sensor width
    uint32_t height;            // sensor height
    uint64_t start_timestamp;   // start timestamp (microseconds)
};

Events are encoded/decoded (CD events) via EventCDEncoder/EVT2Decoder; EventTriggerEncoder handles external trigger events, and EventTimeEncoder handles timestamp high-bit encoding (N_LOWER_BITS_TH = 6, REDUNDANCY_FACTOR = 4). Type Timestamp = uint64_t (microseconds). Full API at Toolkit API — hv_evt2_codec.h.

RAW8 (MIPI raw packet)

On carrier boards like RDK X5, evs_live_player saves recordings as RAW8 (MIPI raw packet) by default. RAW8 cannot be read directly by the host software or algorithm library; it must first be converted to EVT2:

./raw8_to_evt2 /userdata/hand_wave.RAW8 /userdata/output.raw

See RDK X5 Carrier Board Adaptation — RAW8 to EVT2.

Why store RAW8 first, then convert to EVT2

At high frame rates, decoding and displaying in real time exceeds CPU capacity (above ~120 FPS the picture stutters). Recording saves only the raw packet to memory, and raw8_to_evt2 later converts it to standard EVT2 — balancing real-time display with complete data.

HVEventsFormat (64-bit compact encoding)

An optimized 64-bit event encoding provided by our Toolkit, for efficient storage and transport:

Field	Bits	Range
Timestamp	43 bits	Supports longer time series
X coord	10 bits	0–1023
Y coord	10 bits	0–1023
Polarity	1 bit	0 / 1

Magic number HV_RAW_MAGIC = 0x48565241 ("HVRA"). Single-event and batch encode/decode are provided: encode_hv_event / decode_hv_event / encode_hv_events_batch / decode_hv_events_batch. Full interface at Toolkit API — hv_events_format.h.

CSV (human-readable text)

EVT2 can be exported to CSV for viewing in Excel, analysis with Python/MATLAB, or plotting with visualization tools. Column definitions:

x,y,polarity,timestamp
352,240,1,1234567890
120,180,0,1234567920

Column	Meaning	Values
x	abscissa	0 ~ (width-1), depends on sensor (e.g. 768 wide → 0–767; 4096 wide → 0–4095)
y	ordinate	0 ~ (height-1)
polarity	polarity	0 (darken) / 1 (brighten)
timestamp	timestamp	microseconds

./evt2_to_csv /userdata/hand_wave.raw /userdata/events.csv

Warning

A long recording exported to CSV can reach hundreds of MB; opening it directly may freeze your machine — stream-process it with a script. A Python read-and-analyze example is in Python Tutorial.

---

Format selection guidance

• On-board recording (RDK X5, etc.): store RAW8 first, then convert to EVT2 as needed.
• Host software / algorithm library processing: use EVT2 uniformly.
• Cross-platform exchange, archiving: EVT2 (standard, compact).
• Offline data analysis, beginner debugging: CSV (readable, but bulky).
• High-performance internal pipelines: HVEventsFormat (64-bit compact).