Event store

The dv-processing library provides an easy to use and an efficient data structure to store and manage incoming event data from the camera - the dv::EventStore class. It is implemented as a shallow, shared ownership data structure which only holds pointers to actual memory locations containing event data. Similarly to how OpenCV handles image data, the dv::EventStore does not copy the data, instead it only holds pointers to received packets of events and uses metadata of these packets to efficiently slice the data given time-intervals.

Create and store events

The following sample code shows how to create an empty event store and fill it with software generated events:

C++Python

#include <dv-processing/core/core.hpp>
#include <dv-processing/core/utils.hpp>

int main() {
    // Initialize an empty store
    dv::EventStore store;

    // Get the current timestamp
    const int64_t timestamp = dv::now();

    // Add some events into the event store
    // This allocates and inserts events at the back, the function arguments are:
    // timestamp, x, y, polarity
    store.emplace_back(timestamp, 0, 0, true);
    store.emplace_back(timestamp + 1000, 1, 1, false);
    store.emplace_back(timestamp + 2000, 2, 2, false);
    store.emplace_back(timestamp + 3000, 3, 3, true);

    // Perform time-based slicing of event store, the output event store "sliced" will contain
    // the second and third events from above. The end timestamp (second argument) is 2001, since start
    // timestamp (first argument) is inclusive and timestamp is exclusive, so 1 is added.
    const dv::EventStore sliced = store.sliceTime(timestamp + 1000, timestamp + 2001);

    // This should print two events
    for (const dv::Event &ev : sliced) {
        std::cout << fmt::format("Sliced event [{}, {}, {}, {}]", ev.timestamp(), ev.x(), ev.y(), ev.polarity())
                  << std::endl;
    }

    return 0;
}

Slicing Event Stores

dv::EventStore can be sliced by time or by the number of events. Slicing is a shallow operation, it does not copy any data. Slicing returns a new dv::EventStore that only references the data requested. The original store is unaffected.

Slicing by time

dv::EventStore implements event data slicing by time in an efficient way. By reusing the underlying packet structure, the slicing is performed with O(log n) time complexity. The following sample shows the usage of time based slicing functions:

C++Python

#include <dv-processing/core/core.hpp>
#include <dv-processing/data/generate.hpp>

int main() {
    using namespace std::chrono_literals;

    // Generate 10 events with time range [10000; 20000]
    const auto store = dv::data::generate::uniformEventsWithinTimeRange(10000, 10ms, cv::Size(100, 100), 10);

    // Get all events with timestamp above 12500, it will be 13000 and up
    dv::EventStore eventsAfterTimestamp = store.sliceTime(12'500);

    // Print the timestamp ranges
    std::cout << "1. " << eventsAfterTimestamp << std::endl;

    // Slice event within time range [12000; 16000); the end time is exclusive
    const dv::EventStore eventsInRange = store.sliceTime(12'000, 16'000);

    // Print the timestamp ranges; It will print that range is [12000; 15000] since end time is exclusive and
    // event at timestamp 16000 is not going to be included.
    std::cout << "2. " << eventsInRange << std::endl;

    return 0;
}

Slicing by number of events

dv::EventStore provides slicing capabilities by an index and number of events. The first argument to the dv::EventStore::slice() method is a starting index from which the output slice starts, the second optional argument is the number of events to be sliced. If the number argument is not provided, the slice will contain all events from given index.

Following sample shows how to slice an event store within given indices of the underlying events:

C++Python

#include <dv-processing/core/core.hpp>
#include <dv-processing/data/generate.hpp>

int main() {
    using namespace std::chrono_literals;

    // Add 10 event with timestamps in range [10000; 20000]
    const auto store = dv::data::generate::uniformEventsWithinTimeRange(10000, 10ms, cv::Size(100, 100), 10);

    // Get all events beyond and including index 5
    dv::EventStore eventsAfterIndex = store.slice(5);
    std::cout << "1. " << eventsAfterIndex << std::endl;

    // Get 3 events starting with index 2
    dv::EventStore eventsInRange = store.slice(2, 3);
    std::cout << "2. " << eventsInRange << std::endl;

    // Use sliceBack to retrieve event from the end; this call will retrieve last 3 events
    dv::EventStore lastEvents = store.sliceBack(3);
    std::cout << "3. " << lastEvents << std::endl;

    return 0;
}

Combining multiple EventStores

Multiple instances of dv::EventStore can be added together to have a single object to access and manage it. Since dv::EventStore uses pointers to underlying event packet data, combining does not involve any deep data copies, the implementation takes over shared memory ownership instead. Following sample show how to efficiently combine multiple event stores into one:

C++Python

#include <dv-processing/core/core.hpp>
#include <dv-processing/data/generate.hpp>

int main() {
    using namespace std::chrono_literals;

    // Generate 10 events with timestamps in range [10000; 20000]
    const auto store1 = dv::data::generate::uniformEventsWithinTimeRange(10000, 10ms, cv::Size(100, 100), 10);

    // Generate second event store with 10 events with timestamps in range [20000; 29000] to the second store
    const auto store2 = dv::data::generate::uniformEventsWithinTimeRange(20000, 10ms, cv::Size(100, 100), 10);

    // Final event store which will contain all events
    dv::EventStore finalStore;

    // Add the events into the final store; this operation is shallow, so no data copies
    // are performed, but the underlying data has shared ownership between all stores
    finalStore.add(store1);
    finalStore.add(store2);

    // Print specific information on what we contain in the event store
    std::cout << finalStore << std::endl;

    return 0;
}