Goal

In this tutorial, you will learn how to to use EventCV to load and open event files to retrieve frame slices.

Requirements

Please make sure you have installed EventCV using your preferred Python package manager.

You have an event stream file in one of the following supported formats:

  • .hdf5
  • .bag
  • .npz
  • .txt
  • .csv
  • .aedat
  • .dat

If you do not have an event file to work with, you can follow this tutorial along at our Google Colab to get hands on experience. Or you can download an example stream from N-ImageNet here.

ecv.load() and ecv.open()

There are two main ways to read event files.

  • ecv.load() will import all the events into memory, which for smaller individual files is safe.
  • ecv.open() is a lazy-loader that pre-slices the event stream for efficiency, safer for large files.

EventCV has an auto-detection feature for sensor resolution, [x,y,t,p] format, and time-units.

Python
import eventcv as ecv

# use ecv.load() to import all the events into memory
stream = ecv.load("example.npz")
print(stream.sensor_size) # (W, H)
print(len(stream))        # number of events
print("first events [x, y, t, p]:")
print(stream.numpy()[:5])  # print the first 5 rows of events
Python
import eventcv as ecv

# use ecv.open() to lazy-load an event stream
stream = ecv.open("example.npz")
print(stream.sensor_size) # (W, H)
print(len(stream))        # number of events

There is little difference in functionality between load and open, other than with open we must explicitly call a slice first to access the events, since nothing is loaded into memory yet.

More details on EventStream and EventReader objects can be found in the official Documentation

To load event files lazily with slices, we must tell EventCV how we want it sliced. The two options we have are:

  • Max timewindow (dt_ms) – maximum timewindow to accumulate over in milliseconds.
  • Max events (event_count) – maximum number of events to accumulate over in raw counts.
Python
# open an event stream with a different max timewindows 
stream5 = ecv.open("example.npz", dt_ms=5)
stream10 = ecv.open("example.npz", dt_ms=10)
print(stream5.n_slices)   # returns number of slices at 5 msec timewindows
print(stream10.n_slices)  # returns number of slices at 10 msec timewindows

# shows the number of events in the first slice
print(len(stream5.slice(0)))
print(len(stream10.slice(0)))
Python
# open an event stream with a different max timewindows 
stream25 = ecv.open("example.npz", max_events=25000)
stream150 = ecv.open("example.npz", max_events=50000)
print(stream25.n_slices)   # returns number of slices for 25,000 max events
print(stream50.n_slices)  # returns number of slices for 50,000 max events

# shows the number of events in the first slice
print(len(stream25.slice(0)))
print(len(stream50.slice(0)))

A sliced stream creates an EventFrame object, which allows you to view the event stream and convert to NumPy arrays.

Python
stream = ecv.open("example.npz", dt_ms=10)
slice0 = stream.slice(0)
slice0.view()                # renders an object view of the sliced stream
slice0_np = slice0.numpy()   # converts sliced object to a numpy array

Recap

In this tutorial, we learned how to interact and work with event stream files, use the lazy loader open for efficient data slicing, and controlling the maximum timewindow or event count for slicing.

The next tutorial covers the different event-based representations that EventCV offers, but first test your knowledge below.

Test your knowledge

 
QUIZ START

#1. After loading an event stream with stream = ecv.load(“example.npz”), how do you return the number of events?

The EventStream object is fully loaded into memory and is a list of [x, y, t, p] events that can be returned simply in Python by using len(stream)

Previous
Next

#2. You need to load all events into memory to get access to filters and transforms in EventCV

This is a false statement, EventCV allows you to apply filters and transforms on a EventReader object using ecv.open() on a per slice basis

Previous
Next

#3. Which EventCV object is created when using ecv.open()?

ecv.open() is the lazy reader option, so will return an EventReader object when opening an event file. This should be used for large event stream volumes that consume a lot of memory

Previous
Finish

Results

Next tutorial: Event representations

Learn about the different event representations EventCV includes

Scroll to Top