upxo.gsdataops.gid_ops module

Grain/Feature ID operations.

This module provides utilities for Labelled Feature Image (LFI) processing, including neighbour detection, neighbour subset extraction, feature-ID classification (boundary/internal/corner/edge), and helper operations for 2D/3D grain-label arrays.

Imports

import upxo.gsdataops.gid_ops as gidOps

Metadata

  • Module: upxo.gsdataops.gid_ops

  • Package: upxo

  • License: GPL-3.0-only

  • Author: Dr. Sunil Anandatheertha

  • Email: vaasu.anandatheertha@ukaea.uk

  • Status: Active development

  • Last updated: 2026-03-12

Applications

  • O(1) neighbourhood extraction in 2D and 3D LFIs

  • Probabilistic neighbour down-selection

  • Boundary/internal/corner/edge feature-ID detection

  • Island and small-feature identification

Definitions

  • LFI: Labelled Feature Image

upxo.gsdataops.gid_ops.get_all_masks(section2d, as_coordinates=False)[source]

Build per-ID index/coordinate masks from a 2D labelled section.

Parameters:

  • section2d (ndarray) – 2D Labelled Feature Image.

  • as_coordinates (bool, optional) – If True, return coordinates (row, col) for each ID. If False, return flattened index locations.

Returns:

Mapping of feature_id -> indices or feature_id -> Nx2 coordinates depending on as_coordinates.

Return type:

dict

upxo.gsdataops.gid_ops.find_O1_neigh_2d(lgi, p=1.0, include_central_grain=False, throw_numba_dict=False, validate_input=True, verbosity_nfids=1000)[source]

Find first-order neighbours in 2D label grid.

Parameters ———-. lgi : ndarray

2D label grid of grain IDs.

pfloat, optional

Probability of including each neighbour. Default is 1.0 (all neighbours).

include_central_grainbool, optional

If True, include the central grain ID in its own neighbour list.

throw_numba_dictbool, optional

If True, return the raw numba Dict object. Default is False.

validate_inputbool, optional

If True, validate input parameters. Default is True.

verbosity_nfidsint, optional

Number of fids for verbosity control (not used here).

Returns:

neigh_fids – Dictionary where keys are grain IDs and values are lists of neighbour grain IDs.

Return type:

dict

upxo.gsdataops.gid_ops.find_O1_neigh_3d(lgi, p=1.0, include_central_grain=False, throw_numba_dict=False, validate_input=True)[source]

Find first-order neighbours in 3D label grid.

Parameters ———-. lgi : ndarray

3D label grid of grain IDs.

pfloat, optional

Probability of including each neighbour. Default is 1.0 (all neighbours).

include_central_grainbool, optional

If True, include the central grain ID in its own neighbour list.

throw_numba_dictbool, optional

If True, return the raw numba Dict object. Default is False.

validate_inputbool, optional

If True, validate input parameters. Default is True.

Returns:

  • neigh_fids (dict) – Dictionary where keys are grain IDs and values are lists of neighbour grain IDs.

  • Usage

  • —–

  • import upxo.gsdataops.gid_ops as gidOps

  • Use as (gidOps.find_O1_neigh_3d)

upxo.gsdataops.gid_ops.find_O1_neigh_2d_fids(lgi, fids, p=1.0, include_central_grain=False, throw_numba_dict=False, validate_input=True, verbosity_nfids=1000)[source]

Find first-order neighbours in 2D label grid for specific feature IDs.

Parameters ———-. lgi : ndarray

2D label grid of grain IDs.

fidslist or ndarray

List or array of grain IDs for which neighbours are required.

pfloat, optional

Probability of including each neighbour. Default is 1.0 (all neighbours).

include_central_grainbool, optional

If True, include the central grain ID in its own neighbour list.

throw_numba_dictbool, optional

If True, return the raw numba Dict object. Default is False.

validate_inputbool, optional

If True, validate input parameters. Default is True.

verbosity_nfidsint, optional

Number of fids for verbosity control (not used here).

Returns:

neigh_fids – Dictionary where keys are grain IDs and values are lists of neighbour grain IDs.

Return type:

dict

upxo.gsdataops.gid_ops.find_O2_neigh_3d_fids(lgi, fids, p=1.0, include_central_grain=False, throw_numba_dict=False, validate_input=True, verbosity_nfids=2500)[source]

Find first-order neighbours in 3D for selected feature IDs.

Parameters:

  • lgi (ndarray) – 3D Labelled Feature Image.

  • fids (list or ndarray) – Feature IDs for which neighbours are required.

  • p (float, optional) – Probability of retaining each neighbour. Default is 1.0.

  • include_central_grain (bool, optional) – If True, include each central feature ID in its own neighbour list.

  • throw_numba_dict (bool, optional) – If True, return the raw numba Dict output.

  • validate_input (bool, optional) – If True, validate probability settings in post-processing.

  • verbosity_nfids (int, optional) – Reserved verbosity control argument.

Returns:

Neighbour mapping for requested feature IDs.

Return type:

dict or numba.typed.Dict

upxo.gsdataops.gid_ops.extract_neigh_gid_subset(neigh_fids={}, subset_fids=[], type_correction=True, validate_input=True, verbosity_nfids=1000)[source]

Extract a subset of neigh_fid dict for usert specified fids.

Parameters:

neigh_fidsdict

Dictionary where keys are grain IDs and values are lists of neighbor grain IDs.

subset_fidslist

List of grain IDs to extract from the neighbor lists.

type_correctionbool, optional

If True, convert all grain IDs to integers. Default is True.

validate_inputbool, optional

If True, validate the input types. Default is True.

Returns:

extracted_neigh_fidsdict

Dictionary with the same keys as neigh_fids, but values are lists of neighbor grain IDs that are in subset_fids.

upxo.gsdataops.gid_ops.select_neighs_with_probability(neigh_fids, p=1.0, include_central_grain=False, validate_input=True, verbosity_nfids=1000)[source]

Helper function to select neighbours with a given probability once neighbours have been found.

Usage

import upxo.gsdataops.gid_ops as gidOps Use as: gidOps.select_neighs_with_probability

upxo.gsdataops.gid_ops.shuffleLFIIDs(self, lfi)[source]

Shuffle LFI IDs to randomize grain labels while preserving structure. Usage —– from upxo.gsdataops.gid_ops import shuffleLFIIDs

upxo.gsdataops.gid_ops.find_neighs2d(lfi, conn)[source]

Find neighboring grain IDs in 2D using connected components and region graph. :param lfi: 2D Labelled Feature Image. :type lfi: ndarray :param conn: Connectivity for defining neighbors (e.g., 4 or 8). :type conn: int

Returns:

  • neigh_fids (dict) – Dictionary where keys are grain IDs and values are arrays of neighboring grain IDs.

  • Usage

  • —–

  • from upxo.gsdataops.gid_ops import find_neighs3d

upxo.gsdataops.gid_ops.find_neighs3d(lfi, conn)[source]

Find neighboring grain IDs in 3D using connected components and region graph. :param lfi: 3D Labelled Feature Image. :type lfi: ndarray :param conn: Connectivity for defining neighbors (e.g., 6, 18, or 26). :type conn: int

Returns:

  • neigh_fids (dict) – Dictionary where keys are grain IDs and values are arrays of neighboring grain IDs.

  • Usage

  • —–

  • from upxo.gsdataops.gid_ops import find_neighs3d

upxo.gsdataops.gid_ops.get_nth_order_neighbors(target_fid, neigh_fids, n_order=1)[source]

Recursively finds Nth order neighbors using the neigh_fids dictionary.

Usage

from upxo.gsdataops.gid_ops import get_nth_order_neighbors

upxo.gsdataops.gid_ops.detect_islands(neigh_fids)[source]

Detect grain IDs that have exactly one listed neighbour.

Parameters:

neigh_fids (dict) – Mapping gid -> iterable of neighbouring gids.

Returns:

Grain IDs whose neighbour list length is exactly one.

Return type:

list

Notes

This utility is commonly used with neighbour maps that include the central grain ID itself. In that case, an “island” corresponds to a grain that has no true external neighbours.

upxo.gsdataops.gid_ops.find_small_fids(lfi, threshold)[source]

Find grain IDs whose voxel/pixel count is below or equal to threshold.

Parameters:

  • lfi (ndarray) – N-dimensional Labelled Feature Image.

  • threshold (int) – Maximum allowed size (count) for a feature to be classified as small.

Returns:

1D array of small feature IDs.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_boundary_fids2d(lfi)[source]

Return unique feature IDs touching the outer boundary of a 2D grid.

Parameters:

lfi (ndarray) – 2D Labelled Feature Image.

Returns:

Sorted unique IDs appearing on any of the four outer edges.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_boundary_fids3d(lfi)[source]

Return unique feature IDs touching the outer boundary of a 3D volume.

Parameters:

lfi (ndarray) – 3D Labelled Feature Image.

Returns:

Sorted unique IDs appearing on any of the six outer faces.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_internal_fids2d(lfi)[source]

Return 2D feature IDs that do not touch the domain boundary.

Parameters:

lfi (ndarray) – 2D Labelled Feature Image.

Returns:

Sorted unique IDs present only in the interior.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_internal_fids3d(lfi)[source]

Return 3D feature IDs that do not touch the domain boundary.

Parameters:

lfi (ndarray) – 3D Labelled Feature Image.

Returns:

Sorted unique IDs present only in the interior.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_corner_fids2d(lfi)[source]

Return unique feature IDs located at 2D domain corners.

Parameters:

lfi (ndarray) – 2D Labelled Feature Image.

Returns:

Sorted unique IDs from the four corner pixels.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_corner_fids3d(lfi)[source]

Return unique feature IDs located at 3D domain corners.

Parameters:

lfi (ndarray) – 3D Labelled Feature Image.

Returns:

Sorted unique IDs from the eight corner voxels.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_edge_fids2d(lfi)[source]

Return unique feature IDs present on 2D boundary edges.

Parameters:

lfi (ndarray) – 2D Labelled Feature Image.

Returns:

Sorted unique IDs from all four boundary edges.

Return type:

numpy.ndarray

upxo.gsdataops.gid_ops.find_edge_fids3d(lfi)[source]

Return unique feature IDs present on 3D boundary edges.

Parameters:

lfi (ndarray) – 3D Labelled Feature Image.

Returns:

Sorted unique IDs sampled from the 12 domain edges.

Return type:

numpy.ndarray