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

1"""Module for generating Time-Ordered Recent Event (TORE) representations from events.""" 

2 

3import numpy as np 

4from ..jit import lazy_njit_unwrapped_events 

5from ..types import EventArray 

6 

7@lazy_njit_unwrapped_events 

8def _tore_jit(t, x, y, p, tore_fifo, tore_fifo_idx, t_res, tau): 

9 height, width, n_events, _ = tore_fifo.shape 

10 for i in range(len(t) - 1, -1, -1): 

11 xi = x[i] 

12 yi = y[i] 

13 pi = p[i] 

14 ti = t[i] 

15 if 0 <= xi < width and 0 <= yi < height: 

16 k_idx = tore_fifo_idx[yi, xi, pi] 

17 tore_fifo_idx[yi, xi, pi] -= 1 

18 if k_idx >= 0: 

19 dt = max(0.0, float(t_res - ti)) 

20 tore_fifo[yi, xi, k_idx, pi] = np.exp(-dt / tau) 

21 

22def tore(events: 'np.ndarray | EventArray', width: int = 1280, height: int = 720, n_events: int = 4, tau: int = 10_000, dtype: np.dtype | type = np.uint8) -> np.ndarray: 

23 """Generate a TORE from the events. 

24 

25 Parameters 

26 ---------- 

27 events : np.ndarray 

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

29 width : int, optional 

30 Width of the frame, by default 1280 

31 height : int, optional 

32 Height of the frame, by default 720 

33 n_events : int, optional 

34 Number of events to keep in the TORE, by default 4 

35 tau : int, optional 

36 Time constant for the exponential decay, by default 10_000 

37 dtype : np.dtype, optional 

38 Data type of the output array, by default np.uint8 

39  

40 Returns 

41 ------- 

42 np.ndarray 

43 A numpy array with the TORE representation (height, width, n_events, 2) 

44 

45 Examples 

46 -------- 

47 >>> import numpy as np 

48 >>> from evutils.dense import tore 

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

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

51 >>> frame = tore(events, width=100, height=100, n_events=4) 

52 >>> frame.shape 

53 (100, 100, 4, 2) 

54 

55 [1] Baldwin, R. W., Liu, R., Almatrafi, M., Asari, V., & Hirakawa, K. (2022). Time-ordered recent event (tore) volumes for event cameras. IEEE Transactions on Pattern Analysis and Machine Intelligence, 45(2), 2519-2532. 

56 

57 """ 

58 tore_fifo = np.zeros((height, width, n_events, 2), dtype=np.float32) 

59 

60 if len(events) == 0: 

61 return tore_fifo 

62 

63 tore_fifo_idx = np.full((height, width, 2), n_events - 1, dtype=np.int32) 

64 

65 t_res = events['t'][-1] 

66 

67 _tore_jit(events, tore_fifo, tore_fifo_idx, t_res, tau) 

68 

69 return tore_fifo