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

1 

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

3 

4import numpy as np 

5from ..jit import lazy_njit_unwrapped_events 

6from ..types import EventArray 

7 

8@lazy_njit_unwrapped_events 

9def _timesurface_jit(t, x, y, p, buffer, t_ref, tau): 

10 height, width = buffer.shape 

11 for i in range(len(t)): 

12 xi = x[i] 

13 yi = y[i] 

14 ti = t[i] 

15 pi = p[i] 

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

17 dt = max(0.0, float(t_ref - ti)) 

18 value = np.exp(-dt / tau) 

19 if pi == 0: 

20 value = -value 

21 buffer[yi, xi] = value 

22 

23def timesurface(events: 'np.ndarray | EventArray', width: int = 1280, height: int = 720, tau: int = 10_000, dtype: np.dtype | type = np.float32) -> np.ndarray: 

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

25 

26 Parameters 

27 ---------- 

28 events : np.ndarray 

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

30 width : int, optional 

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

32 height : int, optional 

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

34 tau : int, optional 

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

36 dtype : np.dtype, optional 

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

38 

39 Returns 

40 ------- 

41 np.ndarray 

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

43 

44 Examples 

45 -------- 

46 >>> import numpy as np 

47 >>> from evutils.dense import timesurface 

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

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

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

51 >>> frame.shape 

52 (100, 100) 

53 

54 [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 

55 

56 """ 

57 # Initialize the buffer 

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

59 

60 if len(events) < 1: 

61 return buffer 

62 

63 # Last event timestamp 

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

65 

66 _timesurface_jit(events, buffer, t_ref, tau) 

67 

68 return buffer 

69 

70 """"""