Coverage for src/evutils/dense/_voxel.py: 100%

1 

2"""Module for generating voxel grid representations from events.""" 

3 

4from ._histogram import histogram 

5from ..chunking import window_delta_t 

6 

7import numpy as np 

8 

9from ..types import EventArray 

10 

11def voxel_histogram(events: 'np.ndarray | EventArray', width: int = 1280, height: int = 720, n_bins: int = 10, dt: int = 10_000, dtype: np.dtype | type = np.uint8) -> np.ndarray: 

12 """Generate a voxel grid from the events. 

13 

14 Parameters 

15 ---------- 

16 events : np.ndarray 

17 Array of events in the :class:`~evutils.types.Events` format. 

18 width : int, optional 

19 Width of the voxel grid, by default 1280. 

20 height : int, optional 

21 Height of the voxel grid, by default 720. 

22 n_bins : int, optional 

23 Number of depth bins (time slices) in the voxel grid, by default 10. 

24 dt : int, optional 

25 Time delta in microseconds for events buffer by default 10_000 (10 ms). 

26 dtype : np.dtype, optional 

27 Data type of the output voxel grid, by default np.uint8. 

28 

29 Returns 

30 ------- 

31 np.ndarray 

32 A numpy array with the voxel grid (n_bins, height, width, 3). 

33 

34 Examples 

35 -------- 

36 >>> import numpy as np 

37 >>> from evutils.dense import voxel_histogram 

38 >>> events = np.array([(10, 20, 100, 1), (15, 25, 200, 0), (20, 30, 10000, 1)], 

39 ... dtype=[('x', '<u2'), ('y', '<u2'), ('t', '<i8'), ('p', 'i1')]) 

40 >>> grid = voxel_histogram(events, width=100, height=100, n_bins=10, dt=10000) 

41 >>> grid.shape 

42 (10, 100, 100, 3) 

43 """ 

44 buffer = np.zeros((n_bins, height, width, 3), dtype=dtype) 

45 

46 if len(events) <= 2: 

47 return buffer 

48 

49 if events['t'][-1] - events['t'][0] > dt: 

50 raise ValueError(f"Events span a duration greater than dt ({dt}).") 

51 

52 bin_dt = dt // n_bins # Time per bin in microseconds 

53 

54 for i, e in enumerate(window_delta_t(events, delta_t=bin_dt)): 

55 if i >= n_bins: 

56 break 

57 hist = histogram(e, width=width, height=height, fill=False, dtype=dtype) 

58 

59 # Only keep the r and b channels 

60 buffer[i] = hist 

61 

62 return buffer