upxo.pxtalops.grain_boundary_zones module

upxo.pxtalops.grain_boundary_zones.introduce_boundary_zones(gs, fids=[], niterations=5, method='use_min_core_size', min_core_size=50, threshold_bz_thickness=2, structure_nx=3, structure_ny=3, reset_others=False, renumber_fid_map=True, morph_char=False, topo_char=False, remap_scalars=False, perform_topology_checks=False, see_plot=False, figure_size=(5, 5), figure_dpi=100)[source]

Introduce boundary zones and cores within grains using morphological erosion.

This function partitions each grain into a boundary zone (outer region) and a core (inner region) by applying binary erosion. The method parameter controls how the boundary zone thickness is determined.

Parameters:

gs (mcgs2_grain_structure) – Grain structure object (temporal slice) from UPXO. Note: This object is modified in-place; attributes bbox_bz and bbox_core are added to each grain. Pass a deep copy if you need to preserve the original.
fids (list of int, optional) – List of grain IDs (gid) to process. If empty (default), processes all grains in gs.gid. Use to selectively apply boundary zone detection to specific grains.
niterations (int, default=5) – Maximum number of morphological erosion iterations to attempt. Higher values allow thicker boundary zones but may eliminate small grains entirely.
method ({'use_min_core_size', 'simple', 'thresholded'}, default='use_min_core_size') –
Algorithm for defining boundary zones:
- ’use_min_core_size’: Erodes until core size drops below min_core_size, then backs off to maintain minimum core dimension (recommended for ensuring non-trivial cores).
- ’simple’: Uses maximum successful erosion without size constraints (may produce very small cores).
- ’thresholded’: Stops erosion when boundary zone reaches specific thickness defined by threshold_bz_thickness.
min_core_size (int, default=50) – Minimum number of pixels required in the grain core (used only with method=’use_min_core_size’). Grains smaller than this after maximum erosion will have their entire bbox assigned as boundary zone with bbox_core=None.
threshold_bz_thickness (int, default=2) – Number of erosion iterations to define boundary zone thickness (used only with method=’thresholded’). Boundary zone is the result of eroding exactly this many iterations.
structure_nx (int, default=3) – Width of the morphological structuring element (connectivity kernel). Value of 3 creates 8-connectivity for erosion (includes diagonals). Use 2 for 4-connectivity.
structure_ny (int, default=3) – Height of the morphological structuring element. Typically set equal to structure_nx for isotropic erosion.
see_plot (bool, default=False) – If True, generates a matplotlib visualization showing boundary zones overlaid on the grain structure with distinct colormap (useful for debugging).
figure_size (tuple of float, default=(5, 5)) – Width and height of the plot figure in inches (used only if see_plot=True).
figure_dpi (int, default=100) – Resolution of the plot figure in dots per inch (used only if see_plot=True).

Returns:

lgi_new – 2D label image with boundary zones visualized as separate grain IDs. Shape matches gs.lgi. Original grain cores retain their IDs; boundary zones are assigned new sequential IDs starting from max(gs.gid) + 1.

Return type:

ndarray of int

Raises:

ValueError – If method is not one of the recognized options.
Side Effects –
------------ –
Modifies the input gs object in-place by adding two attributes to each processed grain: –

:raises - gs.g[gid][‘grain’].bbox_bz : ndarray of bool: Boolean mask of the boundary zone within the grain’s bounding box. Shape matches grain.bbox. Pixels marked True belong to the boundary zone. :raises - gs.g[gid][‘grain’].bbox_core : ndarray of bool or None: Boolean mask of the core region. If the grain is too small or erosion eliminates the core entirely, this is set to None.

Notes

Uses scipy.ndimage.binary_erosion for morphological operations.
For grains with bbox_core=None, the entire grain bbox is considered boundary zone.
To avoid modifying the original grain structure, pass a deep copy: lgi_new = introduce_boundary_zones(deepcopy(gs), …)
The returned lgi_new is for visualization only; actual boundary zone data is stored in gs.g[gid][‘grain’].bbox_bz.

Examples

>>> from upxo.pxtalops.grain_boundary_zones import introduce_boundary_zones
>>> from copy import deepcopy
>>> # Apply to all grains with minimum core size constraint
>>> lgi_bz = introduce_boundary_zones(gs, method='use_min_core_size', min_core_size=100)
>>>
>>> # Process specific grains with simple erosion
>>> lgi_bz = introduce_boundary_zones(gs, fids=[1, 5, 10], method='simple', niterations=3)
>>>
>>> # Preserve original structure
>>> gs_copy = deepcopy(gs)
>>> lgi_bz = introduce_boundary_zones(gs_copy, see_plot=True)