dv-toolkit 0.2.0__tar.gz

dv_toolkit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Kuga Maxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dv_toolkit-0.2.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: dv_toolkit
+Version: 0.2.0
+Summary: a generic and simple toolkit for processing event-based data
+Author: Kuga Maxx
+Author-email: KugaMaxx@outlook.com
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: dv_processing>=2.0
+Requires-Dist: plotly>=5.17
+Requires-Dist: matplotlib>=3.7
+Dynamic: author
+Dynamic: author-email
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

dv_toolkit-0.2.0/README.md

@@ -0,0 +1,268 @@
+# DV Toolkit 
+
+![](https://img.shields.io/github/v/tag/KugaMaxx/yam-toolkit?style=flat-square)
+![](https://img.shields.io/github/license/KugaMaxx/yam-toolkit?style=flat-square)
+
+DV Toolkit is an extension of [dv-processing](https://dv-processing.inivation.com/), 
+providing a series of wrapped modules to help users to do processing and 
+analysis on event camera data. Any questions, please contact me with 
+[KugaMaxx@outlook.com](mailto:KugaMaxx@outlook.com).
+
+<div align=center><img src="https://github.com/KugaMaxx/yam-toolkit/blob/main/assets/images/demonstrate.gif" alt="demonstrate" width="100%"></div>
+
+## Background
+
+### Why create this extension?
+
+The dv-processing library provides convenience for developers to handle event-based data. However, there is still room for improvement in **data reading, slicing, and visualization** during actual usage. Therefore, this repository has made the following improvements:
+
++ Enables fast interoperation between C++ and Python.
++ Adds data alignment and slicing for events, frames, imus, and triggers.
++ Adds offline data reading and processing, eliminating the need for online operations.
++ Implements a more convenient visual interactive interface in Python.
++ Provides a unified usage method for C++ and Python interfaces.
+
+## Installation
+
+### Preliminaries
+
+Since our library is an extension of dv-processing, you need to install dv-processing first. The official installation tutorial is available [here](https://dv-processing.inivation.com/rel_1.7/installation.html), or you can follow the steps below to install it on Ubuntu 20.04:
+
++ Install necessary dependencies that dv-processing required:
+
+    ```bash
+    sudo apt-get install libboost-all-dev libeigen3-dev libopencv-dev
+    sudo apt-get install pybind11-dev python3-dev python3-numpy
+    ```
+
++ Add repository and install dv-processing:
+
+    ```bash
+    sudo add-apt-repository ppa:inivation-ppa/inivation
+    sudo apt-get update
+    sudo apt-get install libcaer-dev libfmt-dev liblz4-dev libzstd-dev libssl-dev libusb-1.0-0-dev
+    sudo apt-get install dv-processing
+    ```
+
+### Git submodule usage
+
+Assuming you are working on a project in Git, you can use this repository as a 
+submodule. Here is an example of placing this repository as a dependency in the
+ `/external` folder.
+
++ Add the repository as a submodule in your project:
+
+    ```bash
+    git submodule add git@github.com:KugaMaxx/yam-toolkit.git external/dv-toolkit
+    ```
+
++ Use in your cmake project:
+
+    ```CMake
+    # Find dv-processing supports
+    find_package(dv-processing REQUIRED)
+
+    # Install toolkit supports.
+    add_subdirectory(external/dv-toolkit)
+
+    # link your targets against the library
+    target_link_libraries(your_target
+        dv::processing
+        dv::toolkit
+        ...)
+    ```
+
+### Python package usage
+
+This repository also allows for Python integration, which can be used by binding 
+it as a Python package before usage. Here is an example in a conda environment 
+named `toolkit`. Please refer to the [README](https://github.com/KugaMaxx/yam-toolkit/blob/main/python/README.md) to get more information.
+
++ Create conda environment and install:
+
+    ```bash
+    # recommend python ≥ 3.8
+    conda create -n toolkit
+
+    # activate environment
+    conda activate toolkit
+
+    # include pybind11 as submodule
+    git submodule update --init
+
+    # install as package
+    pip install .
+    ```
+
++ Import the library in your script:
+
+    ```python
+    # must have
+    import dv_processing as dv
+
+    # introduce extension
+    import dv_toolkit as kit
+    ```
+
+## Getting started
+
+### Standard Type
+
+The dv-toolkit library encapsulates `event`, `frame`, `imu`, and `trigger` into 
+addressable storage types, which supports add, erase and slice operations.
+
++ `dv::toolkit::MonoCameraData` stores all basic storage types of event-based data.
+
+    ```C++
+    #include <dv-toolkit/core/core.hpp>
+
+    int main() {
+        namespace kit = dv::toolkit;
+
+        // Initialize MonoCameraData
+        kit::MonoCameraData data;
+
+        // Access immutable variables through functions, support types are:
+        // events, frames, imus and triggers
+        std::cout << data.events() << std::endl;
+        // "Storage is empty!"
+
+        // Emplace back event elements, the function arguments are:
+        // timestamp, x, y, polarity
+        kit::EventStorage store;
+        store.emplace_back(dv::now(), 0, 0, false);
+        store.emplace_back(dv::now(), 1, 1, true);
+        store.emplace_back(dv::now(), 2, 2, false);
+        store.emplace_back(dv::now(), 3, 3, true);
+
+        // Assignment value to MonoCameraData
+        data["events"] = store;
+
+        // Access mutable variables through std::get
+        std::cout << std::get<kit::EVTS>(data["events"]) << std::endl;
+        // "Storage containing 4 elements within ..."
+
+        return 0;
+    }
+    ```
+
+### I/O Operations
+
+The dv-toolkit library provide convenient method to read and write standard 
+aedat4 files offline. It facilitates the repeated operation and processing on 
+data, avoiding the issue of reading and writing files over and over again.
+
++ `dv::toolkit::MonoCameraReader` reads offline data from standard aedat4 
+files.
+
+    ```C++
+    #include <dv-toolkit/io/reader.hpp>
+
+    int main() {
+        namespace kit = dv::toolkit;
+
+        // Initialize reader
+        kit::io::MonoCameraReader reader("/path/to/aedat4");
+        
+        // Get offline MonoCameraData
+        kit::MonoCameraData data = reader.loadData();
+        
+        // Check all basic types
+        std::cout << data.events()   << std::endl;
+        std::cout << data.frames()   << std::endl;
+        std::cout << data.imus()     << std::endl;
+        std::cout << data.triggers() << std::endl;
+
+        // Get camera resolution
+        // Can also use reader.getEventResolution()
+        const auto resolution = reader.getResolution("events");
+        if (resolution.has_value()) {
+            std::cout << *resolution << std::endl;
+        }
+
+        return 0;
+    }
+    ```
+
++ `dv::toolkit::MonoCameraWrite` write data back to standard aedat4 files.
+
+    ```C++
+    #include <dv-toolkit/core/core.hpp>
+    #include <dv-toolkit/io/reader.hpp>
+    #include <dv-toolkit/io/writer.hpp>
+    #include <dv-toolkit/simulation/generator.hpp>
+
+    int main() {
+        namespace kit = dv::toolkit;
+
+        // Enable literal time expression from the chrono library
+        using namespace std::chrono_literals;
+        
+        // Initialize MonoCameraData
+        kit::MonoCameraData data;
+
+        // Initialize resolution
+        const auto resolution = cv::Size(346, 260);
+
+        // Create sample events
+        data["events"] = kit::simulation::generateSampleEvents(resolution);
+
+        // Initialize MonoCameraWriter
+        kit::io::MonoCameraWriter writer("/path/to/file.aedat4", resolution);
+
+        // Write MonoCameraData
+        writer.writeData(data);
+
+        return 0;
+    }
+    ```
+
+### Unified stream slicing
+
+Thanks to the redefined standard data structure, it is possible to achieve 
+unified slicing of various types of data by using dv-toolkit library.
+
++ `dv::toolkit::MonoCameraSlicer` allows to slice by time or by number. Before registering each slicer, please ensure that the reference type of the slicer
+ is specified.
+
+    ```C++
+    #include <dv-toolkit/core/slicer.hpp>
+    #include <dv-toolkit/io/reader.hpp>
+
+    int main() {
+        namespace kit = dv::toolkit;
+
+        // Initialize reader
+        kit::io::MonoCameraReader reader("/path/to/aedat4");
+        
+        // Get offline MonoCameraData
+        kit::MonoCameraData data = reader.loadData();
+
+        // Initialize slicer, it will have no jobs at this time
+        kit::MonoCameraSlicer slicer;
+
+        // Use this namespace to enable literal time expression from the chrono library
+        using namespace std::chrono_literals;
+
+        // Register this method to be called every 33 millisecond of events
+        slicer.doEveryTimeInterval("events", 33ms, [](const kit::MonoCameraData &mono) {
+            std::cout << mono.events() << std::endl;
+        });
+
+        // Register this method to be called every 2 elements of frames
+        slicer.doEveryNumberOfElements("frames", 2, [](const kit::MonoCameraData &mono) {
+            std::cout << mono.events() << std::endl;
+        });
+
+        // Now push the store into the slicer, the data contents within the store
+        // can be arbitrary, the slicer implementation takes care of correct slicing
+        // algorithm and calls the previously registered callbacks accordingly.
+        slicer.accept(data);
+
+        return 0;
+    }
+    ```
+
+## Acknowledgement
+
+Special thanks to [Jinze Chen](mailto:chjz@mail.ustc.edu.cn).

dv_toolkit-0.2.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel", "numpy>=1.24"]
+build-backend = "setuptools.build_meta"

dv_toolkit-0.2.0/python/src/dv_toolkit/__init__.py

@@ -0,0 +1,2 @@
+from .lib._lib_toolkit import *
+from . import plot

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/__init__.py

@@ -0,0 +1,4 @@
+from .player import OfflineMonoCameraPlayer
+
+
+__all__ = ['OfflineMonoCameraPlayer']

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/player.py

@@ -0,0 +1,80 @@
+from typing import Tuple
+from datetime import timedelta
+
+from ..lib import _lib_toolkit as kit
+
+from .tools import mp_player
+from .tools import go_player
+
+
+class OfflineMonoCameraPlayer(object):
+    def __init__(self, 
+                 resolution: Tuple[int, int], 
+                 mode: str = "hybrid", 
+                 core: str = "matplotlib"):
+        if (len(resolution) == 2):
+            self.resolution = resolution
+        else:
+            raise ValueError("Resolution must be a tuple of length 2.")            
+        
+        if core == "matplotlib":
+            self.core = mp_player
+        elif core == "plotly":
+            self.core = go_player
+        else:
+            raise ValueError("Invalid player core. use 'matplotlib' or 'plotly'")
+        
+        if mode in ["hybrid", "2d", "3d"]:
+            self.mode = mode
+        else:
+            raise ValueError("Invalid view mode. use '2d', '3d' or 'hybrid'")
+
+    def viewPerTimeInterval(self, data, 
+                            reference: str = "events",
+                            interval: timedelta = timedelta(milliseconds=33)):
+        # slice data
+        slicer, packets = kit.MonoCameraSlicer(), list()
+        slicer.doEveryTimeInterval(
+            reference, interval, lambda data: packets.append(data)
+        )
+        slicer.accept(data)
+
+        # run
+        self._run(
+            self.core.Figure(),
+            self.core.Preset(self.resolution, packets)
+        )
+
+    def viewPerNumberInterval(self, data, 
+                              reference: str = "events",
+                              interval: int = 15000):
+        # slice data
+        slicer, packets = kit.MonoCameraSlicer(), list()
+        slicer.doEveryNumberOfElements(
+            reference, interval, lambda data: packets.append(data)
+        )
+        slicer.accept(data)
+        
+        # run
+        self._run(
+            self.core.Figure(),
+            self.core.Preset(self.resolution, packets)
+        )
+
+    def _run(self, figure, preset):
+        figure.set_ticks(preset.get_ticks())
+        if self.mode == "2d":
+            figure.set_subplot(rows=1, cols=1, specs=[[{"type": "2d"}]])
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_2d_frame, set_func=preset.set_2d_plot)
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_2d_event, set_func=preset.set_2d_plot)
+        elif self.mode == "3d":
+            figure.set_subplot(rows=1, cols=1, specs=[[{"type": "3d"}]])
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_3d_frame, set_func=preset.set_3d_plot)
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_3d_event, set_func=preset.set_3d_plot)
+        else:
+            figure.set_subplot(rows=1, cols=2, specs=[[{"type": "2d"}, {"type": "3d"}]])
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_2d_frame, set_func=preset.set_2d_plot)
+            figure.append_trace(row=1, col=1, plot_func=preset.plot_2d_event, set_func=preset.set_2d_plot)
+            figure.append_trace(row=1, col=2, plot_func=preset.plot_3d_frame, set_func=preset.set_3d_plot)
+            figure.append_trace(row=1, col=2, plot_func=preset.plot_3d_event, set_func=preset.set_3d_plot)
+        figure.show()

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/tools/__init__.py

@@ -0,0 +1,5 @@
+from . import go_player
+from . import mp_player
+
+
+__all__ = ['go_player', 'mp_player']

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/tools/func.py

@@ -0,0 +1,56 @@
+import numpy as np
+from abc import ABC, abstractmethod
+
+
+def _unravel_index(index, shape):
+    row, col = np.unravel_index(index, shape)
+    return row, col
+
+
+def _ravel_multi_index(row, col, shape):
+    ind = np.ravel_multi_index(np.array([row, col]), shape)
+    return ind
+
+
+def _reformat_layout(list_of_dict, mapping: dict):
+    for _list in list_of_dict:
+        for _dict in _list:
+            _dict['type'] = mapping[_dict['type']]
+
+    return list_of_dict
+
+
+def _visualize_events(events, size, mode="accumulate"):
+    counts = np.zeros(size)
+    _bins  = [size[0], size[1]]
+    _range = [[0, size[0]], [0, size[1]]]
+
+    # w/ polar
+    if mode == 'polar':
+        counts = np.histogram2d(events.ys(), events.xs(), 
+                                weights=(-1) ** (1 + events.polarities()), 
+                                bins=_bins, range=_range)[0]
+        return counts
+    
+    # w/o polar
+    elif mode == 'monopolar':
+        counts = np.histogram2d(events.ys(), events.xs(), 
+                                weights=(+1) ** (1 + events.polarities()), 
+                                bins=_bins, range=_range)[0]
+        return counts
+    
+    # count before polar assignment
+    elif mode == 'accumulate':
+        counts = np.histogram2d(events.ys(), events.xs(), 
+                                weights=(+1) ** (1 + events.polarities()), 
+                                bins=_bins, range=_range)[0]
+        weight = np.zeros(size)
+        weight[events.ys(), events.xs()] = (-1) ** (1 + events.polarities())
+        return counts * weight
+
+    return counts
+
+def _convert_to_rgba(image):
+    if len(image.shape) == 2:
+        image = np.stack((image,) * 3, axis=-1)
+    return np.concatenate((image, 255 * np.ones((*image.shape[:2], 1))), axis=2)

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/tools/go_player.py

@@ -0,0 +1,247 @@
+import numpy as np
+import dv_processing as dv
+from datetime import datetime
+import plotly.graph_objects as go
+
+from .func import _reformat_layout, _visualize_events
+
+
+class Animator(object):
+    def __init__(self, canvas, update, ticks, fps=25):
+        self._canvas = canvas
+        self._frames = [update(i) for i in range(len(ticks))]
+        self._ticks = ticks
+        self._interval = int(1E3 / fps)
+        self._init_widgets()
+
+    def _init_widgets(self):
+        self._buttons = [{
+            "type": "buttons",
+            "buttons": [
+                {
+                    "method": "animate", "label": "▶",
+                    "args": [None, {"frame": {"duration": self._interval},
+                                    "mode": "immediate", "fromcurrent": True}]
+                },
+                {
+                    "method": "animate", "label": "◼",
+                    "args": [[None], {"frame": {"duration": self._interval},
+                                      "mode": "immediate", "fromcurrent": True}]
+                }
+            ],
+            "x": 0.1, "y": 0.0, "direction": "left", "pad": {"r": 10, "t": 70},
+        }]
+
+        self._sliders = [{
+            "steps": [
+                {
+                    "method": "animate", "label": self._ticks[i],
+                    "args": [[self._ticks[i]], {"frame": {"duration": self._interval},
+                                          "mode": "immediate", "fromcurrent": True}]
+                } for i, val in enumerate(self._frames)
+            ],
+            "x": 0.1, "y": 0.0, "len": 0.9, "pad": {"b": 10, "t": 50},
+        }]
+        self._canvas.layout.update(
+            sliders=self._sliders,
+            updatemenus=self._buttons,
+            template="plotly_white",
+        )
+
+    def run(self):
+        self._canvas.update(frames=self._frames)
+        self._canvas.show()
+
+
+class Figure(object):
+    def __init__(self):
+        self._figure = go.Figure()
+        self._traces = {
+            "inds": list(),
+            "rows": list(),
+            "cols": list(),
+            "plot_func": list(),
+            "set_func": list(),
+            "kwargs": list(),
+        }
+
+        self._index = 0
+        self._nrows = 0
+        self._ncols = 0
+        self._shape = (0, 0)
+        self._layouts = None
+        self._ticks = range(1)
+
+    def set_ticks(self, ticks):
+        self._ticks = ticks
+
+    def set_subplot(self, rows, cols, specs):
+        self._nrows = rows
+        self._ncols = cols
+        self._shape = (rows, cols)
+        self._layouts = _reformat_layout(specs, {'2d': 'xy', '3d': 'scene'})
+
+    def append_trace(self, row, col, plot_func, set_func, **kwargs):
+        self._index = self._index + 1
+        self._traces["rows"].append(row)
+        self._traces["cols"].append(col)
+        self._traces["plot_func"].append(plot_func)
+        self._traces["set_func"].append(set_func)
+        self._traces["kwargs"].append(kwargs)
+        self._traces["inds"].append(self._index - 1)
+
+    def show(self):
+        self._traces["data"] = list()
+        for plot_func, kwargs in zip(self._traces["plot_func"], self._traces["kwargs"]):
+            self._traces["data"].append(plot_func(**kwargs))
+            
+        self._figure.set_subplots(rows=self._nrows, cols=self._ncols, specs=self._layouts)
+        self._figure.add_traces(data=self._traces["data"],
+                                rows=self._traces["rows"], 
+                                cols=self._traces["cols"])
+
+        for set_func, kwargs in zip(self._traces["set_func"], self._traces["kwargs"]):
+            self._figure.layout.update(set_func(**kwargs))
+
+        Animator(canvas=self._figure, update=self._update, ticks=self._ticks).run()
+
+    def _update(self, k):
+        data = list()
+        for obj, plot_func, kwargs in zip(self._traces["data"], self._traces["plot_func"], self._traces["kwargs"]):
+            data.append(plot_func(obj, k, **kwargs))
+        self._traces["data"] = data
+
+        return go.Frame(data=self._traces["data"],
+                        traces=self._traces["inds"], name=self._ticks[k])
+
+
+class Preset(object):
+    def __init__(self, size, packets):
+        """
+        Create a Figure() class with default settings
+        """
+        self._size = size
+        self._packets = packets
+        self._ticks = range(len(packets))
+
+        self._fr_cmap = 'gray'
+        self._ev_cmap = [[0.0, "rgba(223,73,63,1)"],
+                         [0.5, "rgba(0,0,0,0)"],
+                         [1.0, "rgba(46,102,153,1)"]]
+
+    # ---------------- 2d settings ----------------
+    def set_2d_plot(self, **kwargs):
+        return {
+            "xaxis": dict(range=[0, self._size[0]]),
+            "yaxis": dict(range=[0, self._size[1]],
+                          scaleanchor="x",
+                          scaleratio=1.),
+        }
+
+    def plot_2d_event(self, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = go.Heatmap(
+                z=[], zmin=-1, zmax=1,
+                colorscale=self._ev_cmap,
+                showscale=False,
+                showlegend=False,
+            )
+            return obj
+
+        events = self._packets[i].events()
+        if not events.isEmpty():
+            image = _visualize_events(events, self._size[::-1])
+            obj = go.Heatmap(
+                z=np.flip(image, axis=0),
+            )
+        else:
+            obj = go.Heatmap(
+                z=np.zeros(self._size[::-1]),
+            )            
+
+        return obj
+
+    def plot_2d_frame(self, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = go.Heatmap(
+                z=[], zmin=0, zmax=255,
+                colorscale=self._fr_cmap,
+                showscale=False,
+                showlegend=False,
+            )
+            return obj
+
+        frames = self._packets[i].frames()
+        if not frames.isEmpty():
+            image = frames.front().image
+            obj = go.Heatmap(
+                z=np.flip(image, axis=0)
+            )
+            self._tmp_frame = frames.front().image
+        
+        return obj
+
+    # ---------------- 3d settings ----------------
+    def set_3d_plot(self, **kwargs):
+        return {
+            "scene": dict(yaxis=dict(range=[0, self._size[0]]),
+                          zaxis=dict(range=[self._size[1], 0]),
+                          aspectratio=dict(x=1., y=self._size[0]/500, z=self._size[1]/500)),
+        }
+
+    def plot_3d_event(self, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = go.Scatter3d(
+                x=[], y=[], z=[],
+                mode='markers',
+                marker=dict(
+                    size=2,
+                    cmin=0,
+                    cmax=1,
+                    colorscale=self._ev_cmap,
+                ),
+                showlegend=False,
+            )
+            return obj
+        
+        events = self._packets[i].events()
+        if not events.isEmpty():
+            obj = go.Scatter3d(
+                x=[f"{datetime.fromtimestamp(ts * 1E-6).strftime('%H:%M:%S.%f')}"
+                   for ts in events.timestamps()],
+                y=events.xs(), z=events.ys(), 
+                marker=dict(color=events.polarities()),
+            )
+        else:
+            obj = go.Scatter3d(
+                x=[], y=[], z=[]
+            )
+        return obj
+
+    def plot_3d_frame(self, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = go.Surface(
+                x=[], y=[], z=[],
+                surfacecolor=np.full((*self._size, 1), np.nan),
+                colorscale=self._fr_cmap,
+                cmin=0,
+                cmax=255,
+                showscale=False,
+                showlegend=False,
+            )
+            return obj
+
+        frames = self._packets[i].frames()
+        if not frames.isEmpty():
+            for frame in frames:
+                xx, yy = np.mgrid[0:self._size[0], 0:self._size[1]]
+                obj = go.Surface(
+                    x=np.full(self._size, datetime.fromtimestamp(frame.timestamp * 1E-6).strftime('%H:%M:%S.%f')),
+                    y=xx, z=yy,
+                    surfacecolor=np.fliplr(np.rot90(frame.image, -1))
+                )
+
+        return obj
+
+    def get_ticks(self):
+        return self._ticks

dv_toolkit-0.2.0/python/src/dv_toolkit/plot/tools/mp_player.py

@@ -0,0 +1,281 @@
+import itertools
+import numpy as np
+import dv_processing as dv
+from datetime import datetime
+
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+import matplotlib.colors as mcolors
+from matplotlib.animation import FuncAnimation
+from matplotlib.widgets import Button, Slider, TextBox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+
+from .func import _reformat_layout, _ravel_multi_index, _visualize_events, _convert_to_rgba
+
+
+class Animator(FuncAnimation):
+    """
+    Animated interactive plot using matplotlib
+    https://stackoverflow.com/questions/46325447/animated-interactive-plot-using-matplotlib
+    """
+
+    def __init__(self, canvas, update, ticks, fps=25) -> None:
+        self._canvas = canvas
+        self._frames = update
+        self._ticks = ticks
+        self._len = len(ticks) - 1
+        self._pos = -1
+        self._min = 0
+        self._max = self._len if self._len > 0 else 1
+        self._run = True
+        self._forward = True
+        self._interval = int(1E3 / fps)
+        self._init_widgets()
+        super().__init__(self._canvas, self._frames, frames=self._play(), interval=self._interval, save_count=self._len)
+
+    def _init_widgets(self):
+        # add another axes
+        playerax = self._canvas.add_axes([0.13, 0.05, 0.74, 0.04])
+        divider = make_axes_locatable(playerax)
+
+        # create button on axes
+        bax = divider.append_axes("right", size="100%", pad="15%")
+        sax = divider.append_axes("right", size="100%", pad="15%")
+        fax = divider.append_axes("right", size="100%", pad="15%")
+        ofax = divider.append_axes("right", size="100%", pad="15%")
+        sliderax = divider.append_axes("right", size="700%", pad="30%")
+        textax = divider.append_axes("right", size="200%", pad="30%")
+        self.button_oneback = Button(playerax, label='$\u29CF$')
+        self.button_backward = Button(bax, label='$\u25C0$')
+        self.button_pauseplay = Button(sax, label='$\u25A0$')
+        self.button_forward = Button(fax, label='$\u25B6$')
+        self.button_onenext = Button(ofax, label='$\u29D0$')
+        self.slider = Slider(sliderax, '', self._min, self._max, valstep=1)
+        self.text = TextBox(textax, '', color='1.', textalignment='center')
+
+        # create button functions
+        self.button_oneback.on_clicked(self._play_back_frame)
+        self.button_backward.on_clicked(self._play_backwards)
+        self.button_pauseplay.on_clicked(self._set_stop)
+        self.button_forward.on_clicked(self._play_forwards)
+        self.button_onenext.on_clicked(self._play_next_frame)
+        self.slider.on_changed(self._set_position)
+        self.slider.valtext.set_visible(False)
+
+    def run(self, path=None, fps=30):
+        if path is None:
+            plt.show()
+        else:
+            self.save(path, writer='imagemagick', fps=fps)
+
+    # ---------------- call back function ----------------
+    def _play(self):
+        while self._run:
+            self._one_step()
+            yield self._pos
+
+    def _one_step(self):
+        if self._len == 0:
+            self._pos = 0
+            self.event_source.stop()
+        elif 0 < self._pos < self._len:
+            self._pos += self._forward - (not self._forward)
+        elif self._pos <= 0:
+            self._pos += self._forward
+        elif self._pos >= self._len and not self._forward:
+            self._pos -= not self._forward
+        self.slider.set_val(self._pos)
+        self.text.set_val(f"{self._ticks[self._pos]}")
+        self._frames(self._pos)
+        self._canvas.canvas.draw_idle()
+
+    def _play_back_frame(self, event=None):
+        self._run, self._forward = False, False
+        self.event_source.stop()
+        self._one_step()
+
+    def _play_backwards(self, event=None):
+        self._run, self._forward = True, False
+        self.event_source.start()
+
+    def _set_stop(self, event=None):
+        if not self._run:
+            self._run = True
+            self.event_source.start()
+        elif self._run:
+            self._run = False
+            self.event_source.stop()
+
+    def _play_forwards(self, event=None):
+        self._run, self._forward = True, True
+        self.event_source.start()
+
+    def _play_next_frame(self, event=None):
+        self._run, self._forward = False, True
+        self.event_source.stop()
+        self._one_step()
+
+    def _set_position(self, i):
+        self._pos = int(self.slider.val)
+        self.text.set_val(f"{self._ticks[self._pos]}")
+        self._frames(self._pos)
+
+
+class Figure(object):
+    def __init__(self):
+        self._figure = plt.figure(figsize=(16, 9))
+        self._traces = {
+            "inds": list(),
+            "rows": list(),
+            "cols": list(),
+            "plot_func": list(),
+            "set_func": list(),
+            "kwargs": list(),
+            "AxesSubplots": list(),
+            "AxesImages": list(),
+        }
+
+        self._index = 0
+        self._nrows = 0
+        self._ncols = 0
+        self._shape = (0, 0)
+        self._layouts = None
+        self._ticks = range(1)
+
+    def set_ticks(self, ticks):
+        self._ticks = ticks
+
+    def set_subplot(self, rows, cols, specs):
+        self._nrows = rows
+        self._ncols = cols
+        self._shape = (rows, cols)
+        self._layouts = _reformat_layout(specs, {'2d': None, '3d': '3d'})
+
+    def append_trace(self, row, col, plot_func, set_func, **kwargs):
+        self._index = self._index + 1
+        self._traces["rows"].append(row)
+        self._traces["cols"].append(col)
+        self._traces["plot_func"].append(plot_func)
+        self._traces["set_func"].append(set_func)
+        self._traces["kwargs"].append(kwargs)
+        self._traces["inds"].append(_ravel_multi_index(row-1, col-1, self._shape))
+
+    def show(self):
+        ax_list = list()
+        for ind, _layout in enumerate(list(itertools.chain(*self._layouts))):
+            ax_list.append(self._figure.add_subplot(*self._shape, ind+1, projection=_layout["type"]))
+
+        for ind, plot_func, set_func, kwargs \
+            in zip(self._traces["inds"], self._traces["plot_func"], self._traces["set_func"], self._traces["kwargs"]):
+            AxesSubplot = set_func(ax_list[ind], **kwargs)
+            self._traces["AxesSubplots"].append(AxesSubplot)
+            self._traces["AxesImages"].append(plot_func(AxesSubplot, **kwargs))
+
+        Animator(canvas=self._figure, update=self._update, ticks=self._ticks).run()
+
+    def _update(self, k):
+        for i in range(self._index):
+            plot_func = self._traces["plot_func"][i]
+            AxesSubplot, AxesImage = self._traces["AxesSubplots"][i], self._traces["AxesImages"][i]
+            self._traces["AxesImages"][i] = plot_func(AxesSubplot, AxesImage, k, **self._traces["kwargs"][i])
+
+
+class Preset(object):
+    def __init__(self, size, packets) -> None:
+        """
+        Create a Figure() class with default settings
+        """
+        self._size = size
+        self._packets = packets
+        self._ticks = range(len(packets))
+
+        self._fr_cmap = plt.get_cmap('gray')
+        self._ev_cmap = mcolors.LinearSegmentedColormap.from_list("evCmap", [(0.871, 0.286, 0.247, 1.),
+                                                                             (0.000, 0.000, 0.000, 0.),
+                                                                             (0.180, 0.400, 0.600, 1.)])
+
+    # ---------------- 2d settings ----------------
+    def set_2d_plot(self, ax, **kwargs):
+        ax.set_xlim(0, self._size[0])
+        ax.set_ylim(0, self._size[1])
+        ax.set_xticks([])
+        ax.set_yticks([])
+        return ax
+
+    def plot_2d_event(self, ax, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = ax.imshow(
+                np.zeros(self._size[::-1]), 
+                vmin=-1, vmax=1,
+                cmap=self._ev_cmap
+            )        
+            return obj
+
+        events = self._packets[i].events()
+        if not events.isEmpty():
+            image = _visualize_events(events, self._size[::-1])
+            obj.set_data(np.flip(image, axis=0))
+        else:
+            obj.set_data(np.zeros(self._size[::-1]))
+
+        return obj
+
+    def plot_2d_frame(self, ax, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = ax.imshow(
+                np.zeros(self._size[::-1]),
+                vmin=0, vmax=255,
+                cmap=self._fr_cmap
+            )
+            return obj
+        
+        frames = self._packets[i].frames()
+        if not frames.isEmpty():
+            image = frames.front().image
+            obj.set_data(np.flip(image, axis=0))
+        
+        return obj
+
+    # ---------------- 3d settings ----------------
+    def set_3d_plot(self, ax, **kwargs):
+        ax.set_ylim3d(0, self._size[0])
+        ax.set_zlim3d(self._size[1], 0)
+        ax.set_box_aspect((500, self._size[0], self._size[1]))
+        ax.view_init(elev=45, azim=30, roll=0)
+        return ax
+    
+    def plot_3d_event(self, ax, obj=None, i=None, **kwargs):
+        if i is None:
+            obj = ax.scatter([], [], [], c=[], s=1.0, vmin=0, vmax=1, cmap=self._ev_cmap)
+            return obj
+
+        events = self._packets[i].events()
+        if not events.isEmpty():
+            obj._offsets3d = (events.timestamps(), events.xs(), events.ys())
+            obj.set_array(events.polarities())
+            ax.set_xlim3d(events.getLowestTime(), events.getHighestTime())
+            ax.set_xticks(np.linspace(events.getLowestTime(), events.getHighestTime(), 5))
+            ax.set_xticklabels([f"{datetime.fromtimestamp(ts * 1E-6).strftime('%H:%M:%S')}s" 
+                                for ts in ax.get_xticks().tolist()])
+        else:
+            obj._offsets3d = ([], [], [])    
+        
+        return obj
+
+    def plot_3d_frame(self, ax, obj=None, i=None, **kwargs):
+        xx, yy = np.mgrid[0:self._size[0], 0:self._size[1]]
+        if i is None:
+            obj = ax.plot_surface(np.nan, xx, yy, facecolors=np.full((*self._size, 1), np.nan))
+            return obj
+        
+        frames = self._packets[i].frames()
+        if not frames.isEmpty():
+            obj.remove()
+            for frame in frames:
+                image = np.fliplr(np.rot90(_convert_to_rgba(frame.image) / 255.0, -1))
+                obj = ax.plot_surface(frame.timestamp, xx, yy, facecolors=image)
+
+        return obj
+
+    def get_ticks(self):
+        return self._ticks

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: dv_toolkit
+Version: 0.2.0
+Summary: a generic and simple toolkit for processing event-based data
+Author: Kuga Maxx
+Author-email: KugaMaxx@outlook.com
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: dv_processing>=2.0
+Requires-Dist: plotly>=5.17
+Requires-Dist: matplotlib>=3.7
+Dynamic: author
+Dynamic: author-email
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+python/src/dv_toolkit/__init__.py
+python/src/dv_toolkit.egg-info/PKG-INFO
+python/src/dv_toolkit.egg-info/SOURCES.txt
+python/src/dv_toolkit.egg-info/dependency_links.txt
+python/src/dv_toolkit.egg-info/not-zip-safe
+python/src/dv_toolkit.egg-info/requires.txt
+python/src/dv_toolkit.egg-info/top_level.txt
+python/src/dv_toolkit/plot/__init__.py
+python/src/dv_toolkit/plot/player.py
+python/src/dv_toolkit/plot/tools/__init__.py
+python/src/dv_toolkit/plot/tools/func.py
+python/src/dv_toolkit/plot/tools/go_player.py
+python/src/dv_toolkit/plot/tools/mp_player.py

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.24
+dv_processing>=2.0
+plotly>=5.17
+matplotlib>=3.7

dv_toolkit-0.2.0/python/src/dv_toolkit.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+_lib_toolkit
+dv_toolkit

dv_toolkit-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dv_toolkit-0.2.0/setup.py

@@ -0,0 +1,207 @@
+import os
+import re
+import subprocess
+import sys
+import platform
+from pathlib import Path
+
+from setuptools import Extension, setup, find_packages
+from setuptools.command.build_ext import build_ext
+
+global extra_cmake_args
+extra_cmake_args = [
+    "-DTOOLKIT_ENABLE_SAMPLES=OFF",
+    "-DTOOLKIT_ENABLE_PYTHON=ON"
+]
+
+# Convert distutils Windows platform specifiers to CMake -A arguments
+PLAT_TO_CMAKE = {
+    "win32": "Win32",
+    "win-amd64": "x64",
+    "win-arm32": "ARM",
+    "win-arm64": "ARM64",
+}
+
+
+# A CMakeExtension needs a sourcedir instead of a file list.
+# The name must be the _single_ output extension from the CMake build.
+# If you need multiple extensions, see scikit-build.
+class CMakeExtension(Extension):
+
+    def __init__(self, name: str, sourcedir: str = "") -> None:
+        super().__init__(name, sources=[])
+        self.sourcedir = os.fspath(Path(sourcedir).resolve())
+
+
+class CMakeBuild(build_ext):
+
+    def build_extension(self, ext: CMakeExtension) -> None:
+        # Must be in this form due to bug in .resolve() only fixed in Python 3.10+
+        ext_fullpath = Path.cwd() / self.get_ext_fullpath(ext.name)  # type: ignore[no-untyped-call]
+        extdir = ext_fullpath.parent.resolve()
+
+        # Using this requires trailing slash for auto-detection & inclusion of
+        # auxiliary "native" libs
+
+        debug = int(os.environ.get("DEBUG", 0)) if self.debug is None else self.debug
+        cfg = "Debug" if debug else "Release"
+
+        # CMake lets you override the generator - we need to check this.
+        # Can be set with Conda-Build, for example.
+        cmake_generator = os.environ.get("CMAKE_GENERATOR", "")
+
+        # Set Python_EXECUTABLE instead if you use PYBIND11_FINDPYTHON
+        # EXAMPLE_VERSION_INFO shows you how to pass a value into the C++ code
+        # from Python.
+        cmake_args = [
+            f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY={extdir}{os.sep}dv_toolkit/lib",
+            f"-DPYTHON_EXECUTABLE={sys.executable}",
+            f"-DCMAKE_BUILD_TYPE={cfg}",  # not used on MSVC, but no harm
+        ]
+        build_args = []
+        # Adding CMake arguments set as environment variable
+        # (needed e.g. to build for ARM OSx on conda-forge)
+        if "CMAKE_ARGS" in os.environ:
+            cmake_args += [item for item in os.environ["CMAKE_ARGS"].split(" ") if item]
+
+        # In this example, we pass in the version to C++. You might not need to.
+        # cmake_args += [f"-DEXAMPLE_VERSION_INFO={self.distribution.get_version()}"]  # type: ignore[attr-defined]
+
+        # Pass Python3 executable path to CMake after external args (eg. VCPKG toolchain files)
+        cmake_args += [f"-DPython3_EXECUTABLE={sys.executable}"]
+
+        # Add custom CMake arguments needed for build features
+        global extra_cmake_args
+        cmake_args += extra_cmake_args
+
+        if self.compiler.compiler_type != "msvc":
+            # Using Ninja-build since it a) is available as a wheel and b)
+            # multithreads automatically. MSVC would require all variables be
+            # exported for Ninja to pick it up, which is a little tricky to do.
+            # Users can override the generator with CMAKE_GENERATOR in CMake
+            # 3.15+.
+            if not cmake_generator or cmake_generator == "Ninja":
+                try:
+                    import ninja
+
+                    ninja_executable_path = Path(ninja.BIN_DIR) / "ninja"
+                    cmake_args += [
+                        "-GNinja",
+                        f"-DCMAKE_MAKE_PROGRAM:FILEPATH={ninja_executable_path}",
+                    ]
+                except ImportError:
+                    pass
+
+        else:
+            # Single config generators are handled "normally"
+            single_config = any(x in cmake_generator for x in {"NMake", "Ninja"})
+
+            # CMake allows an arch-in-generator style for backward compatibility
+            contains_arch = any(x in cmake_generator for x in {"ARM", "Win64"})
+
+            # Specify the arch if using MSVC generator, but only if it doesn't
+            # contain a backward-compatibility arch spec already in the
+            # generator name.
+            if not single_config and not contains_arch:
+                cmake_args += ["-A", PLAT_TO_CMAKE[self.plat_name]]
+
+            # Multi-config generators have a different way to specify configs
+            if not single_config:
+                cmake_args += [f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_{cfg.upper()}={extdir}"]
+                build_args += ["--config", cfg]
+
+        if sys.platform.startswith("darwin"):
+            # Cross-compile support for macOS - respect ARCHFLAGS if set
+            archs = re.findall(r"-arch (\S+)", os.environ.get("ARCHFLAGS", ""))
+            if archs:
+                cmake_args += ["-DCMAKE_OSX_ARCHITECTURES={}".format(";".join(archs))]
+
+        # Set CMAKE_BUILD_PARALLEL_LEVEL to control the parallel build level
+        # across all generators.
+        if "CMAKE_BUILD_PARALLEL_LEVEL" not in os.environ:
+            # self.parallel is a Python 3 only way to set parallel jobs by hand
+            # using -j in the build_ext call, not supported by pip or PyPA-build.
+            if hasattr(self, "parallel") and self.parallel:
+                # CMake 3.12+ only.
+                build_args += [f"-j{self.parallel}"]
+
+        build_temp = Path(self.build_temp) / ext.name
+        if not build_temp.exists():
+            build_temp.mkdir(parents=True)
+
+        ret = subprocess.run(["cmake", ext.sourcedir, *cmake_args], cwd=build_temp, check=True)
+        print("Called cmake with: " + str(ret.args))
+        ret = subprocess.run(["cmake", "--build", ".", *build_args], cwd=build_temp, check=True)
+        print("Called cmake with: " + str(ret.args))
+
+
+def parse_gplusplus_major_version(gpp_path):
+    try:
+        p = subprocess.Popen([gpp_path, "--version"], stdout=subprocess.PIPE)
+        out, _ = p.communicate()
+        if p.returncode == 0:
+            output_text = out.decode('UTF-8')
+            prog = re.compile(r"^(\S+)\s\(.*\)\s(\d+)\.\d+\.\d+.*")
+            result = prog.match(output_text)
+            if result is not None and result[1][0:3] == "g++":
+                return int(result[2])
+    except FileNotFoundError:
+        pass
+    return None
+
+
+def verify_and_configure_compiler():
+    # This verify and check only relevant on linux
+    if platform.system() != 'Linux':
+        return
+
+    version = parse_gplusplus_major_version("g++")
+    if version is not None and version >= 10:
+        # default compiler seems fine, continue
+        return
+    try:
+        version = parse_gplusplus_major_version(os.environ["CXX"])
+        if version is not None and version >= 10:
+            # A preset compiler found, it seems suitable
+            return
+    except KeyError:
+        pass
+
+    version = parse_gplusplus_major_version("g++-10")
+    if version is not None and version >= 10:
+        global extra_cmake_args
+        print("Detected installation of g++10, it will be used for compilation")
+        extra_cmake_args += ["-DCMAKE_C_COMPILER=gcc-10", "-DCMAKE_CXX_COMPILER=g++-10"]
+        return
+
+    # None of the above worked. Print a warning.
+    print("Compatible GCC compiler was not found.", file=sys.stderr)
+    print("Compiler compatibility verification failed, compilation will use system compiler.", file=sys.stderr)
+    print("This might fail!", file=sys.stderr)
+
+
+# Initial setup
+verify_and_configure_compiler()
+        
+# The information here can also be placed in setup.cfg - better separation of
+# logic and declaration, and simpler if you include description/version in a file.
+setup(
+    name="dv_toolkit",
+    version="0.2.0",
+    author="Kuga Maxx",
+    author_email="KugaMaxx@outlook.com",
+    description="a generic and simple toolkit for processing event-based data",
+    long_description="",
+    ext_modules=[CMakeExtension("_lib_toolkit")],
+    cmdclass={"build_ext": CMakeBuild},
+    zip_safe=False,
+    python_requires=">=3.8",
+    packages=find_packages(where='python/src'),
+    package_dir={'':'python/src'},
+    install_requires=[
+        'numpy>=1.24',
+        'dv_processing>=2.0',
+        'plotly>=5.17',
+        'matplotlib>=3.7'
+    ]
+)