Skip to content

Helper functions

Utility functions and helpers.

FpsTracker

Utility class to track frames per second.

Use tracker.tick() once per update (e.g., per frame). The tracker stores the time differences (dt) between successive tick calls. You can then get the current estimate of FPS through the tracker.fps property.

Parameters:

Name Type Description Default
maxlen

number of time differences to use for FPS calculation. Defaults to 30.

 30
Source code in src\yarppg\helpers.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class FpsTracker:
    """Utility class to track frames per second.

    Use `tracker.tick()` once per update (e.g., per frame). The tracker
    stores the time differences (dt) between successive `tick` calls.
    You can then get the current estimate of FPS through the `tracker.fps`
    property.

    Args:
        maxlen: number of time differences to use for FPS calculation. Defaults to 30.
    """

    def __init__(self, maxlen=30):
        self.last_update = time.perf_counter()
        self.dts = collections.deque(maxlen=maxlen)

    def tick(self):
        """Update tracker (call this once per loop iteration)."""
        now = time.perf_counter()
        self.dts.append(now - self.last_update)
        self.last_update = now

    @property
    def fps(self) -> float:
        """Frames per second calculated from average time difference between updates."""
        if len(self.dts) > 0:
            return 1 / (sum(self.dts) / len(self.dts))
        return 1

fps: float property

Frames per second calculated from average time difference between updates.

tick()

Update tracker (call this once per loop iteration).

Source code in src\yarppg\helpers.py 
70
71
72
73
74
def tick(self):
    """Update tracker (call this once per loop iteration)."""
    now = time.perf_counter()
    self.dts.append(now - self.last_update)
    self.last_update = now

bpm_from_frames_per_beat(hr, fps)

Convert frames per beat to beats per minute (60 * fps / hr).

Source code in src\yarppg\helpers.py 
49
50
51
def bpm_from_frames_per_beat(hr: ArrayLike, fps: float) -> np.ndarray:
    """Convert frames per beat to beats per minute (60 * fps / hr)."""
    return 60 * fps / np.asarray(hr)

frames_from_video(filename)

Read and yield frames from a video file.

Source code in src\yarppg\helpers.py 
29
30
31
32
33
34
35
36
def frames_from_video(filename: str | pathlib.Path) -> Iterator[np.ndarray]:
    """Read and yield frames from a video file."""
    cap = cv2.VideoCapture(str(filename))
    while True:
        ret, frame = cap.read()
        if not ret:
            break
        yield frame

get_cached_resource_path(filename, url, reload=False)

Download a file from the web and store it locally.

Source code in src\yarppg\helpers.py 
16
17
18
19
20
21
22
23
24
25
26
def get_cached_resource_path(filename: str, url: str, reload: bool = False):
    """Download a file from the web and store it locally."""
    RESOURCE_DIR.mkdir(exist_ok=True)
    local_file = RESOURCE_DIR / filename
    if not local_file.exists() or reload:
        urllib.request.urlretrieve(url, filename=str(local_file))
        if not local_file.exists():
            raise FileNotFoundError(
                f"Something went wrong when getting {filename=:!r} from {url=:!r}."
            )
    return local_file

get_video_fps(filename)

Find the frame rate of the given video file.

Source code in src\yarppg\helpers.py 
39
40
41
42
43
44
45
46
def get_video_fps(filename: str | pathlib.Path) -> float:
    """Find the frame rate of the given video file."""
    if not pathlib.Path(filename).exists():
        raise FileNotFoundError(f"{filename=!r} not found.")
    cap = cv2.VideoCapture(str(filename))
    fps = cap.get(cv2.CAP_PROP_FPS)
    cap.release()
    return fps