PedestalTrackingPixelHistogram¶

Warning

PedestalTrackingPixelHistogram is specifically designed for use in the Jungfrau calibration pipeline. Make sure you understand the behaviour before using it in other contexts.

PedestalTrackingPixelHistogram accumulates a pixel-wise histogram of frame - pedestal residuals while maintaining a running per-pixel pedestal estimate.

Use push_pedestal_no_update() to seed the pedestal estimate, then update_mean() before submitting frames with fill_async(). Pending asynchronous fills are drained by flush(), and snapshot methods such as values() and pedestal_mean() return numpy arrays.

class aare.PedestalTrackingPixelHistogram¶

Bases: pybind11_object

A pixel-wise histogram of frame - pedestal residuals, with a per-pixel running pedestal estimate sharded across worker threads

bin_centers(self: aare._aare.PedestalTrackingPixelHistogram) → numpy.ndarray¶

Get the bin centers along the residual axis.

Returns:: float32) of bin center values.
Return type:: A 1D numpy array (dtype

bin_edges(self: aare._aare.PedestalTrackingPixelHistogram) → numpy.ndarray¶

Get the bin edges along the residual axis.

Returns:: float32) of bin edge values.
Return type:: A 1D numpy array (dtype

fill_async(self: aare._aare.PedestalTrackingPixelHistogram, image: numpy.typing.NDArray[numpy.uint16]) → None¶

Submit an image for asynchronous filling with sigma-clipped pedestal tracking.

For each pixel the worker pool:

histograms the pedestal-subtracted residual when it falls in [xmin, xmax), and
additionally pushes the raw pixel value back into the per-thread pedestal estimate when abs(residual) < n_sigma * cached_std (the sigma-clipped pedestal-update gate).

The cached std is populated by update_mean(), so push_pedestal_no_update() + update_mean() must have run at least once for the pedestal-update side effect to fire. Setting n_sigma = 0 disables the side effect and recovers plain histogram-only async filling.

The image is copied into an internal buffer before this call returns, so the caller may mutate or free the numpy array immediately. If the internal queue is full this call blocks (with the GIL released) until a slot becomes available.

Parameters:: image – A 2D numpy array of raw pixel values (dtype: uint16)

fill_from_file(self: aare._aare.PedestalTrackingPixelHistogram, fname: os.PathLike | str | bytes, max_frames: SupportsInt | SupportsIndex = -1, verbose: bool = False) → None¶

Fill the histogram from a file.

Parameters:

file_path – Path to the file to fill from
max_frames – Maximum number of frames to fill from the file (default: -1)

flush(self: aare._aare.PedestalTrackingPixelHistogram) → None¶: Block until all images submitted via fill_async() have been merged into the accumulators. Cheap when nothing is pending.

property n_sigma¶: Sigma multiplier used as the pedestal-update gate in fill_async(). Atomic; safe to read or write from any thread. Setting it to 0.0 disables the pedestal update entirely. The new value takes effect on subsequent per-pixel evaluations inside the worker pool.

pedestal_mean(self: aare._aare.PedestalTrackingPixelHistogram) → numpy.ndarray¶

Snapshot the per-pixel pedestal mean stitched together from all shards.

Returns:: float64) containing the current cached pedestal mean.
Return type:: A 2D numpy array (rows x cols, dtype

process_pedestal_file(self: aare._aare.PedestalTrackingPixelHistogram, fname: os.PathLike | str | bytes, max_frames: SupportsInt | SupportsIndex = -1, verbose: bool = False) → None¶

Process a pedestal file.

Parameters:

file_path – Path to the file to process
max_frames – Maximum number of frames to process from the file (default: -1)

push_pedestal_no_update(self: aare._aare.PedestalTrackingPixelHistogram, frame: numpy.typing.NDArray[numpy.uint16]) → None¶

Accumulate frame into the per-pixel running pedestal estimate without refreshing the cached mean.

Use repeatedly while bootstrapping the pedestal, then call update_mean() once before starting to fill the histogram.

Parameters:: frame – A 2D numpy array of raw pixel values (dtype: uint16)

update_mean(self: aare._aare.PedestalTrackingPixelHistogram) → None¶: Refresh each partial pedestal’s cached per-pixel mean from its running sums. Drains pending async fills first, then dispatches the update to the worker pool so the writes to each shard happen on the same thread that reads them in fill_async().

values(self: aare._aare.PedestalTrackingPixelHistogram) → numpy.ndarray¶

Get the histogram data as a numpy array.

Implicitly flushes any pending asynchronous fills before returning, so the snapshot is consistent with everything submitted up to this call.

Returns:: uint16) containing the histogram bins for each pixel.
Return type:: A 3D numpy array (rows x cols x n_bins, dtype