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

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

2 

3import numba 

4import numpy as np 

5 

6 

7from typing import Any 

8 

9@numba.njit 

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

11 """Generate a TORE from the events. 

12 

13 Parameters 

14 ---------- 

15 events : np.ndarray 

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

17 width : int, optional 

18 Width of the frame, by default 1280 

19 height : int, optional 

20 Height of the frame, by default 720 

21 n_events : int, optional 

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

23 tau : int, optional 

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

25 dtype : np.dtype, optional 

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

27  

28 Returns 

29 ------- 

30 np.ndarray 

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

32 

33 Examples 

34 -------- 

35 >>> import numpy as np 

36 >>> from evutils.repr import tore 

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

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

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

40 >>> frame.shape 

41 (100, 100, 4, 2) 

42 

43 [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. 

44 

45 """ 

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

47 

48 if len(events) == 0: 

49 return tore_fifo 

50 

51 

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

53 

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

55 

56 for i in range(len(events) -1, -1, -1): 

57 e = events[i] 

58 x = e['x'] 

59 y = e['y'] 

60 p = e['p'] 

61 

62 k_idx = tore_fifo_idx[y, x, p] 

63 tore_fifo_idx[y, x, p] -= 1 

64 

65 

66 if k_idx >= 0: 

67 tore_fifo[y, x, k_idx, p] = np.exp(-(t_res - e['t'])/tau) 

68 

69 

70 return tore_fifo