Pixel Classifier

Classifies pixels into physics categories (CHARGE_COLLECTION, CHARGE_NEIGHBOR, INDUCTION_ONLY, INACTIVE) based on:

  • Perpendicular distance from segment line to pixel surface (point-to-box distance)

  • Expected diffusion spread (\(\sigma_T = \sqrt{2 * D_T * t_\mathrm{drift}}\))

  • Far-field induction signal strength estimate

Example workflow:

# Classify pixels by physics regime # For each pixel, all segments are processed to determine if # it’s in CHARGE_COLLECTION, CHARGE_NEIGHBOR, INDUCTION_ONLY, # or INACTIVE result = classify_pixels(segments, plane_id=0)

# Result contains pixel IDs for each category charge_pixel_ids = result.charge_pixels # CuPy array on GPU neighbor_pixel_ids = result.neighbor_pixels induction_pixel_ids = result.induction_pixels

larndsim.far_field.pixel_classifier.generate_pixel_coordinates(plane_id)[source][source]

Generate all pixel center coordinates for a given TPC plane.

Uses the same grid structure as pixels_from_track.py for consistency. This ensures that pixel IDs from pixel2id() correspond to the correct physical positions.

Parameters:

plane_id (int) – TPC plane index

Returns:

(pixel_coords_x, pixel_coords_y, pixel_ids)

  • pixel_coords_x: (n_pixels,) array of x-coordinates in cm

  • pixel_coords_y: (n_pixels,) array of y-coordinates in cm

  • pixel_ids: (n_pixels,) array of unique pixel IDs from pixel2id()

Return type:

tuple

larndsim.far_field.pixel_classifier.classify_pixels_kernel(segments, pixel_coords_x, pixel_coords_y, categories, z_anode)[source]

CUDA kernel to classify each pixel by proximity to segments.

For each pixel:

  1. Loop over all segments

  2. Calculate perpendicular distance from segment to pixel surface (point-to-box)

  3. Estimate diffusion spread: \(\sigma_T = \sqrt{2 * D_T * t_\mathrm{drift}}\)

  4. Check proximity thresholds including diffusion spread

  5. Assign highest-priority category (CHARGE_COLLECTION > CHARGE_NEIGHBOR > INDUCTION_ONLY)

Parameters:

  • segments (cupy.typing.NDArray) – (n_segments,) structured array with fields x_start, y_start, z_start, x_end, y_end, z_end (cm), n_electrons (float), and pixel_plane (int).

  • pixel_coords_x (cupy.typing.NDArray.cupy.float32) – (n_pixels,) pixel center x positions (cm)

  • pixel_coords_y (cupy.typing.NDArray.cupy.float32) – (n_pixels,) pixel center y positions (cm)

  • categories (cupy.typing.NDArray.cupy.int32) – (n_pixels,) output array of PixelCategory enum values

  • z_anode (float) – anode z-position for this plane (cm)

larndsim.far_field.pixel_classifier.classify_pixels(segments, plane_id)[source][source]

Classify pixels into physics regimes based on segment proximity and diffusion.

This function is the main entry point for pixel classification. It:

  1. Generates pixel coordinates for the specified TPC plane

  2. Validates inputs and transfers data to GPU if needed

  3. Launches the classification kernel

  4. Extracts per-category pixel indices

  5. Returns a PixelClassificationResult with categorized pixel lists and pixel IDs

Parameters:

  • segments (cupy.typing.NDArray) – (n_segments,) structured array with fields x_start, y_start, z_start, x_end, y_end, z_end (cm), n_electrons (float), and pixel_plane (int).

  • plane_id (int) – TPC plane identifier.

Returns:

Categorized pixel lists and pixel IDs.

See PixelClassificationResult for field details.

Return type:

PixelClassificationResult

Raises:

ValueError – If input arrays have mismatched sizes or invalid data.

larndsim.far_field.pixel_classifier.get_classification_cache(segments)[source][source]

Get cache of pixel classes for all active TPCs.

Parameters:

segments (cupy.typing.NDArray) – (n_segments,) structured array with fields x_start, y_start, z_start, x_end, y_end, z_end (cm), n_electrons (float), and pixel_plane (int).

Returns:

Dict from TPC index to PixelClassificationResult

Return type:

dict[int, PixelClassificationResult]