spine.utils.ppn

Module which contains utility function to process PPN information.

It contains functions to produce PPN labels and functions to process the PPN predictions into something human-readable.

Functions

check_track_orientation_ppn(start_point, ...)

Use PPN end point predictions to predict track orientation.

get_ppn_labels(particle_v, meta, dtype[, ...])

Gets particle point coordinates and informations for running PPN.

get_vertex_labels(particle_v, neutrino_v, ...)

Gets particle vertex coordinates.

image_contains(meta, point[, dim])

Checks whether a point is contained in the image box defined by meta.

image_coordinates(meta, point[, dim])

Returns the coordinates of a point in units of pixels with an image.

Classes

PPNPredictor([score_threshold, ...])

PPN post-processing class to convert PPN raw predictions into points.

ParticlePointPredictor([use_numpy, ...])

Produces start/end points given a list of particles and PPN predictions.
class spine.utils.ppn.PPNPredictor(score_threshold=0.5, type_score_threshold=0.5, type_dist_threshold=1.999, pool_score_fn='max', pool_dist=1.999, enforce_type=True, classes=[0, 1, 2, 3], apply_deghosting=False)[source]

PPN post-processing class to convert PPN raw predictions into points.

Methods

__call__(ppn_points, ppn_coords, ppn_masks)

Converts the batched raw output of PPN to a discrete set of proposed points of interest.

dbscan_points(coordinates)

Form clusters of predited points based on proximity.

process_single(ppn_raw, ppn_coords, ppn_mask)

Converts the PPN output from a single entry into points of interests for that entry.
process_single(ppn_raw, ppn_coords, ppn_mask, ppn_ends=None, segmentation=None, ghost=None, selection=None)[source]

Converts the PPN output from a single entry into points of interests for that entry.

Notes

This function works with both torch.Tensor and np.ndarray inputs.

Parameters:

  • ppn_raw (Union[torch.Tensor, np.ndarray]) – Raw output of PPN

  • ppn_coords (Union[torch.Tensor, np.ndarray]) – Coordinates of the image at each PPN layer

  • ppn_masks (Union[torch.Tensor, np.ndarray]) – Predicted masks of at each PPN layer

  • ppn_ends (Union[torch.Tensor, np.ndarray], optional) – Raw logits from the end point classification layer of PPN

  • segmentation (Union[torch.Tensor, np.ndarray], optional) – Raw logits from the semantic segmentation network output

  • ghost (Union[torch.Tensor, np.ndarray], optional) – Raw logits from the ghost segmentation network output

  • selection (Union[torch.Tensor, np.ndarray], optional) – List of indexes to consider exclusively (e.g. to get PPN predictions within a list of clusters)

Returns:

Predicted points encoded as rows containing coordinates, validity scores, occupancy, type scores, predicted type and endpoint type.

Return type:

Union[torch.Tensor, np.ndarray]

dbscan_points(coordinates)[source]

Form clusters of predited points based on proximity.

Parameters:

coordinates (np.ndarray) – Coordinates of the points to cluster

Returns:

List of proposed point cluster indexes

Return type:

List[np.ndarray]

class spine.utils.ppn.ParticlePointPredictor(use_numpy=True, contained_first=True, anchor_points=True, enhance_track_points=False, approx_farthest_points=True)[source]

Produces start/end points given a list of particles and PPN predictions.

Given a list particle or fragment clusters, leverage the raw PPN output to produce a list of start points for shower objects and of start/end points for track objects: - For showers, pick the most likely PPN point - For tracks, pick the two points farthest away from each other

Methods

__call__(data, clusts, clust_shapes, ppn_points)

Assign start/end points to one batch of events.

get_end_points_numpy(points, clusts, ...)

Parallelized numba function to fetch each of the cluster end points.

get_end_points_torch(points, clusts, ...)

Torch function to fetch each of the cluster end points.
get_end_points_torch(points, clusts, clusts_seg, ppn_points)[source]

Torch function to fetch each of the cluster end points.

Parameters:

  • points (torch.Tensor) – (N, 3) Image point coordinates

  • clusts (List[np.ndarray]) – List of particle clusters

  • clust_shapes (np.ndarray) – Semantic type of each of the clusters

  • ppn_points (torch.Tensor) – Raw output of PPN

get_end_points_numpy(points, clusts, clust_shapes, ppn_points)[source]

Parallelized numba function to fetch each of the cluster end points.

Parameters:

  • points (np.darray) – (N, 3) Image point coordinates

  • clusts (List[np.ndarray]) – List of particle clusters

  • clust_shapes (np.darray) – Semantic type of each of the clusters

  • ppn_points (np.ndarray) – Raw output of PPN

spine.utils.ppn.check_track_orientation_ppn(start_point, end_point, ppn_candidates)[source]

Use PPN end point predictions to predict track orientation.

Use the PPN point assignments as a basis to orient a track. Match the end points of a track to the closest PPN candidate and pick the candidate with the highest start score as the start point

Parameters:

  • start_point (np.ndarray) –

    1. Start point of the track

  • end_point (np.ndarray) –

    1. End point of the track

  • ppn_candidates (np.ndarray) – (N, 10) PPN point candidates and their associated scores

Returns:

Returns True if the start point provided is correct, False if the end point is more likely to be the start point.

Return type:

bool

spine.utils.ppn.get_ppn_labels(particle_v, meta, dtype, dim=3, min_voxel_count=1, min_energy_deposit=0, include_point_tagging=True)[source]

Gets particle point coordinates and informations for running PPN.

We skip some particles under specific conditions (e.g. low energy deposit, low voxel count, nucleus track, etc.)

Parameters:

  • particle_v (List[larcv.Particle]) – List of LArCV particle objects in the image

  • meta (larcv::Voxel3DMeta or larcv::ImageMeta) – Metadata information

  • dtype (str) – Typing of the output PPN labels

  • dim (int, default 3) – Number of dimensions of the image

  • min_voxel_count (int, default 5) – Minimum number of voxels associated with a particle to be included

  • min_energy_deposit (float, default 0) – Minimum energy deposition associated with a particle to be included

  • include_point_tagging (bool, default True) – If True, include an a label of 0 for start points and 1 for end points

Returns:

Array of points of shape (N, 5/6) where 5/6 = x,y,z + point type + particle index [+ start (0) or end (1) point tagging]

Return type:

np.array

spine.utils.ppn.get_vertex_labels(particle_v, neutrino_v, meta, dtype)[source]

Gets particle vertex coordinates.

It provides the coordinates of points where multiple particles originate:

  • If neutrino_v is provided, it uses the neutrino interaction points.

  • If particle_v is provided instead, it looks for ancestor positions shared by at least two primary particles.

Parameters:

  • particle_v (List[larcv.Particle]) – List of LArCV particle objects in the image

  • neutrino_v (List[larcv.Neutrino]) – List of LArCV neutrino objects in the image

  • meta (larcv::Voxel3DMeta or larcv::ImageMeta) – Metadata information

  • dtype (str) – Typing of the output PPN labels

Returns:

Array of points of shape (N, 4) where 4 = x, y, z, vertex_id

Return type:

np.array

spine.utils.ppn.image_contains(meta, point, dim=3)[source]

Checks whether a point is contained in the image box defined by meta.

Parameters:

  • meta (larcv::Voxel3DMeta or larcv::ImageMeta) – Metadata information

  • point (larcv::Point3D or larcv::Point2D) – Point to check on

  • dim (int, default 3) – Number of dimensions of the image

Returns:

True if the point is contained in the image box

Return type:

bool

spine.utils.ppn.image_coordinates(meta, point, dim=3)[source]

Returns the coordinates of a point in units of pixels with an image.

Parameters:

  • meta (larcv::Voxel3DMeta or larcv::ImageMeta) – Metadata information

  • point (larcv::Point3D or larcv::Point2D) – Point to convert the units of

  • dim (int, default 3) – Number of dimensions of the image

Returns:

True if the point is contained in the image box

Return type:

bool