evutils.vis.plot3d#

Matplotlib 3D visualization utilities for event data.

This module provides functions to plot event streams, 3D histograms, and time surfaces using matplotlib’s 3D plotting capabilities.

cv2 and matplotlib are imported lazily, inside the functions that use them, so import evutils.vis (and importing this module) stays cheap and does not drag in OpenCV / the full matplotlib stack.

Functions#

plot_3d(→ tuple[Optional[matplotlib.figure.Figure], ...)

Plot a 3D scatter plot of events.

plot_3d_histogram(...)

Plot a 3D histogram of events.

plot_3d_timesurface(...)

Plot a 3D time surface of events.

Module Contents#

evutils.vis.plot3d.plot_3d(events: numpy.ndarray, width: int = 1280, height: int = 720, colormap: str | matplotlib.colors.Colormap = 'Spectral', time_scale: float = 1000.0, time_unit: str = 'ms', fig: matplotlib.figure.Figure | None = None, ax: mpl_toolkits.mplot3d.Axes3D | None = None) → tuple[matplotlib.figure.Figure | None, mpl_toolkits.mplot3d.Axes3D | None][source]#

Plot a 3D scatter plot of events.

Parameters:

  • events (np.ndarray) – Array of events with fields ‘t’, ‘x’, ‘y’, and ‘p’.

  • width (int, optional) – Width of the event frame, by default 1280.

  • height (int, optional) – Height of the event frame, by default 720.

  • colormap (Union[str, Colormap], optional) – Colormap to use for the event polarities, by default ‘Spectral’.

  • fig (Optional[plt.Figure], optional) – Matplotlib figure to plot on, by default None (a new figure will be created).

  • ax (Optional[Axes3D], optional) – Matplotlib 3D axis to plot on, by default None (a new axis will be created).

  • time_scale (float)

  • time_unit (str)

Returns:

A tuple containing the figure and axis objects.

Return type:

tuple

Raises:

ValueError – If the colormap is not found or invalid.

evutils.vis.plot3d.plot_3d_histogram(histogram: numpy.ndarray, down_sample: int = 4, fig: matplotlib.figure.Figure | None = None, ax: mpl_toolkits.mplot3d.Axes3D | None = None) → tuple[matplotlib.figure.Figure | None, mpl_toolkits.mplot3d.Axes3D | None][source]#

Plot a 3D histogram of events.

Parameters:

  • histogram (np.ndarray) – 3D histogram array with shape (depth, height, width).

  • down_sample (int, optional) – Downsampling factor for the histogram, by default 4.

  • fig (Optional[plt.Figure], optional) – Matplotlib figure to plot on, by default None (a new figure will be created).

  • ax (Optional[Axes3D], optional) – Matplotlib 3D axis to plot on, by default None (a new axis will be created).

Returns:

A tuple containing the figure and axis objects.

Return type:

tuple

evutils.vis.plot3d.plot_3d_timesurface(events: numpy.ndarray, width: int = 1280, height: int = 720, tau: int = 10000, fig: matplotlib.figure.Figure | None = None, ax: mpl_toolkits.mplot3d.Axes3D | None = None) → tuple[matplotlib.figure.Figure | None, mpl_toolkits.mplot3d.Axes3D | None][source]#

Plot a 3D time surface of events.

Parameters:

  • events (np.ndarray) – Array of events with fields ‘t’, ‘x’, ‘y’, and ‘p’.

  • width (int, optional) – Width of the event frame, by default 1280.

  • height (int, optional) – Height of the event frame, by default 720.

  • tau (int, optional) – Time constant for the time surface exponential decay in microseconds, by default 10_000.

  • fig (Optional[plt.Figure], optional) – Matplotlib figure to plot on, by default None (a new figure will be created).

  • ax (Optional[Axes3D], optional) – Matplotlib 3D axis to plot on, by default None (a new axis will be created).

Returns:

A tuple containing the figure and axis objects.

Return type:

tuple