From 24bed5d309e15ccc2fe7b46b2892e0a107d0c8af Mon Sep 17 00:00:00 2001 From: Jun Xue Date: Mon, 18 May 2026 16:42:06 +0200 Subject: [PATCH] Add EBSD graph documentation --- docs/method.rst | 110 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/docs/method.rst b/docs/method.rst index 987ff6c5..cb0c2932 100644 --- a/docs/method.rst +++ b/docs/method.rst @@ -121,4 +121,114 @@ The assignment algorithm begins by randomly assigning orientations obtained from .. _Biswas (2019): https://onlinelibrary.wiley.com/doi/full/10.1002/adem.201900275 .. _Kocks (2000): https://www.cambridge.org/de/academic/subjects/engineering/materials-science/texture-and-anisotropy-preferred-orientations-polycrystals-and-their-effect-materials-properties?format=PB&isbn=9780521794206 .. _Miodownik (1999): https://www.sciencedirect.com/science/article/pii/S1359645499001378 + + +------------ +EBSD reading +------------ + +Kanapy can read two dimensional EBSD maps and convert the measured pixel +orientations into a graph representation of the microstructure. The graph is +intended to describe the grain structure on the EBSD map after region +segmentation, graph cleanup, and node merging. It can also be plotted directly +on the EBSD inverse pole figure map for visual inspection. + +The EBSD workflow is handled by :class:`kanapy.texture.EBSDmap`. During map +reading, Kanapy stores the EBSD pixel orientations, separates the retained +phases, and builds graph data for the selected phase. For each phase, the graph +data contains the final graph, diagnostic information from the initial graph, +and merge information from the cleanup procedure. + +Initial region construction +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Initial EBSD regions are identified by local pixel to pixel misorientation. The +procedure is implemented in :func:`kanapy.texture.find_similar_regions_by_misorientation`. +Starting from each unassigned pixel, a breadth first search grows a region by +adding neighboring pixels whose local misorientation is below the selected +threshold. The misorientation calculation uses the crystal symmetry of the +current phase. + +For the two dimensional EBSD graph path, neighboring pixels are evaluated with +4-neighbor connectivity. This gives each pixel direct horizontal and vertical +neighbors on the EBSD map. The resulting labeled regions form the initial graph +nodes. + +Graph construction and node data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The labeled EBSD regions are converted into graph nodes by +:func:`kanapy.texture.build_graph_from_labeled_pixels`. Each graph node +represents one connected labeled region. Node attributes include the pixel list, +the node center, the number of pixels, the original pixel rotations, and the +mean node orientation. + +The mean orientation of a node is computed by +:func:`kanapy.texture.mean_orientation_data`. Pixel quaternions are normalized, +symmetry equivalent orientations are aligned to a reference orientation, and the +``q`` versus ``-q`` quaternion ambiguity is handled before averaging. The final +mean quaternion is obtained from the dominant eigenvector of the quaternion +accumulator matrix. + +Graph edges are added between neighboring labeled regions. Label ``0`` is +treated as background and is not used as a graph node. + +Boundary artifact cleanup +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some small regions can appear mainly along grain boundaries. Kanapy computes +node boundary information with :func:`kanapy.texture.get_node_boundary_stats`. +For each node, the function checks local neighboring pixels and reports +boundary pixel fraction, neighboring labels, map edge contact, bounding box +size, and bounding box fill fraction. + +Small boundary artifact nodes can be merged with +:func:`kanapy.texture.merge_boundary_artifact_nodes`. The merge target is chosen +from neighboring nodes by comparing the node orientations. After node merging, +the mean orientation of the merged node is recomputed from the original pixel +orientations. + +Graph plotting +^^^^^^^^^^^^^^ + +The final EBSD graph can be plotted on the EBSD inverse pole figure map by +setting ``show_graph=True`` when creating an :class:`kanapy.texture.EBSDmap` +object. The graph overlay is produced by +:meth:`kanapy.texture.EBSDmap.plot_graph_overlay`. Node centers are shown as +black points and graph edges are shown as black lines. + +Example usage: + +.. code-block:: python + + import kanapy as knpy + + ebsd = knpy.EBSDmap("p558_250x_1.ang", show_graph=True) + +The same plotting method can also save the graph image to file when an output +path is provided. + +Example scripts +^^^^^^^^^^^^^^^ + +Two example scripts are provided in ``examples/EBSD_graph_analysis``. + +``plot_ebsd_graph_manually.py`` + Runs EBSD graph construction, saves the final graph overlay image, and + writes a short text summary of the graph. The output is written to + ``plot_ebsd_graph_manually_result``. + +``run_ebsd_analysis_with_graph.py`` + Runs the standard EBSD analysis workflow and adds the final graph overlay + by using ``show_graph=True``. + +The manual plotting example produces: + +.. code-block:: text + + plot_ebsd_graph_manually_result/ebsd_graph_overlay.png + plot_ebsd_graph_manually_result/ebsd_graph_summary.txt + +The overlay image shows the final graph node centers and graph edges on the +EBSD inverse pole figure map.