graintrace.rei_comparison#

Compare two rare-event-identification point clouds for spatial overlap.

class graintrace.rei_comparison.REIComparison(rei_csv_1, rei_csv_2, output_dir, spacing_1=None, spacing_2=None, coord_cols=('x', 'y', 'z'), cluster_col='rare_cluster_id', origin=None, s_ref=None, supersample=1, split_merge_fraction=0.2)[source]#

Bases: object

Compare two rare-event-identification (REI) point clouds.

Each input CSV is a voxelized point cloud of a rare region on a regular grid (columns coord_cols plus an optional integer cluster_col). The two grids may have different spacings but are assumed to share an origin (no rotation / translation is applied here).

A rare point is treated as the center of its voxel cube, so each REI is a union of axis-aligned cubes and the overlap is a boolean volume intersection. Both regions are resampled onto a common finer lattice (s_ref = min(spacing_1, spacing_2) per axis); membership is then an O(1) integer-index hash lookup. Carrying cluster_col through the same pass yields a per-cluster overlap matrix used for a 1-to-1 (Hungarian) cluster correspondence.

Outputs written to output_dir:

  • overlap_metrics.json: IoU/Dice/containment + counts/volumes

  • overlap_cloud.vtk: classified point cloud (membership 1=only-1, 2=only-2, 3=both)

  • cluster_match.csv: 1-to-1 cluster pairing (if cluster_col)

Parameters:

  • rei_csv_1 (str)

  • rei_csv_2 (str)

  • output_dir (str)

  • spacing_1 (SpacingLike)

  • spacing_2 (SpacingLike)

  • coord_cols (Tuple[str, str, str])

  • cluster_col (Optional[str])

  • origin (Optional[Sequence[float]])

  • s_ref (SpacingLike)

  • supersample (int)

  • split_merge_fraction (float)

run_comparison()[source]#

Run the full comparison, write outputs, and return the metrics dict.

Return type:

Dict[str, Any]