upxo.pxtal.twinned_simple_3d.feature_props_3d module

feature_props_3d.py

Grain and twin morphological property extraction for the twinned simple 3D pipeline.

upxo.pxtal.twinned_simple_3d.feature_props_3d.compute_grain_volumes(lgi: numpy.ndarray, grain_ids: List[int] | None = None) → Dict[int, int][source]

Return voxel count per grain using a single np.bincount pass (O(N_vox)).

upxo.pxtal.twinned_simple_3d.feature_props_3d.compute_twin_volume_fraction(lgi: numpy.ndarray, twin_gids: List[int]) → float[source]

Compute twin VF using a single np.bincount pass (O(N_vox)).

upxo.pxtal.twinned_simple_3d.feature_props_3d.compute_equivalent_diameters(volumes: Dict[int, int], voxel_size: float) → Dict[int, float][source]
upxo.pxtal.twinned_simple_3d.feature_props_3d.grain_role_statistics(volumes: Dict[int, int], twin_role: Dict[int, str], voxel_size: float) → Dict[str, Dict][source]
upxo.pxtal.twinned_simple_3d.feature_props_3d.compute_ebsd_mc_comparison_stats(ebsd_ref: dict, sgc_ref: dict) → dict[source]

Compute side-by-side descriptive statistics comparing the EBSD reference microstructure against the synthetic SGC structure.

Parameters:

  • ebsd_ref (dict) – miso_deg_full - 1-D ndarray EBSD MDF angles (full, with twins) miso_deg_merged - 1-D ndarray EBSD MDF angles (parent-state, merged) twin_thick_um - 1-D ndarray EBSD twin lamella thicknesses (um) host_eqdia_um - 1-D ndarray EBSD pure-parent eq. diameters (um) tvf_2d - scalar EBSD 2D twin area fraction

  • sgc_ref (dict) – miso_deg_posttwin- 1-D ndarray SGC post-twin MDF angles twin_thick_3d_um - 1-D ndarray SGC actual 3D twin thicknesses (um) host_eqdia_um - 1-D ndarray SGC host grain eq. diameters (um) tvf_2d_slices - 1-D ndarray per-slice 2D twin VF values tvf_3d - scalar SGC 3D twin volume fraction

Returns:

Nested dict with keys ‘mdf’, ‘twin_thickness’, ‘host_grain_size’, ‘twin_volume_fraction’, each containing ‘ebsd’ and ‘mc’ sub-dicts of descriptive statistics.

Return type:

dict

upxo.pxtal.twinned_simple_3d.feature_props_3d.print_ebsd_mc_comparison(stats: dict) → None[source]

Print a formatted side-by-side comparison table from the output of compute_ebsd_mc_comparison_stats().

upxo.pxtal.twinned_simple_3d.feature_props_3d.assemble_ebsd_sgs_comparison_data(cleaner, tg, base, rg, parent_info, mdf, twin_thickness, n_slices_per_axis: int = 5, axes=('x', 'y', 'z')) → tuple[source]

Assemble the (ebsd_ref, sgc_ref) raw-array input pair consumed by compute_ebsd_mc_comparison_stats(). Pulled out of SummaryReportPage.on_compute so Distribution Viewer can reuse the exact same assembly for its raw-array overlay plots instead of duplicating it.

Parameters:

  • cleaner (StructureCleaner3D) – Post-twin cleaned structure (lgi_clean, twin_role_clean, all_quats_clean).

  • tg (TwinGenerator3D) – Post-introduction twin generator (twin_halfwidths_vox, summary(), compute_achieved_2d_tvf, base).

  • base (TwinnedSimple3DBase) – Pre-twin host structure (mprop['eqdia'], host_grain_ids).

  • rg (repgen2d) – EBSD reference (lfi_ebsd_merged, quat_ebsd, prop_ebsd).

  • parent_info (dict) – Output of rg.identify_parent_grains.

  • mdf (dict) – Full EBSD MDF, output of rg.compute_mdf_ebsd (must carry 'miso_deg').

  • twin_thickness (dict) – Output of rg.compute_mc_twin_thickness (must carry 'thick_um').

  • n_slices_per_axis – Forwarded to tg.compute_achieved_2d_tvf for the SGS 2D-slice twin-area-fraction distribution.

  • axes – Forwarded to tg.compute_achieved_2d_tvf for the SGS 2D-slice twin-area-fraction distribution.

Returns:

(ebsd_ref, sgc_ref) – See compute_ebsd_mc_comparison_stats()’s parameter docs.

Return type:

tuple of dict

upxo.pxtal.twinned_simple_3d.feature_props_3d.compute_sgs_role_property_distributions(lgi_clean: numpy.ndarray, twin_role_clean: Dict[int, str], twin_parent_of_clean: Dict[int, int], selected_props: List[str], selected_levels: List[str], n_slices_per_axis: int = 5, axes=('x', 'y', 'z'), voxel_size: float = 1.0) → Dict[str, Dict[str, numpy.ndarray]][source]

Per-twin-role-level distributions of area / aspect_ratio / perimeter / solidity / n_neighbours, sampled from 2D cross-sections of the cleaned 3D structure – the SGS-side equivalent of EBSD’s inherently-2D grain morphology, so the two are directly comparable. Mirrors TwinGenerator3D.compute_achieved_2d_tvf’s slice-sampling convention (evenly-spaced slices per axis, native axis-label mapping, no re-labelling – a grain’s 2D cross-section keeps its 3D grain ID, so twin_role_clean/twin_parent_of_clean apply directly).

Parameters:

  • lgi_clean (ndarray (nz, ny, nx)) – cleaner.lgi_clean – pipeline-native axis order.

  • twin_role_clean (dict) – cleaner.twin_role_clean / cleaner.twin_parent_of_clean.

  • twin_parent_of_clean (dict) – cleaner.twin_role_clean / cleaner.twin_parent_of_clean.

  • selected_props (list of str) – Subset of ('area', 'aspect_ratio', 'perimeter', 'solidity', 'n_neighbours').

  • selected_levels (list of str) – Subset of ('nonhost', 'host', 'primary', 'seca', 'secb').

  • n_slices_per_axis – Evenly-spaced 2D cross-sections sampled per axis in axes.

  • axes – Evenly-spaced 2D cross-sections sampled per axis in axes.

  • voxel_size (float) – Physical voxel edge length (um); scales area (um^2) and perimeter (um).

Returns:

{prop_name: {level_key: ndarray}}.

Return type:

dict

upxo.pxtal.twinned_simple_3d.feature_props_3d.format_size(n)[source]

Human-readable file size (B/KB/MB/GB/TB).

upxo.pxtal.twinned_simple_3d.feature_props_3d.build_summary_markdown_lines(role_stats, tvf_final_3d, tvf_ebsd_target, comparison_stats=None)[source]

Formats grain-role volume statistics + twin volume fraction summary (and, if given, the full EBSD-vs-MC comparison) as Markdown lines. Pure formatting, no file I/O – shared by every report writer that needs this summary, so all embed byte-identical content when the same data is available.