upxo.pxtalops.twin3d module

twin3d.py

3D voxel-space twin lamella introduction for representative grain structure generation.

This module is the 3D counterpart of the polygon-space twin introduction functions in upxo.pxtalops.gssmooth2d. It uses the Plane class for perpendicular-distance voxel selection and crystallographically-derived habit plane normals (computed by compute_s3_habit_plane_3d()) to ensure lamella geometry is physically consistent with the host grain’s crystal orientation.

upxo.pxtalops.twin3d.introduce_twin_lamella_3d(lgi, host_gid, host_centroid, normal, half_width, next_gid, abrupt=False, rng=None, host_coords=None)[source]

Carve a single Sigma3 twin lamella out of a host grain in a 3D lgi array.

Uses Plane to compute perpendicular distances from each host-grain voxel to the habit plane, then selects voxels within half_width as the twin lamella region.

This mirrors the production morphological pipeline (identify_twins_gid) but drives the plane normal from the host’s crystallographic {111} habit plane instead of three randomly chosen voxel points, ensuring lamella geometry and crystal orientation remain consistent.

Parameters:

  • lgi (ndarray (nx, ny, nz), int) – 3D labelled grain image. Modified in place.

  • host_gid (int) – Grain ID of the host grain to twin.

  • host_centroid (array-like (3,)) – Centroid of the host grain’s voxel coordinates; used as the plane origin.

  • normal (array-like (3,)) – Unit normal of the habit plane in the sample frame (typically from compute_s3_habit_plane_3d()).

  • half_width (float) – Lamella half-thickness in voxels.

  • next_gid (int) – Grain ID to assign to the new twin region.

  • abrupt (bool) – If True, truncate the lamella to one half of the host grain along an in-plane axis, mimicking EBSD-measured abrupt twins.

  • rng (numpy.random.Generator or None) – Required when abrupt is True.

  • host_coords (ndarray (M, 3) or None) – Pre-built coordinate array of host-grain voxels. When provided the O(N_total_voxels) np.argwhere scan is skipped entirely, giving a large speedup for large domains. If None the scan is performed as a fallback.

Returns:

twin_voxels – Global voxel coordinates of the twin region, or None if no voxels were selected.

Return type:

ndarray (N, 3) or None