FastPedestal

FastPedestal calculates a running mean and standard deviation for each pixel in a series of frames. The python binding only exposes uint16 input but the underlying C++ class is templated. Initialize it with n_samples frames using add_init_frame(). Once ready is true, use push_ema() to update the exponential moving average initialized by the mean and with smoothing factor 1/n_samples.

Warning

FastPedestal is not usable until you have added n_samples initial frames with add_init_frame(raw). You can check the state with ready.

The public factory selects the bound C++ specialization from dtype:

  • numpy.float64 creates FastPedestal_d

  • numpy.float32 creates FastPedestal_f

  • numpy.int16 creates FastPedestal_i16

Internal moments and variance are calculated in double precision. Variance is private and stays in double precision through the square root; the cached mean and on-demand standard deviation are returned in the specified type. Negative variance caused by floating-point roundoff is clamped to zero.

Factory

aare.FastPedestal(rows, cols, n_samples=1000, dtype=<class 'numpy.float64'>)

Create an empty per-pixel running pedestal.

This factory hides the dtype suffix used by the templated C++ bindings. Call add_init_frame() exactly n_samples times before using the statistics or calling push_ema(). Subsequent frames have weight 1 / n_samples in the running mean and population variance.

Parameters:

  • rows – Number of image rows.

  • cols – Number of image columns.

  • n_samples – Initialization frame count and steady-state update-weight denominator.

  • dtype – Output dtype for the mean and standard deviation. Supported values are np.float64, np.float32, and np.int16.

Loading from a file

FastPedestal.from_file() initializes the pedestal from n_samples frames after skip_first, then applies steady-state updates for any frames remaining in the file. The input frames must contain uint16 data; dtype selects the output type of the pedestal statistics.

aare.FastPedestal.from_file(filename, n_samples=1000, skip_first=0, dtype=<class 'numpy.float64'>)

Create a FastPedestal from frames in a file.

After ignoring skip_first frames, the next n_samples frames initialize the pedestal. Every remaining frame is then applied as a steady-state update. Input frames are read as uint16 data.

Parameters:

  • filename – Input image file.

  • n_samples – Number of frames used for initialization.

  • skip_first – Number of leading frames to ignore.

  • dtype – Output dtype for the mean and standard deviation.

Raises:

RuntimeError – If fewer than n_samples frames remain after skip_first or n_samples is zero.

pedestal = FastPedestal.from_file(
    "frames.npy", n_samples=100, skip_first=10, dtype=np.float32
)

Example

import numpy as np
from aare import FastPedestal

pedestal = FastPedestal(512, 1024, n_samples=100, dtype=np.float32)

# Initialize with n_samples frames
for frame in initialization_frames:
    pedestal.add_init_frame(frame)

# Now we can push a frame for pedestal update
if pedestal.ready:
    pedestal.push_ema(next_frame)

# Mean and std are  also ready
mean = pedestal.mean()
noise = pedestal.std()

# Direct pedestal subtraction is also supported
for frame in raw_data:
    image = frame - pedestal

Complete API

The API below is for the float64 specialization. All dtype variants share the same API.

class aare._aare.FastPedestal_d

Bases: pybind11_object

Maintain a per-pixel running mean and population standard deviation.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: aare._aare.FastPedestal_d, rows: typing.SupportsInt | typing.SupportsIndex, cols: typing.SupportsInt | typing.SupportsIndex, n_samples: typing.SupportsInt | typing.SupportsIndex) -> None

Construct an empty pedestal. It becomes ready after n_samples calls to add_init_frame().

  1. __init__(self: aare._aare.FastPedestal_d, rows: typing.SupportsInt | typing.SupportsIndex, cols: typing.SupportsInt | typing.SupportsIndex) -> None

Construct an empty pedestal with n_samples=1000.

add_init_frame(self: aare._aare.FastPedestal_d, frame: numpy.typing.NDArray[numpy.uint16]) → None

Accumulate one uint16 initialization frame. Call exactly n_samples times to make the pedestal ready.

clear(self: aare._aare.FastPedestal_d) → None

Reset all statistics and initialization state to zero.

clone(self: aare._aare.FastPedestal_d) → aare._aare.FastPedestal_d

Return an independent copy of the pedestal and its state.

property cols

Number of image columns.

property cur_samples

Number of initialization frames accumulated. Steady-state pushes do not change it.

static from_file(filename: os.PathLike | str | bytes, n_samples: SupportsInt | SupportsIndex = 1000, skip_first: SupportsInt | SupportsIndex = 0) → aare._aare.FastPedestal_d

Create a pedestal from a uint16 file. Skip skip_first frames, use the next n_samples for initialization, then apply every remaining frame as a steady-state update.

mean(self: aare._aare.FastPedestal_d) → numpy.ndarray

Return a copy of the cached mean. The pedestal must be ready.

property n_samples

Initialization frame count and steady-state update-weight denominator.

push_ema(self: aare._aare.FastPedestal_d, frame: numpy.typing.NDArray[numpy.uint16]) → None

Update exponential moving average. The pedstal must already be ready for this update.

property ready

Whether n_samples initialization frames have been accumulated.

property rows

Number of image rows.

std(self: aare._aare.FastPedestal_d) → numpy.ndarray

Return the population standard deviation as a NumPy array. The pedestal must be ready.

view(self: object) → object

Return a non-owning, non-writable NumPy view of the cached mean. The pedestal must be ready.