spine.geo.base.Geometry

class spine.geo.base.Geometry(name: str, tag: str, version: str, tpc: dict[str, Any], optical: dict[str, Any] | None = None, crt: dict[str, Any] | None = None, gdml: str | None = None, crs_files: list[str] | None = None, lrs_file: str | None = None)[source]

Handles all geometry functions for a collection of box-shaped TPCs with a arbitrary set of optical detectors organized in optical volumes and auxiliary CRT planes.

name

Name of the detector

Type:: str

tag

Tag or label for the geometry instance

Type:: str

version

Version number of the geometry

Type:: int

tpc

TPC detector properties

Type:: TPCDetector

optical

Optical detector properties

Type:: OptDetector, optional

crt

CRT detector properties

Type:: CRTDetector, optional

gdml

GDML file name associated with the geometry

Type:: str, optional

crs_files

CRS (Charge Readout System) geometry file(s) reference (flow only)

Type:: List[str], optional

lrs_file

LRS (Light Readout System) geometry file reference (flow only)

Type:: str, optional

Attributes:

center: Center of the box.
crs_files
crt
dimensions: Dimensions of the box.
faces: Returns the 6 faces of the box as Plane objects.
gdml
lower: Lower bounds of the box.
lrs_file
optical
upper: Upper bounds of the box.
volume: Volume of the box.

Methods

`ContDefinition`(volumes, use_source, ...)	Helper class to store containment volume definitions.
`adapt_volume`(ref_volume, margin[, ...])	Apply margins from a given volume.
`check_containment`(definition, points[, ...])	Check whether a point cloud comes within some distance of the boundaries of a certain subset of detector volumes, depending on the mode.
`define_containment_volumes`(margin[, ...])	This function defines a list of volumes to check containment against.
`distance`(points)	Computes the minimum distance from a set of points to the box.
`get_boundaries`([with_optical, with_crt])	Fetch the overall geometry boundaries, optionally including optical and CRT detectors.
`get_chambers`(sources)	Converts logical TPC indexes to unique chamber indexes.
`get_closest_module`(points)	For each point, find the ID of the closest module.
`get_closest_module_indexes`(points)	For each module, get the list of points that live closer to it than any other module in the detector.
`get_closest_tpc`(points)	For each point, find the ID of the closest TPC.
`get_closest_tpc_indexes`(points)	For each TPC, get the list of points that live closer to it than any other TPC in the detector.
`get_contributors`(sources)	Gets the list of [module ID, tpc ID] pairs that contributed to an object, as defined in this geometry.
`get_min_volume_offset`(points, module_id[, ...])	Get the minimum offset to apply to a point cloud to bring it within the boundaries of a volume.
`get_sources`(sources)	Converts logical TPC indexes to physical TPC indexes.
`get_volume_index`(sources, module_id[, tpc_id])	Gets the list of indices of points that belong to a certain detector volume (module or individual TPC).
`get_volume_offsets`(points, module_id[, tpc_id])	Compute how far each point is from a certain detector volume.
`merge_volumes`(volumes)	Given a list of volumes and their boundaries, find the smallest box that encompass all volumes combined.
`parse_optical`(volume, **optical)	Parse the optical detector configuration.
`split`(points, target_id[, sources, meta])	Migrate all points to a target module, organize them by module ID.
`translate`(points, source_id, target_id[, factor])	Moves a point cloud from one module to another one

__init__(name: str, tag: str, version: str, tpc: dict[str, Any], optical: dict[str, Any] | None = None, crt: dict[str, Any] | None = None, gdml: str | None = None, crs_files: list[str] | None = None, lrs_file: str | None = None) → None[source]

Initialize the detector geometry.

Parameters:

name (str) – Name of the detector
tag (str) – Tag or label for the geometry instance
version (int) – Version number of the geometry
tpc (dict) – Detector boundary configuration
optical (dict, optional) – Optical detector configuration
crt (dict, optional) – CRT detector configuration
gdml (str, optional) – GDML file name associated with the geometry
crs_files (str or list of str, optional) – CRS (Cosmic Ray System) geometry file(s)
lrs_file (str, optional) – LRS (Light Readout System) geometry file

Returns:

np.ndarray – Lower boundaries of the overall geometry
np.ndarray – Upper boundaries of the overall geometry

Methods

`__init__`(name, tag, version, tpc[, optical, ...])	Initialize the detector geometry.
`adapt_volume`(ref_volume, margin[, ...])	Apply margins from a given volume.
`check_containment`(definition, points[, ...])	Check whether a point cloud comes within some distance of the boundaries of a certain subset of detector volumes, depending on the mode.
`define_containment_volumes`(margin[, ...])	This function defines a list of volumes to check containment against.
`distance`(points)	Computes the minimum distance from a set of points to the box.
`get_boundaries`([with_optical, with_crt])	Fetch the overall geometry boundaries, optionally including optical and CRT detectors.
`get_chambers`(sources)	Converts logical TPC indexes to unique chamber indexes.
`get_closest_module`(points)	For each point, find the ID of the closest module.
`get_closest_module_indexes`(points)	For each module, get the list of points that live closer to it than any other module in the detector.
`get_closest_tpc`(points)	For each point, find the ID of the closest TPC.
`get_closest_tpc_indexes`(points)	For each TPC, get the list of points that live closer to it than any other TPC in the detector.
`get_contributors`(sources)	Gets the list of [module ID, tpc ID] pairs that contributed to an object, as defined in this geometry.
`get_min_volume_offset`(points, module_id[, ...])	Get the minimum offset to apply to a point cloud to bring it within the boundaries of a volume.
`get_sources`(sources)	Converts logical TPC indexes to physical TPC indexes.
`get_volume_index`(sources, module_id[, tpc_id])	Gets the list of indices of points that belong to a certain detector volume (module or individual TPC).
`get_volume_offsets`(points, module_id[, tpc_id])	Compute how far each point is from a certain detector volume.
`merge_volumes`(volumes)	Given a list of volumes and their boundaries, find the smallest box that encompass all volumes combined.
`parse_optical`(volume, **optical)	Parse the optical detector configuration.
`split`(points, target_id[, sources, meta])	Migrate all points to a target module, organize them by module ID.
`translate`(points, source_id, target_id[, factor])	Moves a point cloud from one module to another one

Attributes

`center`	Center of the box.
`crs_files`
`crt`
`dimensions`	Dimensions of the box.
`faces`	Returns the 6 faces of the box as Plane objects.
`gdml`
`lower`	Lower bounds of the box.
`lrs_file`
`optical`
`upper`	Upper bounds of the box.
`volume`	Volume of the box.
`name`
`tag`
`version`
`tpc`
`boundaries`

name: str

tag: str

version: str

gdml: str | None = None

crs_files: list[str] | None = None

lrs_file: str | None = None

tpc: TPCDetector

optical: OptDetector | None = None

crt: CRTDetector | None = None

parse_optical(volume: str, **optical: Any) → OptDetector[source]

Parse the optical detector configuration.

Parameters:

volume (str) – Optical volume boundaries (one of ‘tpc’ or ‘module’)
**optical (dict) – Reset of the optical detector configuration

Returns:

Optical detector object

Return type:

OptDetector

class ContDefinition(volumes: ndarray, use_source: bool, limit_normals: list[ndarray], limit_thresholds: list[float])[source]

Helper class to store containment volume definitions.

volumes

(N, 3, 2) set of volume boundaries

Type:: List[np.ndarray]

use_source

Whether to use the source of the points to determine the volume

Type:: bool

limit_normals

List of limit plane normals

Type:: List[np.ndarray]

limit_thresholds

List of limit thresholds along the plane normal

Type:: List[float]

volumes: ndarray

use_source: bool

limit_normals: list[ndarray]

limit_thresholds: list[float]

get_boundaries(with_optical: bool = True, with_crt: bool = True) → ndarray[source]

Fetch the overall geometry boundaries, optionally including optical and CRT detectors.

Parameters:

with_optical (bool, default True) – Whether to include optical detector boundaries
with_crt (bool, default True) – Whether to include CRT detector boundaries

Returns:

Lower and upper boundaries of the overall geometry

Return type:

np.ndarray

get_sources(sources: ndarray) → ndarray[source]

Converts logical TPC indexes to physical TPC indexes.

Parameters:: sources (np.ndarray) – (N, 2) Array of logical [module ID, tpc ID] pairs, one per point
Returns:: (N, 2) Array of physical [module ID, tpc ID] pairs, one per point
Return type:: np.ndarray

get_chambers(sources: ndarray) → ndarray[source]

Converts logical TPC indexes to unique chamber indexes.

Parameters:

sources (np.ndarray) – (N, 2) Array of logical [module ID, tpc ID] pairs, one per point

Returns:

Array of physical chamber indexes, one per point

Return type:

np.ndarray

get_contributors(sources: ndarray) → list[ndarray][source]

Gets the list of [module ID, tpc ID] pairs that contributed to an object, as defined in this geometry.

Parameters:: sources (np.ndarray) – (N, 2) Array of [module ID, tpc ID] pairs, one per point
Returns:: (2, N_t) Pair of arrays: the first contains the list of contributing modules, the second of contributing tpcs.
Return type:: List[np.ndarray]

get_volume_index(sources: ndarray, module_id: int, tpc_id: int | None = None) → ndarray[source]

Gets the list of indices of points that belong to a certain detector volume (module or individual TPC).

Parameters:

sources (np.ndarray) – (N, 2) Array of [module ID, tpc ID] pairs, one per point
module_id (int) – ID of the module
tpc_id (int, optional) – ID of the TPC within the module. If not specified, the volume offsets are estimated w.r.t. the module itself

Returns:

Index of points that belong to the requested detector volume

Return type:

np.ndarray

get_closest_tpc(points: ndarray) → ndarray[source]

For each point, find the ID of the closest TPC.

There is a natural assumption that all TPCs are boxes of identical sizes, so that the relative proximitity of a point to a TPC is equivalent to its proximity to the TPC center.

Parameters:

points (np.ndarray) – (N, 3) Set of point coordinates

Returns:

List of TPC indexes, one per input point

Return type:

np.ndarray

get_closest_module(points: ndarray) → ndarray[source]

For each point, find the ID of the closest module.

There is a natural assumption that all modules are boxes of identical sizes, so that the relative proximitity of a point to a module is equivalent to its proximity to the module center.

Parameters:

points (np.ndarray) – (N, 3) Set of point coordinates

Returns:

List of module indexes, one per input point

Return type:

np.ndarray

get_closest_tpc_indexes(points: ndarray) → list[ndarray][source]

For each TPC, get the list of points that live closer to it than any other TPC in the detector.

Parameters:: points (np.ndarray) – (N, 3) Set of point coordinates
Returns:: List of index of points that belong to each TPC
Return type:: List[np.ndarray]

get_closest_module_indexes(points: ndarray) → list[ndarray][source]

For each module, get the list of points that live closer to it than any other module in the detector.

Parameters:: points (np.ndarray) – (N, 3) Set of point coordinates
Returns:: List of index of points that belong to each module
Return type:: List[np.ndarray]

get_volume_offsets(points: ndarray, module_id: int, tpc_id: int | None = None) → ndarray[source]

Compute how far each point is from a certain detector volume.

Parameters:

points (np.ndarray) – (N, 3) : Point coordinates
module_id (int) – ID of the module
tpc_id (int, optional) – ID of the TPC within the module. If not specified, the volume offsets are estimated w.r.t. the module itself

Returns:

(N, 3) Offsets w.r.t. to the volume boundaries

Return type:

np.ndarray

get_min_volume_offset(points: ndarray, module_id: int, tpc_id: int | None = None) → ndarray[source]

Get the minimum offset to apply to a point cloud to bring it within the boundaries of a volume.

Parameters:

points (np.ndarray) – (N, 3) : Point coordinates
module_id (int) – ID of the module
tpc_id (int, optional) – ID of the TPC within the module. If not specified, the volume offsets are estimated w.r.t. the module itself

Returns:

Offsets w.r.t. to the volume location

Return type:

np.ndarray

translate(points: ndarray, source_id: int, target_id: int, factor: float | ndarray | None = None) → ndarray[source]

Moves a point cloud from one module to another one

Parameters:

points (np.ndarray) – (N, 3) Set of point coordinates
source_id (int) – Module ID from which to move the point cloud
target_id (int) – Module ID to which to move the point cloud
factor (Union[float, np.ndarray], optional) – Multiplicative factor to apply to the offset. This is necessary if the points are not expressed in detector coordinates

Returns:

(N, 3) Set of translated point coordinates

Return type:

np.ndarray

split(points: ndarray, target_id: int, sources: ndarray | None = None, meta: Any | None = None) → tuple[ndarray, list[ndarray]][source]

Migrate all points to a target module, organize them by module ID.

Parameters:

points (np.ndarray) – (N, 3) Set of point coordinates
target_id (int) – Module ID to which to move the point cloud
sources (np.ndarray, optional) – (N, 2) Array of [module ID, tpc ID] pairs, one per voxel
meta (Meta, optional) – Meta information about the voxelized image. If provided, the points are assumed to be provided in voxel coordinates.

Returns:

np.ndarray – (N, 3) Shifted set of points
List[np.ndarray] – List of index of points that belong to each module

check_containment(definition: ContDefinition, points: np.ndarray, sources: np.ndarray | None = None, allow_multi_module: bool = False, summarize: bool = True) → bool | np.ndarray[source]

Check whether a point cloud comes within some distance of the boundaries of a certain subset of detector volumes, depending on the mode.

Must define containment volumes first using define_containment_volumes.

Parameters:

definition (ContDefinition) – Containment volume definition to check against
points (np.ndarray) – (N, 3) Set of point coordinates
sources (np.ndarray, optional) – (S, 2) : List of [module ID, tpc ID] pairs that created the point cloud
allow_multi_module (bool, default False) – Whether to allow points to span multiple modules
summarize (bool, default True) – If True, only returns a single flag for the whole cloud. Otherwise, returns a boolean array corresponding to each point.

Returns:

True if the points are contained, False if not

Return type:

Union[bool, np.ndarray]

define_containment_volumes(margin: float | list[float] | np.ndarray, cathode_margin: float | None = None, mode: str = 'module', include_limits: bool = True) → ContDefinition[source]

This function defines a list of volumes to check containment against.

If the containment is checked against a constant volume, it is a lot more efficient to call this function once and call check_containment reapitedly after.

Parameters:

margin (Union[float, List[float], np.array]) – Minimum distance from a detector wall to be considered contained. A scalar applies the same buffer to all six walls. A three-element array applies one shared distance per axis. A (3, 2) array specifies the lower and upper margin independently for each axis.
cathode_margin (float, optional) – If specified, sets a different margin for the cathode boundaries
mode (str, default 'module') – Containment criterion. tpc requires containment within a single TPC, module within a single module, detector within the full detector volume and source uses voxel provenance to determine the contributing TPCs and define the containment volumes accordingly.
include_limits (bool, default True) – If True, the TPC active region limits are checked against

Returns:

Object containing the list of containment volumes, and other information to check containment against

Return type:

ContDefinition

adapt_volume(ref_volume: ndarray, margin: ndarray, cathode_margin: float | None = None, module_id: int | None = None, tpc_id: int | None = None) → ndarray[source]

Apply margins from a given volume. Takes care of subtleties associated with the cathode, if needed.

Parameters:

ref_volume (np.ndarray) – (3, 2) Array of volume boundaries
margin (np.ndarray) – Minimum distance from a detector wall to be considered contained as [[x_low,x_up], [y_low,y_up], [z_low,z_up]], i.e. distance is specified individually of each wall.
cathode_margin (float, optional) – If specified, sets a different margin for the cathode boundaries
module_id (int, optional) – ID of the module
tpc_id (int, optional) – ID of the TPC within the module

Returns:

(3, 2) Updated array of volume boundaries

Return type:

np.ndarray

static merge_volumes(volumes: ndarray) → ndarray[source]

Given a list of volumes and their boundaries, find the smallest box that encompass all volumes combined.

Parameters:: volumes (np.ndarray) – (N, 3, 2) List of volume boundaries
Returns:: (3, 2) Boundaries of the combined volume
Return type:: np.ndarray