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

1 

2"""Module for generating time surface representations from events.""" 

3 

4import numpy as np 

5import numba 

6from typing import Any 

7 

8@numba.njit 

9def timesurface(events: np.ndarray, width: int = 1280, height: int = 720, tau: int = 10_000, dtype: Any = np.float32) -> np.ndarray: 

10 """Generate a time surface frame from the events. 

11 

12 Parameters 

13 ---------- 

14 events : np.ndarray 

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

16 width : int, optional 

17 Width of the time surface frame, by default 1280. 

18 height : int, optional 

19 Height of the time surface frame, by default 720. 

20 tau : int, optional 

21 Time constant for the exponential decay, by default 10_000 (10 ms). 

22 dtype : np.dtype, optional 

23 Data type of the output frame, by default np.uint8. 

24 

25 Returns 

26 ------- 

27 np.ndarray 

28 A numpy array with the time surface frame (height, width). 

29 

30 Examples 

31 -------- 

32 >>> import numpy as np 

33 >>> from evutils.repr import timesurface 

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

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

36 >>> frame = timesurface(events, width=100, height=100) 

37 >>> frame.shape 

38 (100, 100) 

39 

40 [1] Lagorce et al. 2016, Hots: a hierarchy of event-based time-surfaces for pattern recognition https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7508476 

41 

42 """ 

43 # Initialize the buffer 

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

45 

46 if len(events) < 1: 

47 return buffer 

48 

49 # Last event timestamp 

50 t_ref = events[-1]['t'] 

51 

52 for e in events: 

53 x = e['x'] 

54 y = e['y'] 

55 t = e['t'] 

56 p = e['p'] 

57 

58 value = np.exp(-(t_ref - t) / tau) 

59 

60 # If polarity is 1, we keep the value as is, flip it if polarity is 0 

61 if p == 0: 

62 value = -value 

63 

64 # Update the buffer 

65 buffer[y, x] = value 

66 

67 

68 return buffer 

69 

70 """"""