Batch 3, Tier 2 Filters reviewed

Author: imikejackson

docs/documentation_review_tracker.md

@@ -12,7 +12,7 @@
 |-------|----------|---------------|---------|-----------|--------|
 | 1 | Orientation / Crystallography Statistics | 17 | 17 | 17 | Complete |
 | 2 | Alignment Filters | 5 | 5 | 5 | Complete |
-| 3 | Segmentation / Feature Identification | 10 | 10 | 1 | In Progress |
+| 3 | Segmentation / Feature Identification | 10 | 10 | 6 | In Progress |
 | 4 | Neighbor / Kernel Operations | ~12 | 0 | 0 | Not Started |
 | 5 | Geometry Creation / Manipulation | ~15 | 0 | 0 | Not Started |
 | 6 | Data Manipulation (Copy, Create, Delete, Rename) | ~20 | 0 | 0 | Not Started |
@@ -267,61 +267,61 @@ The following batches have been identified in the design spec but have not yet b
 
 | Filter | Plugin | Status |
 |--------|--------|--------|
-| ScalarSegmentFeatures | SimplnxCore | Pending |
-| CAxisSegmentFeatures | OrientationAnalysis | Pending |
-| EBSDSegmentFeatures | OrientationAnalysis | Pending |
-| RequireMinimumSizeFeatures | SimplnxCore | Pending |
-| ComputeFeatureNeighbors | SimplnxCore | Pending |
+| ScalarSegmentFeatures | SimplnxCore | Done |
+| CAxisSegmentFeatures | OrientationAnalysis | Done |
+| EBSDSegmentFeatures | OrientationAnalysis | Done |
+| RequireMinimumSizeFeatures | SimplnxCore | Done |
+| ComputeFeatureNeighbors | SimplnxCore | Done |
 
-- [ ] **ScalarSegmentFeaturesFilter** (SimplnxCore)
+- [x] **ScalarSegmentFeaturesFilter** (SimplnxCore)
   - **Clarity:** Burn algorithm steps clear, but term "burn algorithm" undefined; no introduction to what segmentation accomplishes conceptually.
   - **Completeness:** Neighbor scheme well documented with 4 paired figure sets. No guidance on tolerance values (tolerance is in whatever units the scalar array uses).
   - **Accessibility:** "Cells" and "Features" used without first-use definition; bold emphasis is stylistic rather than explanatory.
   - **Figures Needed:** Neighbor-scheme figures already excellent; could add a simple "what is segmentation" before/after conceptual diagram.
   - **Real-World Viz:** Before/after FeatureIds map from a scalar-based segmentation (e.g., image-quality thresholding).
   - **Units Clarity:** Tolerance has no explicit units — depends entirely on input array data type; this must be stated.
   - **Concept Links:** Feature IDs, burn algorithm, segmentation, Cell vs Feature data
-  - **Notes:** Structural twin of CAxisSegment/EBSDSegment. Shares neighbor scheme figures. Add short intro explaining what segmentation produces (FeatureIds) and how to pick a tolerance.
+  - **Changes Made:** Added lead-in describing the FeatureIds output and cross-referencing the two orientation-based segment filters. Added "What is Feature Segmentation?" conceptual section. Rewrote algorithm into a burn-algorithm step list. Added "Tolerance and Units" section with concrete examples for integer phase maps, 0-1 image quality, and 0-255 grayscale. Added "Mask Array" and "Periodic Option" sections. Added Required Input Sources with cross-plugin links.
 
-- [ ] **CAxisSegmentFeaturesFilter** (OrientationAnalysis)
+- [x] **CAxisSegmentFeaturesFilter** (OrientationAnalysis)
   - **Clarity:** Brief C-axis definition provided, but assumes hexagonal-system knowledge; no guidance on when to use this vs EBSDSegmentFeatures.
   - **Completeness:** Shares structure and neighbor scheme figures with other segment filters. Missing: explicit hexagonal-only warning, phase handling, when-to-use guidance.
   - **Accessibility:** `<001>`, hexagonal system, C-axis all used without plain-language expansion.
   - **Figures Needed:** Reuse hexagonal C-axis figure from ComputeAvgCAxes (Batch 1); add a "C-axis misalignment between two neighboring cells" diagram.
   - **Real-World Viz:** Before/after segmentation on hexagonal (e.g., Ti) EBSD data.
   - **Units Clarity:** Tolerance is in **degrees** — must be stated explicitly in the parameter description.
   - **Concept Links:** C-axis, hexagonal materials, burn algorithm, reference frames
-  - **Notes:** Link to ComputeAvgCAxes for the C-axis explanation. Add "When to Use" guidance — hexagonal-only, when grain distinction needs to come from C-axis alignment rather than full orientation.
+  - **Changes Made:** Added explicit hexagonal-only warning at the top with cross-references to alternative segment filters. Added "When to Use This Filter" explaining why C-axis alignment is the right criterion for hexagonal materials and when to use misorientation-based segmentation instead. Rewrote algorithm steps; added "Tolerance and Units" with degree units and typical values (1-3 / 5 / 10+). Added Required Input Sources linking ComputeAvgCAxes for C-axis concept.
 
-- [ ] **EBSDSegmentFeaturesFilter** (OrientationAnalysis)
+- [x] **EBSDSegmentFeaturesFilter** (OrientationAnalysis)
   - **Clarity:** Generic term "misorientation" used without definition; core burn algorithm clear but domain context missing.
   - **Completeness:** No guidance on typical tolerance values (5° is the common industry default for grain segmentation); no mention of how multiple phases are handled.
   - **Accessibility:** Assumes EBSD workflow and misorientation knowledge.
   - **Figures Needed:** Misorientation angle diagram (shared with Batch 1 misorientation concept work); before/after segmentation example.
   - **Real-World Viz:** EBSD IPF map → segmented grains visualization — this is one of the highest-value workflow visualizations in DREAM3DNX.
   - **Units Clarity:** Tolerance is in **degrees** — must be stated explicitly.
   - **Concept Links:** misorientation, EBSD workflow, burn algorithm, reference frames, grain segmentation
-  - **Notes:** This is the flagship segmentation filter for EBSD workflows. Needs a "Typical Values" section (5° for most grain segmentation; tighter for subgrain analysis).
+  - **Changes Made:** Added "What is Misorientation-Based Segmentation?" section explaining grains and misorientation for non-experts. Rewrote algorithm into numbered burn steps including symmetry handling. Added "Typical Tolerance Values" section with 5° industry default, 2-3° for subgrains, 10-15° high-angle cutoff. Added "Phase Handling" explaining different-phase and phase-0 behavior. Added "Mask Array" and "Periodic Option" sections. Added Required Input Sources.
 
-- [ ] **RequireMinimumSizeFeaturesFilter** (SimplnxCore)
+- [x] **RequireMinimumSizeFeaturesFilter** (SimplnxCore)
   - **Clarity:** Core action (remove features below size threshold) clear, but "isotropically coarsened" is unexplained jargon.
   - **Completeness:** Has good warnings (feature data invalidation, NeighborList removal); no guidance on typical minimum-size values.
   - **Accessibility:** "Ensemble" bolded but not defined; "isotropically coarsened" needs a plain-language explanation.
   - **Figures Needed:** Before/after showing small features removed and gaps filled; diagram of isotropic coarsening (neighbors growing outward uniformly).
   - **Real-World Viz:** Before/after microstructure with minimum-size filter applied.
   - **Units Clarity:** Minimum size is in **cells** (integer voxel count) — must be stated explicitly.
   - **Concept Links:** feature cleanup, isotropic coarsening, Ensemble, NeighborList invalidation
-  - **Notes:** Define "isotropically coarsened" (neighboring features grow outward uniformly to fill removed-voxel gaps). State units on the minimum-size parameter.
+  - **Changes Made:** Added lead-in explaining typical use (discarding spurious single-cell grains after segmentation). Added "What is Isotropic Coarsening?" section with plain-language explanation. Added "Minimum Size Units" section stating units are **cells** (integer voxel count), with a formula for converting physical volume to cell count. Rewrote the "Single Phase" option more clearly. Kept existing warnings. Added Required Input Sources.
 
-- [ ] **ComputeFeatureNeighborsFilter** (SimplnxCore)
+- [x] **ComputeFeatureNeighborsFilter** (SimplnxCore)
   - **Clarity:** Algorithm steps clear, but the multiple output arrays are described inline in running prose and hard to scan.
   - **Completeness:** Mentions several outputs (neighbor count, shared surface area, boundary-cell count, surface-feature flag) but all buried in a single paragraph.
   - **Accessibility:** Face-sharing neighbor concept not illustrated; implicit assumption that user knows what a NeighborList is.
   - **Figures Needed:** Diagram showing feature-to-feature shared boundary with shared surface area highlighted.
   - **Real-World Viz:** Grain map colored by number of neighbors; or shared-surface-area visualization.
   - **Units Clarity:** Shared surface area is in **cell-face units** (dimensionless count of shared faces, not physical area) — should be stated.
   - **Concept Links:** contiguous neighbors, Feature IDs, shared surface area, NeighborList
-  - **Notes:** Restructure output descriptions as a bulleted list instead of one prose paragraph. Explain what each output array is used for downstream.
+  - **Changes Made:** Rewrote lead-in describing why downstream filters depend on this (misorientation stats, GBCD, twin merging, boundary strengths). Separated algorithm steps from output descriptions. Added "What This Filter Produces" section with bulleted list of the three main outputs plus two optional outputs; explained each output's downstream use. Explicitly stated shared surface area units are **cell-face count**, not physical area. Added Required Input Sources.
 
 ### Tier 3 — Polish
 

src/Plugins/OrientationAnalysis/docs/CAxisSegmentFeaturesFilter.md

@@ -6,17 +6,35 @@ Reconstruction (Segmentation)
 
 ## Description
 
-This **Filter** segments the **Features** by grouping neighboring **Cells** that satisfy the *C-axis misalignment tolerance*, i.e., have misalignment angle less than the value set by the user. The *C-axis misalignment* refers to the angle between the <001> directions (C-axis in the hexagonal system) that is present between neighboring **Cells**.  The process by which the **Features** are identified is given below and is a standard *burn algorithm*.
+This **Filter** groups neighboring **Cells** (voxels) whose crystal C-axes are nearly aligned into **Features** (grains), producing a *FeatureIds* array that labels every cell in the input **Image Geometry** with a grain number.
 
-1. Randomly select a **Cell**, add it to an empty list and set its *Feature Id* to the current **Feature**
-2. Compare the **Cell** to each of its six (6) face-sharing neighbors (i.e., calculate the c-axis misalignment with each neighbor)
-3. Add each neighbor **Cell** that has a C-axis misalignment below the user defined tolerance to the list created in 1. and set the *Feature Id* of the neighbor **Cell** to the current **Feature**
-4. Remove the current **Cell** from the list and move to the next **Cell** and repeat 2. and 3.; continue until no **Cells** are left in the list
-5. Increment the current **Feature** counter and repeat steps 1. through 4.; continue until no **Cells** remain unassigned in the dataset
+This filter is **only valid for hexagonal phases**. For general EBSD grain segmentation (cubic, orthorhombic, or any other symmetry), use [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md) instead; for scalar-based segmentation, use [Segment Features (Scalar)](../SimplnxCore/ScalarSegmentFeaturesFilter.md).
 
-The user has the option to *Use Mask Array*, which allows the user to set a boolean array for the **Cells** that remove **Cells** with a value of *false* from consideration in the above algorithm. This option is useful if the user has an array that either specifies the domain of the "sample" in the "image" or specifies if the orientation on the **Cell** is trusted/correct.
+### When to Use This Filter
 
-After all the **Features** have been identified, a **Feature Attribute Matrix** is created for the **Features** and each **Feature** is flagged as *Active* in a boolean array in the matrix.
+In hexagonal materials (titanium, magnesium, zinc, zirconium, etc.), the [C-axis](ComputeAvgCAxesFilter.md) is the unique, mechanically significant crystal direction. For many studies -- especially those focused on basal-plane slip, texture, or deformation -- it is more informative to group cells by how closely their C-axes point in the same direction than by their full orientation. Two cells may have very different full orientations (rotated differently about their own C-axis) but still belong to the same grain if their C-axes point the same way.
+
+If you need full misorientation-based grain segmentation (accounting for rotations about the C-axis), use [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md) instead.
+
+### How This Filter Works
+
+The filter uses a standard *burn algorithm* to grow each feature outward from a seed cell:
+
+1. Randomly pick an unassigned **Cell** and give it a new *Feature Id*.
+2. Compute the angle between the C-axis of the seed cell and the C-axis of each neighbor (see **Neighbor Scheme** below).
+3. Any neighbor whose C-axis misalignment angle is less than the user-specified *Misalignment Tolerance* (in **degrees**) is added to the current feature and gets the same *Feature Id*.
+4. Repeat step 2-3 from each newly added cell, growing the feature outward until no more neighbors qualify.
+5. Increment the feature counter and pick a new unassigned seed cell. Continue until every eligible cell has been assigned.
+
+The C-axis direction for each cell is computed on-the-fly from the cell's orientation quaternion. See [Compute Average C-Axis Orientations](ComputeAvgCAxesFilter.md) for a full explanation of the C-axis concept and why it only makes physical sense for hexagonal symmetries.
+
+### Tolerance and Units
+
+The *Misalignment Tolerance* is in **degrees**. Typical values:
+
+- **1-3 degrees** -- very tight; splits grains with even slight C-axis variation (subgrains).
+- **5 degrees** -- the common default for grain segmentation.
+- **10+ degrees** -- loose; merges adjacent grains whose C-axes are within a cone.
 
 ### Neighbor Scheme
 
@@ -25,11 +43,7 @@ The *Neighbor Scheme* parameter provides the following choices:
 - **Face Neighbors [0]**: Only the 6 face-sharing neighbors of a voxel are considered during segmentation.
 - **All Connected Neighbors [1]**: All 26 neighbors connected by a face, edge, or vertex are considered during segmentation.
 
-## Note on Neighbor Scheme
-
-Historically DREAM.3D version 6.x has used *only* the 6 face neighbors of a voxel. This release introduces the option
-of using all 26 neighboring voxels that are connected by a face, edge or vertex. The default for the filter
-is to still use the 6 face neighbors ("Face Only") in order to stay consistent with the output from DREAM.3D version 6.x.
+DREAM.3D version 6.x only used face neighbors. The default here is still *Face Only* for backward compatibility.
 
 | Neighbor Scheme = "Face Only" | Neighbor Scheme = "All Connected" |
 |:--:|:--:|
@@ -47,6 +61,17 @@ is to still use the 6 face neighbors ("Face Only") in order to stay consistent w
 |:--:|:--:|
 | ![Shared Edges & Points With Disconnected Region - "Face Only"](Images/SegmentFeatures/combination_face_only.png) | ![Shared Edges & Points With Disconnected Region - "All Connected"](Images/SegmentFeatures/combination_all_connected.png) |
 
+### Mask Array
+
+If *Use Mask Array* is enabled, cells flagged *false* in the mask are excluded from segmentation and left with a Feature Id of 0. Masks are commonly used to restrict segmentation to the sample region or to cells with reliable orientation data (for example, a threshold on an EBSD confidence index).
+
+### Required Input Sources
+
+- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.md); can also be produced from Euler angles by [Convert Orientations](ConvertOrientationsFilter.md).
+- **Cell Phases** -- typically read from EBSD data alongside the quaternions.
+- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). Phases that are not hexagonal will produce invalid segmentation for those cells.
+- **Mask Array** (optional) -- a boolean array marking valid cells, typically produced by [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md).
+
 % Auto generated parameter table will be inserted here
 
 ## Example Pipelines