Batch 3, Tier 3 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 | 6 | In Progress |
+| 3 | Segmentation / Feature Identification | 10 | 10 | 10 | Complete |
 | 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 |
@@ -327,46 +327,46 @@ The following batches have been identified in the design spec but have not yet b
 
 | Filter | Plugin | Status |
 |--------|--------|--------|
-| IdentifySample | SimplnxCore | Pending |
-| ComputeSurfaceFeatures | SimplnxCore | Pending |
-| ComputeBiasedFeatures | SimplnxCore | Pending |
-| RemoveFlaggedFeatures | SimplnxCore | Pending |
+| IdentifySample | SimplnxCore | Done |
+| ComputeSurfaceFeatures | SimplnxCore | Done |
+| ComputeBiasedFeatures | SimplnxCore | Done |
+| RemoveFlaggedFeatures | SimplnxCore | Done |
 
-- [ ] **IdentifySampleFilter** (SimplnxCore)
+- [x] **IdentifySampleFilter** (SimplnxCore)
   - **Clarity:** Clear purpose (remove overscan border), steps well explained, slice-by-slice option well documented.
   - **Completeness:** Good example images showing when to use vs when not to use the filter.
   - **Accessibility:** FIB-SEM mentioned but not critical to understanding; typo: "thresheld" should be "thresholded".
   - **Figures Needed:** Already adequate; could add a before/after showing cleanup effect on a real overscanned dataset.
   - **Real-World Viz:** Already has good/bad-dataset examples.
   - **Concept Links:** thresholding, sample identification, contiguous regions
-  - **Notes:** Title "Isolate Largest Feature (Identify Sample)" is inconsistent with other filter titles — consider standardizing. Fix typo "thresheld". Light prose polish.
+  - **Changes Made:** Fixed typo "thresheld" → "thresholded". Rewrote intro prose for readability (shorter sentences, active voice). Added explicit link to Multi-Threshold Objects as the typical mask source. Added Required Input Sources. Title preserved as it matches the filter's humanName().
 
-- [ ] **ComputeSurfaceFeaturesFilter** (SimplnxCore)
+- [x] **ComputeSurfaceFeaturesFilter** (SimplnxCore)
   - **Clarity:** Purpose clear; algorithm clear; two WARNING sections are helpful and well-placed.
   - **Completeness:** Broken/truncated sentence on line 9: "the Cells that sit at either ." — should be completed or deleted. Intro paragraph and the "This Filter determines..." paragraph are partially redundant.
   - **Accessibility:** Feature ID=0 convention referenced in a warning but could use an inline first-use definition.
   - **Figures Needed:** Already has good example output images.
   - **Real-World Viz:** Already present.
   - **Concept Links:** Feature ID=0, surface features, bounding box
-  - **Notes:** Fix broken sentence on line 9. Consolidate the two intro paragraphs to remove redundancy.
+  - **Changes Made:** Deleted broken truncated sentence. Consolidated the two redundant intro paragraphs into one. Added inline definition of Feature ID = 0 (the "unassigned / outside sample" convention) with cross-link to IdentifySample. Added cross-link to ComputeBiasedFeatures as the more rigorous approach to boundary bias. Added Required Input Sources.
 
-- [ ] **ComputeBiasedFeaturesFilter** (SimplnxCore)
+- [x] **ComputeBiasedFeaturesFilter** (SimplnxCore)
   - **Clarity:** Algorithm and rationale well explained; before/after example figure is strong.
   - **Completeness:** Good — explains why larger features are more likely to be biased and why bounding-box logic works.
   - **Accessibility:** Most terms defined inline; credit to Dave Rowenhorst retained.
   - **Figures Needed:** Already adequate.
   - **Real-World Viz:** Already present.
   - **Concept Links:** stereology, feature centroids, bounding-box bias, unbiased statistics
-  - **Notes:** Add a short lead-in explaining the statistical/stereology context — *why* unbiased features matter (correct size distributions, correct ODFs, etc.).
+  - **Changes Made:** Added "Why Bias Matters for Statistics" section explaining the size-dependent sampling bias — why excluding only surface-touching features still leaves bias, and why centroid-based bounding-box logic fixes it. Cross-linked ComputeSurfaceFeatures. Added Required Input Sources.
 
-- [ ] **RemoveFlaggedFeaturesFilter** (SimplnxCore)
+- [x] **RemoveFlaggedFeaturesFilter** (SimplnxCore)
   - **Clarity:** Three operations (Remove / Extract / Extract then Remove) well documented.
   - **Completeness:** NeighborList warning present; no Example Pipeline link populated.
   - **Accessibility:** "isotropically coarsened" is jargon (same issue as RequireMinimumSizeFeatures).
   - **Figures Needed:** Before/after showing each of the three operation modes; at least a side-by-side of Remove vs Extract.
   - **Real-World Viz:** Microstructure showing extraction vs removal outcomes.
   - **Concept Links:** feature cleanup, isotropic coarsening, feature extraction
-  - **Notes:** Align "isotropically coarsened" phrasing with RequireMinimumSizeFeatures (shared definition). Add an Example Pipeline reference.
+  - **Changes Made:** Rewrote description to position this filter as the general-purpose flag-based removal tool and cross-reference RequireMinimumSizeFeatures for size-based use. Linked "isotropic coarsening" to the definition in RequireMinimumSizeFeatures rather than repeating. Cleaned up operation list phrasing. Converted NeighborList warning to sub-heading. Added Required Input Sources listing typical flag-producing filters (ComputeBiasedFeatures, ComputeSurfaceFeatures).
 
 ---
 

src/Plugins/SimplnxCore/docs/ComputeBiasedFeaturesFilter.md

@@ -6,7 +6,15 @@ Generic (Spatial)
 
 ## Description
 
-This **Filter** determines which **Features** are *biased* by the outer surfaces of the sample. Larger **Features** are more likely to intersect the outer surfaces and thus it is not sufficient to only note which **Features** touch the outer surfaces of the sample. Denoting which **Features** are biased is important so that they may be excluded from any statistical analyses. The algorithm for determining whether a **Feature** is *biased* is as follows:
+This **Filter** flags each **Feature** as *biased* or *unbiased* by the outer surfaces of the sample, producing a feature-level boolean array suitable for excluding biased features from downstream statistical analyses (size distributions, shape distributions, ODFs, etc.).
+
+### Why Bias Matters for Statistics
+
+When a sample volume is cut out of a larger material, some grains are truncated by the cut. If only size or shape statistics are needed, surface-touching features like those flagged by [Compute Surface Features](ComputeSurfaceFeaturesFilter.md) can be excluded -- but that undercounts the problem. Larger grains are more likely to touch any given surface simply because they are larger, so excluding only surface-touching features still leaves a size-dependent sampling bias: *small* grains that don't touch the surface are over-represented relative to *large* grains that do. The biased-feature flag produced here corrects for this by identifying which features' centroids are close enough to a boundary that they are statistically suspect, regardless of whether the feature itself touches the boundary.
+
+### How This Filter Works
+
+The algorithm for determining whether a **Feature** is *biased* is as follows:
 
 1. The *centroids* of all **Features** are calculated
 2. All **Features** are tested to determine if they touch an outer surface of the sample
@@ -22,6 +30,12 @@ By definition of the box, no **Feature** that intersects an outer surface of the
 The images below show the feature ids before and after running this filter. The image on the right shows the biased features colored in red, the unbiased features colored by their feature id, the bounding box (described in step 3 of the algorithm above), and the feature centroids (white for unbiased and purple for biased).
 ![2D Before and After Biased Features](Images/ComputeBiasedFeaturesBeforeAndAfter.png)
 
+### Required Input Sources
+
+- **Feature Centroids** -- produced by [Compute Feature Centroids](ComputeFeatureCentroidsFilter.md).
+- **Surface Features** -- produced by [Compute Surface Features](ComputeSurfaceFeaturesFilter.md) or as an optional output of [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md).
+- **Feature Phases** (only when applying to a single phase) -- produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md).
+
 % Auto generated parameter table will be inserted here
 
 ## Example Pipelines

src/Plugins/SimplnxCore/docs/ComputeSurfaceFeaturesFilter.md

@@ -6,14 +6,14 @@ Generic (Spatial)
 
 ## Description
 
-This **Filter** determines whether a **Feature** touches an outer surface of the sample. This is accomplished by simply querying the **Feature** owners of the **Cells** that sit at either . Any **Feature** that owns one of those **Cells** is said to touch an outer surface and all other **Features** are said to not touch an outer surface of the sample.
+This **Filter** flags each **Feature** with whether it touches an outer surface of the sample volume. The output is a feature-level boolean array where *false* (0) means the feature is fully enclosed in the interior and *true* (1) means at least one of its cells sits on the sample surface.
 
-This **Filter** determines whether a **Feature** touches an outer *Surface* of the sample volume. A **Feature** is considered touching the *Surface* of the sample if either of the following conditions are met:
+A **Feature** is considered a "surface feature" if either of the following is true:
 
-+ Any cell location is x<sub>min</sub>, x<sub>max</sub>, y<sub>min</sub>, y<sub>max</sub>, z<sub>min</sub> or z<sub>max</sub>
-+ Any cell has **Feature ID = 0** as a neighbor.
+- Any of its cells sits on the outermost voxel layer of the geometry -- i.e., a cell location equal to x<sub>min</sub>, x<sub>max</sub>, y<sub>min</sub>, y<sub>max</sub>, z<sub>min</sub>, or z<sub>max</sub>.
+- Any of its cells has a neighbor with **Feature ID = 0**. (Feature ID 0 is the "unassigned" / "outside sample" label, typically produced by a mask or by [Isolate Largest Feature](IdentifySampleFilter.md).)
 
-The output of this filter is a **Feature** level array of booleans where 0=Interior/Not touching and 1=Surface/Touching.
+Surface features are usually excluded from size distributions, neighbor statistics, and other analyses because their measured volume is artificially truncated by the sample boundary. See [Compute Biased Features](ComputeBiasedFeaturesFilter.md) for a more statistically rigorous treatment of boundary bias.
 
 ### WARNING - Feature ID=0 Voxels
 
@@ -34,6 +34,10 @@ If the structure/data is actually 2D, then the dimension that is planar is not c
 | ![ComputeSurfaceFeatures_Cylinder](Images/ComputeSurfaceFeatures_Cylinder.png) |  ![ComputeSurfaceFeatures_Square](Images/ComputeSurfaceFeatures_Square.png) |
 | Example showing features touching Feature ID=0 (Black voxels) "Mark Feature 0 Neighbors" is **ON** | Example showing features touching the outer surface of the bounding box |
 
+### Required Input Sources
+
+- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md).
+
 % Auto generated parameter table will be inserted here
 
 ## Example Pipelines

src/Plugins/SimplnxCore/docs/IdentifySampleFilter.md

@@ -6,21 +6,21 @@ Processing (Cleanup)
 
 ## Description
 
-Often when performing a serial sectioning experiment (especially in the FIB-SEM), the sample is *over scanned* resulting 
-in a border of *bad* data around the sample.  This **Filter** attempts to *identify* the sample within the over scanned 
-volume.  The **Filter** makes the assumption that there is only one contiguous set of **Cells** that belong to the sample. 
-The **Filter** requires that the user has already *thresheld* the data to determine which **Cells** are *good* and which 
-are *bad*.  The algorithm for the identification of the sample is then as follows:
+Serial-sectioning experiments -- especially FIB-SEM -- typically *over-scan* the sample area, producing a border of *bad* data around the actual sample. This **Filter** identifies the sample within that over-scanned volume by finding the single largest contiguous region of *good* cells.
 
-1. Search for the largest contiguous set of *good* **Cells**. (This is assumed to be the sample)
-2. Change all other *good* **Cells**  to be *bad* **Cells**.  (This removes the "speckling" of what was *threshold* as *good* data in the outer border region)
+The filter assumes that the sample is one connected set of cells, and it requires that the user has already produced a boolean mask marking which cells are *good* and which are *bad* -- typically via [Multi-Threshold Objects](MultiThresholdObjectsFilter.md) applied to a confidence or quality array.
 
-If *Fill Holes* is set to *true* additional steps are taken:
+The algorithm is:
 
-1. Search for the largest contiguous set of *bad* **Cells**. (This is assumed to be the outer border region)
-2. Change all other *bad* **Cells**  to be *good* **Cells**. (This removes the "speckling" of what was *threshold* as *bad* data inside the sample).
+1. Search for the largest contiguous set of *good* cells. This is assumed to be the sample.
+2. Change all other *good* cells to *bad*. (This removes the "speckling" of *good* cells in the outer border region.)
 
-*Note:* if there are in fact "holes" in the sample, then this **Filter** will "close" them (if *Fill Holes* is set to true) by calling all the **Cells** "inside" the sample *good*.  If the user wants to reidentify those holes, then reuse the threshold **Filter** with the criteria of *GoodVoxels = 1* and whatever original criteria identified the "holes" as this will limit applying those original criteria to within the sample and not the outer border region.
+If *Fill Holes* is enabled, two additional steps are run:
+
+1. Search for the largest contiguous set of *bad* cells. This is assumed to be the outer border region.
+2. Change all other *bad* cells to *good*. (This removes the "speckling" of *bad* cells inside the sample.)
+
+*Note:* If the sample contains real holes, enabling *Fill Holes* will close them by calling all cells "inside" the sample *good*. To reidentify those holes afterward, re-run the threshold filter with the criteria *GoodVoxels = 1* AND whatever original criterion identified the holes. This limits the original hole-finding criteria to within the sample and not the outer border region.
 
 ## Slice-By-Slice Option
 
@@ -46,6 +46,10 @@ When *Process Data Slice-By-Slice* is enabled, the *Slice-By-Slice Plane* parame
 - **XZ [1]**: Processes the volume slice by slice along the Y axis, scanning each XZ plane independently.
 - **YZ [2]**: Processes the volume slice by slice along the X axis, scanning each YZ plane independently.
 
+### Required Input Sources
+
+- **Good Voxels Mask** -- a boolean array marking cells as *good* or *bad*, typically produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md) applied to EBSD confidence index, image quality, or a similar scalar.
+
 % Auto generated parameter table will be inserted here
 
 ## Example Pipelines

src/Plugins/SimplnxCore/docs/RemoveFlaggedFeaturesFilter.md

@@ -6,23 +6,30 @@ Processing (Cleanup)
 
 ## Description
 
-This **Filter** will remove **Features** that have been flagged by another **Filter** from the structure.  The **Filter** requires that the user point to a boolean array at the **Feature** level that tells the **Filter** whether the **Feature** should remain in the structure.  If the boolean array is *false* for a **Feature**, then all **Cells** that belong to that **Feature** are temporarily *unassigned*. Optionally, after all *undesired* **Features** are removed, the remaining **Features** are isotropically coarsened to fill in the gaps left by the removed **Features**.
+This **Filter** removes or extracts **Features** that have been flagged by an earlier filter in the pipeline. The user supplies a boolean array at the **Feature** level; features with a value of *false* are targeted for removal (or extraction). Removed features leave gaps in the cell-level **Feature Ids** array, which are then filled by [isotropic coarsening](RequireMinimumSizeFeaturesFilter.md) -- neighboring features grow outward uniformly until every cell is reassigned to a surviving feature.
+
+This filter is the general-purpose tool for discarding features based on any criterion you can express as a boolean flag (biased features, minority phases, user-selected grains, etc.). For the specific case of removing features smaller than a size threshold, see [Remove Minimum Size Features](RequireMinimumSizeFeaturesFilter.md) instead.
 
 ### Selected Operation
 
 The *Selected Operation* parameter provides the following choices:
 
-- **Remove [0]**: Removes the flagged **Features** from the geometry and coarsens remaining features to fill the gaps.
-- **Extract [1]**: Extracts the flagged **Features** into a new separate geometry without removing them from the original.
-- **Extract then Remove [2]**: Extracts the flagged **Features** into a new geometry and then removes them from the original geometry.
+- **Remove [0]**: Remove the flagged **Features** from the geometry. Neighboring features grow outward isotropically to fill the gaps.
+- **Extract [1]**: Copy the flagged **Features** into a new separate geometry without modifying the original.
+- **Extract then Remove [2]**: Copy the flagged **Features** into a new geometry and then remove them from the original (combining the previous two modes).
+
+### WARNING: NeighborList Removal
+
+When the operation is *Remove* or *Extract then Remove*, any *NeighborList* arrays in the Cell Feature **Attribute Matrix** will be **removed** because the neighbor relationships have changed. Re-run [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) afterward to rebuild them.
 
-## WARNING: NeighborList Removal
+### Caveats
 
-If the operation is [0] or [2] and the Cell Feature AttributeMatrix contains any *NeighborList* data arrays, those arrays will be **REMOVED** because those lists are now invalid. Re-run the *Find Neighbors* filter to re-create the lists.
+This filter will **only** run on an **Image Geometry**.
 
-## Caveats
+### Required Input Sources
 
-This filter will **ONLY** run on an Image Geometry.
+- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md).
+- **Flag Array** -- a boolean feature-level array. Typical producers: [Compute Biased Features](ComputeBiasedFeaturesFilter.md), [Compute Surface Features](ComputeSurfaceFeaturesFilter.md), or a custom flag built via threshold/boolean operations on any feature-level statistic.
 
 % Auto generated parameter table will be inserted here