ClusterFinder

template<typename ClusterType = Cluster<int32_t, 3, 3>, typename FRAME_TYPE = uint16_t, typename PEDESTAL_TYPE = double, typename = std::enable_if_t<no_2x2_cluster<ClusterType>::value>>
class ClusterFinder

Find fixed-size photon clusters using a per-pixel pedestal and noise threshold.

Template Parameters:

  • ClusterType – Output cluster type; both dimensions must exceed 2.

  • FRAME_TYPE – Input pixel type.

  • PEDESTAL_TYPE – Type used for pedestal and threshold calculations.

Public Functions

inline ClusterFinder(Shape<2> image_size, PEDESTAL_TYPE nSigma = 5.0, size_t capacity = 1000000, size_t min_pedestal_samples = 1000)

Construct a cluster finder with an empty pedestal.

Parameters:

  • image_size – Image shape as (rows, columns).

  • nSigma – Per-pixel noise threshold multiplier.

  • capacity – Initial cluster-vector capacity.

  • min_pedestal_samples – Minimum number of pedestal frames to accumulate to get reasonable statistics

inline void set_nSigma(PEDESTAL_TYPE nSigma)

Set the noise multiplier used for threshold calculation.

The threshold is recomputed immediately if the pedestal is ready, otherwise when the pedestal becomes ready.

Parameters:

nSigma – New per-pixel noise multiplier.

inline PEDESTAL_TYPE get_nSigma() const

Return the current noise multiplier used for threshold calculation.

inline void push_pedestal_frame(NDView<FRAME_TYPE, 2> frame)

Add a dark frame to the pedestal estimator.

The threshold is initialized automatically when the pedestal first becomes ready. Later frames update the ready pedestal.

Parameters:

frame – Dark frame matching the configured image shape.

Throws:

std::runtime_error – if the frame shape does not match.

inline NDArray<PEDESTAL_TYPE, 2> pedestal()

Return a copy of the per-pixel pedestal mean.

inline NDArray<PEDESTAL_TYPE, 2> noise()

Return the per-pixel pedestal standard deviation (noise).

inline void clear_pedestal()

Clear the pedestal and mark it as not ready.

inline bool pedestal_ready() const

Return whether enough pedestal frames have been pushed to find clusters.

inline void update_threshold()

Recompute the threshold as noise multiplied by nSigma.

Throws:

std::runtime_error – if the pedestal is not ready.

inline ClusterVector<ClusterType> steal_clusters(bool realloc_same_capacity = false)

Move out all accumulated clusters and reset the internal vector.

Parameters:

realloc_same_capacity – Preserve the previous capacity when true.

Returns:

The accumulated clusters and their frame metadata.

inline void find_clusters(NDView<FRAME_TYPE, 2> frame, uint64_t frame_number = 0)

Find clusters in one frame and update eligible pedestal pixels.

Note

Clusters accumulate until steal_clusters() is called.

Parameters:

  • frame – Input frame matching the configured image shape.

  • frame_number – Metadata assigned to the accumulated clusters.

Throws:

std::runtime_error – if the pedestal is not ready.

Pre:

frame has the same shape as image_size passed to the constructor.