ClusterVector¶

A ClusterVector stores fixed-size clusters contiguously. Since it is templated in C++, each bound class has a suffix indicating the cluster type. The suffix follows the same pattern as ClusterFile; for example, ClusterVector_Cluster3x3i stores 3x3 clusters with 32-bit integer pixels.

The intended use case is to pass a ClusterVector to C++ functions that support it or to view it as a NumPy array.

View ClusterVector as a NumPy array

from aare import ClusterFile
with ClusterFile("path/to/file") as f:
    cluster_vector = f.read_frame()

# Create a copy of the cluster data in a numpy array
clusters = np.array(cluster_vector)

# Avoid copying the data by passing copy=False
clusters = np.array(cluster_vector, copy=False)

Warning

A NumPy array created with copy=False is a view of the ClusterVector’s current storage. Do not call push_back or otherwise change the ClusterVector while using the view. A push_back that reallocates the backing buffer leaves existing NumPy views pointing to invalid memory, and appending without reallocation does not update their shape. Use copy=True if the ClusterVector may change after creating the array.

class aare.ClusterVector(cluster_size=(3, 3), dtype=<class 'numpy.int32'>)¶

Create an empty ClusterVector for a supported cluster size and pixel dtype.

Parameters:

cluster_size (tuple[int, int], default=(3, 3)) – Cluster dimensions in the x and y directions.
dtype (numpy.dtype, default=numpy.int32) – Pixel storage type. The cluster size and dtype combination must have a compiled binding.

Returns:

An empty vector with frame number 0 and space reserved for at least 1024 clusters.

Return type:

ClusterVector

Raises:

ValueError – If the requested size and dtype combination is unavailable.

Examples

>>> import numpy as np
>>> from aare import ClusterVector
>>> clusters = ClusterVector(cluster_size=(3, 3), dtype=np.float64)

Below is the API of ClusterVector_Cluster3x3i. All variants share the same API.

class aare._aare.ClusterVector_Cluster3x3i¶

Bases: pybind11_object

A contiguous, move-only container of fixed-size clusters.

The class supports the Python buffer protocol, so numpy.array can either copy its data or create a zero-copy view. A zero-copy view is valid only while the ClusterVector’s underlying allocation and size remain unchanged.

__call__(self: aare._aare.ClusterVector_Cluster3x3i, mask: numpy.typing.NDArray[numpy.bool]) → aare._aare.ClusterVector_Cluster3x3i¶

Return a filtered copy of this ClusterVector.

Parameters:: mask (numpy.ndarray) – One-dimensional, writable, C-contiguous array with dtype numpy.bool_ and one element per cluster.
Returns:: Selected clusters in their original order. The frame number is preserved.
Return type:: ClusterVector

__init__(self: aare._aare.ClusterVector_Cluster3x3i) → None¶: Create an empty ClusterVector with frame number 0 and space reserved for at least 1024 clusters.

property capacity¶: Number of clusters that fit without reallocation.

property cluster_size_x¶: Cluster size in the x dimension.

property cluster_size_y¶: Cluster size in the y dimension.

empty(self: aare._aare.ClusterVector_Cluster3x3i) → bool¶: Return True when no clusters are stored.

property fmt¶: PEP 3118 format string for one stored cluster.

property frame_number¶: Signed 32-bit frame number; 0 can indicate clusters from multiple frames.

item_size(self: aare._aare.ClusterVector_Cluster3x3i) → int¶: Return the size in bytes of one stored cluster, including padding.

push_back(self: aare._aare.ClusterVector_Cluster3x3i, cluster: aare::Cluster<int, (unsigned char)3, (unsigned char)3, unsigned short>) → None¶

Append one cluster.

Notes

Do not call this method while a zero-copy NumPy view of the ClusterVector exists. Reallocation invalidates the view, while an append without reallocation leaves its shape unchanged.

property size¶: Number of stored clusters.

sum(self: aare._aare.ClusterVector_Cluster3x3i) → numpy.ndarray¶

Return the sum of all pixels in each cluster.

Returns:: One value per cluster, in container order and with the cluster pixel dtype.
Return type:: numpy.ndarray

sum_2x2(self: aare._aare.ClusterVector_Cluster3x3i) → numpy.ndarray¶

Return the highest-sum center-adjacent 2x2 subcluster for each cluster.

Returns:: Structured array with sum and index fields. Indices are 0 for top-left, 1 for top-right, 2 for bottom-left, and 3 for bottom-right, relative to the cluster center.
Return type:: numpy.ndarray

Free Functions:

aare.hitmap(image_size, clusters)

Count cluster centers into an int32 image. image_size is given as (rows, columns), and output element [y, x] contains the number of photon hits at that coordinate. Out-of-bounds hits are ignored. All registered ClusterVector variants are accepted.

Parameters:

image_size (tuple[int, int]) – Shape of the output image.
clusters (ClusterVector) – Clusters whose centers are counted.

Returns:

Hit counts with shape image_size.

Return type:

numpy.ndarray

aare.reduce_to_3x3(clustervector)

Return a new vector containing the central 3x3 block of every input cluster. Cluster order, coordinates, frame number, and pixel dtype are preserved.

Parameters:: clustervector (ClusterVector) – Input clusters with both dimensions at least 3 and at least one dimension greater than 3.
Returns:: Reduced 3x3 clusters.
Return type:: ClusterVector

aare.reduce_to_2x2(clustervector)

Return a new vector containing the highest-sum center-adjacent 2x2 block of every input cluster. Cluster order, coordinates, frame number, and pixel dtype are preserved.

Parameters:: clustervector (ClusterVector) – Input clusters of size 2x2 or larger.
Returns:: Reduced 2x2 clusters.
Return type:: ClusterVector