计时与媒体工具

genesis.utils.tools 模块提供用于循环计时和保存媒体的轻量辅助函数，在 gs.utils.tools 下暴露。

计时

class genesis.utils.tools.Timer(skip=False, level=0, qd_sync=False)

genesis.utils.tools.create_timer(name=None, new=False, level=0, qd_sync=False, skip_first_call=False)

class genesis.utils.tools.Rate(rate)

Fixed-frequency loop limiter: call sleep once per iteration to hold the loop at rate Hz.

Each wake-up is scheduled against an ideal clock advanced by exactly the periods slept per tick, rather than from the actual (over-slept) wake time, so time.sleep overshoot does not accumulate and the average rate stays on target. When an iteration runs longer than the periods it sleeps, the limiter does not sleep and resets its schedule from the current time, so a loop that cannot keep up simply runs as fast as it can without building a sleep debt to burn off afterwards. period may be changed between two ticks, the next one following the new value.

property rate

The frequency in Hz the loop is held at.

advance(n_periods=1)

Schedule the next tick ‘n_periods’ periods after the previous one, and return the time left until it.

The time left is 0 when the loop is behind, and the schedule then starts anew from the current time. A caller that waits the time left in a way of its own, such as keeping a window responsive (see ‘Viewer.sleep’), uses it in place of ‘sleep’.

sleep(n_periods=1)

Sleep until ‘n_periods’ periods have passed since the previous tick, or not at all if they already have.

class genesis.utils.tools.StepTimer

Times the phases of the steps of a stepped process.

A step opens with start, its phases run under phase, named freely, or between start_phase and the next start_phase or stop_phase where a with block would indent too much, and step closes it. A closed step leaves in timings, until the next one, the wall time of every phase it timed, of the whole step under step, and of the period from the start of the previous step to its own under period. The period covers the time spent between the two steps as well, so its inverse is the rate the loop achieves. A step that start opens and step never closes leaves no trace, as the next start discards it. The first step has no period. The code timing a phase declares it with add_phases before the first step, so that a log laid out once lists every phase a step may time.

property phases: tuple[str, ...]

Every phase a step may time, step and period first, in declaration order (see add_phases).

add_phases(*phases: str)

Declare phases the steps time, ahead of the first step.

property timings: dict[str, float]

Wall time in seconds of every phase the latest recorded step timed, by phase, empty before any.

start()

Open a step: the phases timed from here on belong to it.

start_phase(phase: str)

Time the code that follows as part of a phase, until the next start_phase or stop_phase.

It lets a loop time each of its iterations under its own phase without a with block. A phase running from a previous start_phase stops here.

stop_phase()

Stop the phase start_phase opened, adding its time to what the phase already took in this step.

phase(phase: str)

Time the enclosed code as part of a phase of the current step, adding to what the phase already took.

Blocks nest, each adding to its own phase.

step()

Close the step, keeping its timings in timings until the next one.

class genesis.utils.tools.RunningMean(window: int | None = None, alpha: float | None = None)

Mean of a scalar fed one sample at a time, over the latest samples or exponentially weighted.

Exactly one of ‘window’ and ‘alpha’ is given. With ‘window’, ‘value’ is the mean of the latest ‘window’ samples, NaN until that many have arrived, and it follows a change fully after that many samples. With ‘alpha’, it is the exponential moving average, the value so far weighing ‘alpha’ and each new sample ‘1 - alpha’, starting from the first sample and NaN before it: it never forgets a sample entirely, and costs nothing per sample whatever the smoothing.

update(sample: float)

Add a sample.

property value: float

The mean of the samples so far, NaN until there are enough of them (see the class).

媒体

genesis.utils.tools.animate(imgs, filename=None, fps=60)

Create a video from a list of images.

Parameters:

• imgs (list) – List of input images.

• filename (str, optional) – Name of the output video file. If not provided, the name will default to the name of the script the process was launched from, with a timestamp and ‘.mp4’ extension.

genesis.utils.tools.save_img_arr(arr, filename='img.png')

另请参阅

• 记录与回放：把仿真数据记录到文件和图表中。