graintrace.construct_voxel_mesh#

EBSD/NF voxel-grid segmentation and hex meshing (VoxelMeshBuilder).

class graintrace.construct_voxel_mesh.VoxelMeshBuilder(*, file_path, save_dir, euler_cols, cell_id_col=None, angle_convention='bunge', angle_type='radians', symmetry='432', prefix='voxel', write_intermediate=True, write_vtk=True, default_mesh_filename='mesh.e', default_mapped_orientations_filename='orientations')[source]#

Bases: object

Segment a voxel/grid orientation field into grains and build a hex mesh.

Takes a gridded Euler-angle CSV (EBSD, or a gridded NF/FF reconstruction), segments it into grains via graph (Leiden) or flood-fill, and generates a conformal hexahedral Exodus mesh via CUBIT/SCULPT with per-element MRP orientations. See examples/demonstrate_grid_segmentation_mesh.py and the /voxel-segmentation-mesh skill.

Parameters:

  • file_path (PathLike)

  • save_dir (PathLike)

  • euler_cols (Sequence[str])

  • cell_id_col (Optional[str])

  • angle_convention (str)

  • angle_type (str)

  • symmetry (str)

  • prefix (str)

  • write_intermediate (bool)

  • write_vtk (bool)

  • default_mesh_filename (str)

  • default_mapped_orientations_filename (str)

DEFAULT_SEGMENTATION = {'graph_params': {'graph_mode': 'grid', 'grid_tol': 1e-06, 'manhattan_radius': 2, 'n_jobs': 1, 'networkit_kwargs': {'gamma': 1.0}, 'nodes_chunk': 250000, 'plot': True, 'reduce_edges_topweights_k': None, 'seed': 42, 'segmenter': 'leiden', 'weight_cfg': {'eps': 1e-08, 'mode': 'inverse', 'power': 2.0, 'sigma': None, 'sigma_auto': None}, 'weight_chunk_size': 1000000}, 'method': 'flood', 'params': {'batch_norm': 1000, 'connectivity': 26, 'grain_threshold': 100, 'grain_threshold_final': 1000, 'misorientation_tol': 0.08726646259971647, 'stop_count': 500}}#
DEFAULT_SCULPT_OPTIONS: Sequence[str] = ('--adapt', '-A', '7', '-df', '1', '-S', '2', '-CS', '4', '--void_mat', '0')#
REQUIRED_SCULPT_KEYS = ('psculpt', 'epu', 'nprocs')#
reconstruct(*, segmentation=None, apply_smoothing=False)[source]#

Segment the grid CSV and write grid .npy/.vtk outputs to save_dir.

Loads the CSV onto a dense voxel grid, optionally smooths it, segments it into grains (flood-fill or graph/Leiden), removes small segments, infills, and relabels grain ids to be contiguous. If cell_id_col was set, the provided ids are used and segmentation is skipped.

Parameters:

  • segmentation (Dict[str, Any] | None) – Segmentation config dict with “method” (“flood” or “graph”), “params”, and optional “graph_params”; None uses the class defaults.

  • apply_smoothing (bool) – If True, run an orientation-aware smoothing pass over the grid before segmentation.

Returns:

Path to the written merged_segmented_fixed_grid.npy.

Return type:

Path

mesh(*, sculpt_config=None, sculpt_options=None, merged_grid=None, spn_path=None, orientations_path=None, mesh_path=None, mapped_orientations_path=None, mesher='sculpt', background_id=0)[source]#

Mesh the segmented grid and map orientations to the mesh.

mesher=”sculpt” (default) runs CUBIT/SCULPT for a conformal, smoothed hex mesh (needs sculpt_config). mesher=”voxel” instead dumps the grid straight to Exodus as one cube hex per voxel (no SCULPT, no external tools): every element is a perfect cube (scaled Jacobian = 1, so zero inverted/sliver elements) at the cost of stair-stepped grain boundaries. Both write the mesh to mesh_path and per-block MRP orientations to mapped_orientations_path + “.csv”.

Parameters:

  • sculpt_config (Dict[str, Any] | None) – SCULPT configuration dict (required keys psculpt, epu, nprocs; optional launcher, environment); required when mesher=”sculpt”, ignored for “voxel”.

  • sculpt_options (Sequence[str] | None) – SCULPT CLI flags as a sequence of strings; None uses DEFAULT_SCULPT_OPTIONS.

  • merged_grid (str | Path | None) – Path to the merged segmented grid .npy; None uses save_dir/merged_segmented_fixed_grid.npy.

  • spn_path (str | Path | None) – Override for the SCULPT .spn voxel input path (sculpt path only).

  • orientations_path (str | Path | None) – Override for the SCULPT per-voxel orientations input path (sculpt path only).

  • mesh_path (str | Path | None) – Override for the output Exodus mesh path; None uses the configured default.

  • mapped_orientations_path (str | Path | None) – Override for the mapped per-element orientation output basename (“.csv” is appended).

  • mesher (str) – Meshing backend, “sculpt” (CUBIT/SCULPT conformal hex) or “voxel” (one cube hex per voxel, no external tools).

  • background_id (int) – Grain/phase id treated as background/void in the voxel dump (mesher=”voxel”).

Returns:

Path to the written Exodus mesh.

Return type:

Path