diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5f1d38f26b..0000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,308 +0,0 @@ -# Project Guidelines for Claude - -## Project Overview - -[SIMPLNX Issue 1284](https://github.com/BlueQuartzSoftware/simplnx/issues/1284) -I would like to work on this issue more by converting Filters that have anything more than a trivial execute implementation to move that implementation to an "Algorithm" class like the bulk of the other filters. - -The Algorithm files are located in src/Plugins/SimplnxCore/src/SimplnxCore/Filters/Algorithms/not_used. - -Look at the other filters and understand how we create the Algorithm classes and follow that same style. - -Each Algorithm class that gets updated should be moved out of the "not_used" folder. - -If anything is ambiguous please ask. - -## Directory Structure -- `src/simplnx/` - Core library (Common, Core, DataStructure, Filter, Parameters, Pipeline, Plugin, Utilities) -- `src/Plugins/` - Plugin modules -- `src/nxrunner/` - CLI runner -- `test/` - Test files -- `cmake/` - CMake configuration -- Additional Plugin at "/Users/mjackson/Workspace1/DREAM3D_Plugins/SimplnxReview" -- Additional Plugin at "/Users/mjackson/Workspace1/DREAM3D_Plugins/FileStore" -- Additional Plugin at "/Users/mjackson/Workspace1/DREAM3D_Plugins/Synthetic" -- DREAM3DNX application located in "/Users/mjackson/Workspace1/DREAM3DNX" - -## Directories to Ignore -- `scripts/` - Build/utility scripts -- `conda/` - Conda packaging - -## Coding Standards - -### C++ Style (from .clang-format) -- C++20 standard -- Allman brace style (braces on new lines for classes, control statements, enums, functions, namespaces, structs, before else) -- 200 column limit -- 2-space indentation, no tabs -- Pointer alignment left (`int* ptr` not `int *ptr`) -- No space before parentheses -- Sort includes alphabetically -- No short functions on single line -- Always break template declarations -- Constructor initializers break before comma - -### Naming Conventions (from .clang-tidy) -- C++ header files: `.hpp` extension -- C++ source files: `.cpp` extension -- Namespaces: `lower_case` -- Classes: `CamelCase` -- Structs: `CamelCase` -- Class methods: `camelBack` -- Functions: `camelBack` -- Variables: `camelBack` -- Private members: `m_` prefix + `CamelCase` (e.g., `m_MemberVariable`) -- Global variables: `CamelCase` -- Global constants: `k_` prefix + `CamelCase` (e.g., `k_DefaultValue`) -- Local pointers: `camelBack` + `Ptr` suffix (e.g., `dataPtr`) -- Type aliases: `CamelCase` + `Type` suffix (e.g., `ValueType`) -- Macros: `UPPER_CASE` - -### Descriptive Variable Naming -Use suffixes to make variable types and purposes immediately clear: - -**Geometry variables use `Geom` suffix:** -- Correct: `const auto& imageGeom = dataStructure.getDataRefAs(path);` -- Incorrect: `const auto& image = dataStructure.getDataRefAs(path);` - -**DataStore references use `Ref` suffix:** -- Correct: `const auto& verticesRef = vertexGeom.getVertices()->getDataStoreRef();` -- Incorrect: `const auto& vertices = vertexGeom.getVertices()->getDataStoreRef();` - -Examples: -```cpp -// Geometry variables -auto& imageGeom = dataStructure.getDataRefAs(imagePath); -const auto& rectGridGeom = dataStructure.getDataRefAs(rectPath); -const auto& edgeGeom = dataStructure.getDataRefAs(edgePath); - -// DataStore references -const auto& xBoundsRef = rectGridGeom.getXBounds()->getDataStoreRef(); -const auto& yBoundsRef = rectGridGeom.getYBounds()->getDataStoreRef(); -const auto& verticesRef = edgeGeom.getVertices()->getDataStoreRef(); -``` - -These conventions improve code clarity and distinguish between geometry objects and their underlying data references. - -### File Organization -- When creating a C++ based simplnx filter inside a plugin, the complete filter will have a "NameFilter.hpp" and "NameFilter.cpp" file, an "Algorithm/Name.hpp" and "Algorithm/Name.cpp". -- Filter documentation files are created in Markdown and are in the "docs" subfolder inside the Plugins directory -- Unit tests should be created in the 'test' subfolder and use the 'catch2' unit testing framework. - -## Filter Implementation Guidelines - -### Parameter Validation -- Selection parameters (GeometrySelectionParameter, ArraySelectionParameter, DataGroupSelectionParameter, etc.) automatically validate that the selected object exists in the DataStructure. Do NOT add null checks for these in preflightImpl() or executeImpl(). -- Only add explicit existence checks for objects that are not validated by a selection parameter. - -### DataStructure Access -- Use `getDataRefAs()` to get a reference when you know the object exists (e.g., validated by a selection parameter). -- Use `getDataAs()` to get a pointer only when you need to check if an object exists or when the object may not be present. -- **IMPORTANT**: In unit tests, always wrap `getDataRefAs()` calls with `REQUIRE_NOTHROW()` to provide clear test failure messages if the object doesn't exist. - -Example - Correct: -```cpp -// Parameter already validated this exists, use reference -const auto& imageGeom = dataStructure.getDataRefAs(pInputImageGeometryPathValue); -SizeVec3 dims = imageGeom.getDimensions(); -``` - -Example - Incorrect: -```cpp -// Unnecessary null check - parameter already validated existence -const auto* imageGeomPtr = dataStructure.getDataAs(pInputImageGeometryPathValue); -if(imageGeomPtr == nullptr) -{ - return {MakeErrorResult(-1000, "Could not find geometry")}; -} -``` - -## Thread Safety - -### DataArray and DataStore Classes Are NOT Thread-Safe -- `DataArray`, `DataStore`, and `AbstractDataStore` classes are **NOT thread-safe** for concurrent read or write access. -- The subscript operator (`operator[]`) and other access methods may have internal state or go through virtual function calls that are not safe for concurrent access, even when accessing different indices. -- Some `DataStore` subclasses use out-of-core implementations where data may not be resident in memory. Getting raw pointers to the underlying data is dangerous and should be avoided. - -### Parallelization Guidelines -- When writing parallel algorithms using `ParallelDataAlgorithm`, be aware that passing `DataArray` or `DataStore` references to worker classes can cause random failures on different platforms. -- If parallel access to data arrays is required, consider: - 1. Disabling parallelization with `parallelAlgorithm.setParallelizationEnabled(false)` for correctness - 2. Using thread-local storage for intermediate results - 3. Structuring the algorithm to avoid concurrent access to the same DataArray -- Do NOT assume that writing to different indices of a DataArray from multiple threads is safe. - -Example - Potentially Unsafe: -```cpp -// This pattern can cause random failures even when threads write to different indices -class MyParallelWorker -{ - DataArray& m_OutputArray; // NOT thread-safe for concurrent access - void operator()(const Range& range) const - { - for(usize i = range.min(); i < range.max(); i++) - { - m_OutputArray[i] = computeValue(i); // May fail randomly - } - } -}; -``` - -## Build System -- vcpkg for dependency management -- CMake-based build system - -Example configuring the project -```bash -cd /Users/mjackson/Workspace2/simplnx && cmake --preset simplnx-Rel -``` - -- Build directory is located at "/Users/mjackson/Workspace2/DREAM3D-Build/simplnx-Rel" - -Example building the project -```bash -cd /Users/mjackson/Workspace2/DREAM3D-Build/simplnx-Rel && cmake --build . --target all -``` - -Ensuring all test data files are downloaded -```bash -cd /Users/mjackson/Workspace2/DREAM3D-Build/simplnx-Rel && cmake --build . --target Fetch_Remote_Data_Files -``` - -- Python anaconda environment 'dream3d' can be used if needed - -## Testing -- Unit tests use the Catch2 framework. -- Each `TEST_CASE` should include `UnitTest::CheckArraysInheritTupleDims(dataStructure);` near the end of the test to ensure all created data arrays have correct tuple dimensions inherited from their parent groups. -- Use the `ctest` to run unit tests - -### Running Unit Tests -- Always use `ctest` to run unit tests, NOT the test binary directly -- The `ctest` command handles test data extraction and cleanup automatically -- Use the `-R` flag to run specific tests by name pattern - -Example - Running a specific test: -```bash -cd /Users/mjackson/Workspace2/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel && ctest -R "SimplnxCore::FillBadData" --verbose -``` - -Example - Running all SimplnxCore tests: -```bash -cd /Users/mjackson/Workspace2/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel && ctest -R "SimplnxCore::" --verbose -``` - -### Printing debug statements in unit tests - -Example - Correct - -auto executeResult = filter.execute(dataStructure, args, nullptr, IFilter::MessageHandler{[](const IFilter::Message& message){ fmt::print("{}\n", message.message); }}); - -### Exemplar-Based Testing Pattern -- Many tests use "exemplar" datasets - pre-generated golden reference data stored in `.dream3d` files -- Exemplar datasets are generated by running pipeline files (`.d3dpipeline`) that configure and execute filters - -#### Workflow for Creating and Publishing Test Data: -1. **Generate test data locally**: Create pipeline file with filter configurations and `WriteDREAM3DFilter` to save results -2. **Execute pipeline**: Run the pipeline to generate exemplar `.dream3d` file and any input data files -3. **Package as tar.gz**: Compress test data (no `6_6_` prefix needed - that was only for legacy DREAM3D data) - ```bash - tar -zvcf test_name.tar.gz test_directory/ - ``` -4. **Compute SHA512 hash**: - ```bash - shasum -a 512 test_name.tar.gz - ``` -5. **Upload to GitHub**: Upload to the [DREAM3D data archive release](https://github.com/BlueQuartzSoftware/simplnx/releases/tag/Data_Archive) -6. **Update CMakeLists.txt**: Add `download_test_data()` call in `src/Plugins/[PluginName]/test/CMakeLists.txt`: - ```cmake - download_test_data(DREAM3D_DATA_DIR ${DREAM3D_DATA_DIR} - ARCHIVE_NAME test_name.tar.gz - SHA512 ) - ``` -7. **Test data auto-downloads**: When tests run, the sentinel mechanism automatically downloads and extracts the tar.gz to `unit_test::k_TestFilesDir` - -#### Test Data Archive Naming and Versioning: -- **Base naming**: Use descriptive names that match the test: `test_name.tar.gz` -- **Version suffixes**: When updating existing test data, append version numbers: `test_name_v2.tar.gz`, `test_name_v3.tar.gz` -- **When to version**: - - Original archive already exists in GitHub data archive - - Test requirements changed (new exemplars, different parameters, additional data files) - - Cannot overwrite original because other code may depend on it - - CMakeLists.txt may reference both old and new versions for different tests -- **Check before creating**: Browse the [Data_Archive release](https://github.com/BlueQuartzSoftware/simplnx/releases/tag/Data_Archive) to see if your test data name already exists -- **Legacy prefixes**: The `6_6_` and `6_5_` prefixes are for data from legacy DREAM3D/SIMPL versions - do NOT use for new DREAM3DNX test data - -#### Test Code Pattern: -```cpp -namespace -{ -const std::string k_TestDataDirName = "test_name"; -const fs::path k_TestDataDir = fs::path(unit_test::k_TestFilesDir.view()) / k_TestDataDirName; -const fs::path k_ExemplarFile = k_TestDataDir / "test_name.dream3d"; -const fs::path k_InputImageFile = k_TestDataDir / "input_file.tif"; -} -``` - -**Example**: If `import_image_stack_test.tar.gz` exists in the archive and you need to upload updated test data with new exemplars, create `import_image_stack_test_v2.tar.gz`. Update CMakeLists.txt to reference the new version, and optionally keep the old version if other tests depend on it. - -#### Comparing Test Results Against Exemplars: -- **Load exemplar DataStructure**: Use `UnitTest::LoadDataStructure(exemplarFilePath)` to load the .dream3d file -- **ALWAYS use `REQUIRE_NOTHROW()` before `getDataRefAs()`**: This applies to ALL `getDataRefAs` calls - both generated and exemplar data -- **Get generated data**: Use `getDataRefAs()` wrapped in `REQUIRE_NOTHROW()` since objects were just created by the filter -- **Get exemplar data**: Use `getDataRefAs()` wrapped in `REQUIRE_NOTHROW()` to verify the exemplar exists before accessing -- **Compare geometries**: Use `UnitTest::CompareImageGeometry(&exemplarGeom, &generatedGeom)` - takes two pointers -- **Compare arrays**: Use `UnitTest::CompareDataArrays(exemplarArray, generatedArray)` - type-specific template -- **Switch on data type** when comparing arrays to handle different types (uint8, uint16, uint32, float32, etc.) - -Example pattern: -```cpp -// Load exemplar -DataStructure exemplarDS = UnitTest::LoadDataStructure(k_ExemplarFile); - -// Get geometries - ALWAYS wrap getDataRefAs with REQUIRE_NOTHROW -REQUIRE_NOTHROW(dataStructure.getDataRefAs(generatedGeomPath)); -const auto& generatedGeom = dataStructure.getDataRefAs(generatedGeomPath); -REQUIRE_NOTHROW(exemplarDS.getDataRefAs(DataPath({exemplarGeomName}))); -const auto& exemplarGeom = exemplarDS.getDataRefAs(DataPath({exemplarGeomName})); - -// Compare geometries (dimensions, origin, spacing) - pass pointers -UnitTest::CompareImageGeometry(&exemplarGeom, &generatedGeom); - -// Get arrays - ALWAYS wrap getDataRefAs with REQUIRE_NOTHROW -REQUIRE_NOTHROW(dataStructure.getDataRefAs(generatedDataPath)); -const auto& generatedArray = dataStructure.getDataRefAs(generatedDataPath); -REQUIRE_NOTHROW(exemplarDS.getDataRefAs(exemplarDataPath)); -const auto& exemplarArray = exemplarDS.getDataRefAs(exemplarDataPath); - -// Compare arrays based on type -switch(generatedArray.getDataType()) -{ -case DataType::uint8: - UnitTest::CompareDataArrays(exemplarArray, generatedArray); - break; -case DataType::uint16: - UnitTest::CompareDataArrays(exemplarArray, generatedArray); - break; -// ... etc -} -``` - -**Important**: Use the standardized `UnitTest::` comparison methods directly in test code. - -### Test Organization -- Each test should call `UnitTest::LoadPlugins()` before executing filters -- Use `DYNAMIC_SECTION()` for parameterized tests that generate multiple test cases - -## Pipeline Files -- JSON format with `.d3dpipeline` extension -- Contains array of filter configurations with arguments -- Each filter has: - - `args`: Dictionary of parameter keys and values - - `comments`: Description of what the filter does - - `filter`: Name and UUID - - `isDisabled`: Boolean to skip filter execution -- Common pattern: Multiple filter configurations followed by WriteDREAM3DFilter to save all results to one `.dream3d` file -- Output geometry paths in pipeline must match exemplar names expected by tests - -## Additional Notes - diff --git a/docs/documentation_review_tracker.md b/docs/documentation_review_tracker.md new file mode 100644 index 0000000000..5e965436e3 --- /dev/null +++ b/docs/documentation_review_tracker.md @@ -0,0 +1,1950 @@ +# DREAM3DNX Filter Documentation Review Tracker + +**Design Spec:** [docs/superpowers/specs/2026-04-12-documentation-review-design.md](superpowers/specs/2026-04-12-documentation-review-design.md) +**Style Guide:** [docs/style_palette_final.svg](style_palette_final.svg) +**Branch:** topic/documentation_update (will submit as single PR when complete) + +--- + +## Progress Summary + +| Batch | Category | Total Filters | Triaged | Rewritten | Status | +|-------|----------|---------------|---------|-----------|--------| +| 1 | Orientation / Crystallography Statistics | 17 | 17 | 17 | Complete | +| 2 | Alignment Filters | 5 | 5 | 5 | Complete | +| 3 | Segmentation / Feature Identification | 10 | 10 | 10 | Complete | +| 4 | Neighbor / Kernel Operations | 11 | 11 | 11 | Complete | +| 5 | Geometry Creation / Manipulation | 15 | 15 | 15 | Complete | +| 6 | Data Manipulation (Copy, Create, Delete, Rename) | 21 | 21 | 21 | Complete | +| 7 | I/O Filters (Read/Write) | 44 | 44 | 44 | Complete | +| 8 | Image Processing (ITK wrappers) | 88 | 88 | 88 | Complete | +| 9 | Remaining SimplnxCore filters | 73 | 73 | 73 | Complete | + +--- + +## Batch 1: Orientation / Crystallography Statistics + +**Plugin:** OrientationAnalysis +**Filters:** 17 (15 crystallography + 2 morphological) + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeAvgCAxes | OrientationAnalysis | Done | +| ComputeCAxisLocations | OrientationAnalysis | Done | +| ComputeGBCD | OrientationAnalysis | Done | +| ComputeSchmids | OrientationAnalysis | Done | + +- [x] **ComputeAvgCAxesFilter** (OrientationAnalysis) + - **Clarity:** Assumed deep quaternion/transform knowledge; no explanation of what C-axis is + - **Figures Needed:** Hexagonal unit cell with C-axis labeled + - **Real-World Viz:** IPF color map showing C-axis orientations + - **Concept Links:** C-axis, hexagonal materials, quaternions, reference frames + - **Changes Made:** Added "What is the C-Axis?" section with example materials, plain-language algorithm, hexagonal-only explanation. Added hexagonal unit cell figure. + +- [x] **ComputeCAxisLocationsFilter** (OrientationAnalysis) + - **Clarity:** Very sparse, just restated algorithm + - **Figures Needed:** Same hexagonal C-axis figure (shared with ComputeAvgCAxes) + - **Real-World Viz:** C-axis direction map colored by orientation + - **Concept Links:** C-axis, hexagonal materials, quaternions, reference frames + - **Changes Made:** Added "What is the C-Axis?" section, upper-hemisphere convention note, comparison with ComputeAvgCAxes to help users pick the right filter. Shared hexagonal unit cell figure. + +- [x] **ComputeGBCDFilter** (OrientationAnalysis) + - **Clarity:** 2-sentence stub; non-expert cannot understand what GBCD is + - **Figures Needed:** Conceptual diagram of 5D boundary space (deferred -- complex) + - **Real-World Viz:** GBCD pole figure output screenshot + - **Concept Links:** grain boundaries, misorientation, boundary normals, MRD units + - **Changes Made:** Added "What is the GBCD?" section explaining 5 parameters, MRD units, algorithm steps, resolution parameter. Added Rohrer citations [1][2]. Cross-reference to metric-based filter. + +- [x] **ComputeSchmidsFilter** (OrientationAnalysis) + - **Clarity:** Formula presented but no explanation of slip systems or physical meaning + - **Figures Needed:** Diagram showing tensile axis, slip plane, slip direction, and angles φ/λ + - **Real-World Viz:** Microstructure colored by Schmid factor + - **Concept Links:** slip systems, crystal plasticity, loading axis, CRSS + - **Changes Made:** Added "What is the Schmid Factor?" section with plain-language slip explanation, 0-0.5 range meaning, 4-step algorithm, CRSS limitation note. Added Schmid factor geometric diagram. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeAvgOrientations | OrientationAnalysis | Done | +| ComputeBoundaryStrengths | OrientationAnalysis | Done | +| ComputeFeatureNeighborCAxisMisalignments | OrientationAnalysis | Done | +| ComputeFeatureNeighborMisorientations | OrientationAnalysis | Done | +| ComputeFeatureReferenceCAxisMisorientations | OrientationAnalysis | Done | +| ComputeFeatureReferenceMisorientations | OrientationAnalysis | Done | +| ComputeSlipTransmissionMetrics | OrientationAnalysis | Done | +| ComputeTwinBoundaries | OrientationAnalysis | Done | +| ComputeShapes | OrientationAnalysis | Done | + +- [x] **ComputeAvgOrientationsFilter** (OrientationAnalysis) + - **Clarity:** Comprehensive but very math-heavy; 3 methods with dense statistical notation + - **Figures Needed:** Diagram showing orientations being averaged within a grain; vMF distribution concept + - **Real-World Viz:** IPF color map showing average orientation assignment + - **Concept Links:** quaternions, Fundamental Zone, symmetry operators, Euler angles, EM algorithm + - **Changes Made:** Added introductory paragraph explaining what average orientation means and why it matters for downstream filters. Existing method descriptions were already thorough; kept intact. + +- [x] **ComputeBoundaryStrengthsFilter** (OrientationAnalysis) + - **Clarity:** Relies on citations for metric definitions; readers need access to papers + - **Figures Needed:** Slip transmission across grain boundary concept diagram + - **Real-World Viz:** Feature boundary map colored by boundary strength metrics + - **Concept Links:** slip transmission, Luster-Morris parameter, fracture initiation, grain boundaries + - **Changes Made:** Clarified relationship to ComputeSlipTransmissionMetrics (same metrics, per-Face storage). Added cross-reference for detailed explanations. Explained M' value meaning. + +- [x] **ComputeFeatureNeighborCAxisMisalignmentsFilter** (OrientationAnalysis) + - **Clarity:** Good basic description but "misalignment" vs "misorientation" distinction unclear + - **Figures Needed:** Diagram showing C-axis misalignment angle between two grains + - **Real-World Viz:** Neighbor misalignment values on microstructure + - **Concept Links:** C-axis, misalignment angle, hexagonal crystals, neighbor relationships + - **Changes Made:** Distinguished C-axis misalignment from full misorientation. Explained flexible neighbor list concept. Cross-referenced ComputeAvgCAxes for hexagonal-only explanation. + +- [x] **ComputeFeatureNeighborMisorientationsFilter** (OrientationAnalysis) + - **Clarity:** Straightforward but minimal + - **Figures Needed:** Diagram showing misorientation angle concept between neighboring grains + - **Real-World Viz:** Microstructure with neighbor misorientations displayed + - **Concept Links:** misorientation, orientation angle, grain boundaries + - **Changes Made:** Added plain-language explanation of misorientation. Explained NaN constraint (different crystal structures not comparable). Clarified optional average output. + +- [x] **ComputeFeatureReferenceCAxisMisorientationsFilter** (OrientationAnalysis) + - **Clarity:** Clear what it does but doesn't explain why this metric matters + - **Figures Needed:** Diagram showing cell-to-average C-axis deviation concept + - **Real-World Viz:** Misalignment map within a feature showing spatial variation + - **Concept Links:** C-axis misalignment, hexagonal materials, orientation variation + - **Changes Made:** Reframed around intragranular orientation gradients. Explained what average/std dev outputs tell you (low = uniform, high = internal variation). Cross-referenced ComputeAvgCAxes. + +- [x] **ComputeFeatureReferenceMisorientationsFilter** (OrientationAnalysis) + - **Clarity:** Good. Two reference orientation options clearly explained with use cases + - **Figures Needed:** Legend for existing color scale images would help interpretation + - **Real-World Viz:** Already has 3 images showing IPF colors and two reference orientation results + - **Concept Links:** misorientation, plastic deformation, reference orientation, IPF colors + - **Changes Made:** Added purpose statement about detecting deformation. Rewrote reference orientation options with physical reasoning for when to use each. + +- [x] **ComputeSlipTransmissionMetricsFilter** (OrientationAnalysis) + - **Clarity:** Relies on citations; metrics not explained in the documentation itself + - **Figures Needed:** Slip transmission concept diagram (same as ComputeBoundaryStrengths) + - **Real-World Viz:** Feature pairs with transmission metrics visualized + - **Concept Links:** slip transmission, slip planes/directions, grain boundaries, Luster-Morris + - **Changes Made:** Added introductory explanation of slip transmission concept. Explained M' value meaning (1.0 = perfect alignment). Added cross-reference to ComputeBoundaryStrengths. + +- [x] **ComputeTwinBoundariesFilter** (OrientationAnalysis) + - **Clarity:** Good sigma-3 identification logic but "incoherence" concept needs definition + - **Figures Needed:** Sigma-3 twin relationship diagram; incoherence concept + - **Real-World Viz:** Microstructure with twin boundaries highlighted + - **Concept Links:** twin boundaries, sigma-3, misorientation axis, CSL, incoherence + - **Changes Made:** Added "What is a Twin Boundary?" section explaining Sigma-3 twins and their significance. Explained incoherence in plain terms (0 = perfect coherent twin). + +- [x] **ComputeShapesFilter** (OrientationAnalysis) + - **Clarity:** Good algorithmic steps but missing interpretation guidance + - **Figures Needed:** Best-fit ellipsoid concept; Omega3 sphericity measure + - **Real-World Viz:** Features colored by aspect ratio or Omega3 + - **Concept Links:** principal moments, ellipsoid fitting, eigenvalues, Omega3, aspect ratios + - **Changes Made:** Added "What This Filter Produces" section explaining each output. Defined Omega3 (1.0 = sphere). Cross-referenced triangle geometry version. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeGBCDMetricBased | OrientationAnalysis | Done | +| ComputeGBPDMetricBased | OrientationAnalysis | Done | +| ComputeShapesTriangleGeom | OrientationAnalysis | Done | + +- [x] **ComputeGBCDMetricBasedFilter** (OrientationAnalysis) + - **Clarity:** Excellent technical documentation with clear metric-based vs bin-based distinction + - **Figures Needed:** Maybe one more diagram showing metric distances visually + - **Real-World Viz:** Already has 3 excellent figures (GBCD result, sampling points, error maps) + - **Concept Links:** GBCD, metrics, boundary space, MRD units + - **Changes Made:** Restructured dense metric explanation into numbered two-stage process. Added note about advantages over binning (avoids discretization artifacts). + +- [x] **ComputeGBPDMetricBasedFilter** (OrientationAnalysis) + - **Clarity:** Good. References GBCD Metric-Based filter effectively + - **Figures Needed:** Plane normal vs misorientation sampling differences + - **Real-World Viz:** Already has 1 good figure + - **Concept Links:** GBPD, grain boundary plane distribution, boundary normal + - **Changes Made:** Added opening explaining what GBPD is and how it differs from GBCD (2D plane normals vs full 5D). Added MRD interpretation (1.0 = random, >1.0 = preferred). + +- [x] **ComputeShapesTriangleGeomFilter** (OrientationAnalysis) + - **Clarity:** Very technical but thorough. Excellent caveats section and validation table + - **Figures Needed:** Tetrahedron construction from mesh; watertight vs non-watertight mesh + - **Real-World Viz:** Comparison of voxelized vs triangle geometry shape results + - **Concept Links:** triangle geometry, mesh watertightness, Euler characteristic, winding + - **Changes Made:** Consolidated caveats into "Differences from Image Geometry Version" section. Merged watertight warning and Euler characteristic into "Mesh Quality Requirements" section. Cross-referenced Image Geometry version for output descriptions. + +### Already Complete (Prior to Triage) + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeKernelAvgMisorientations | OrientationAnalysis | Done | + +- [x] **ComputeKernelAvgMisorientationsFilter** (OrientationAnalysis) + - **Changes Made:** Full rewrite with kernel radius explanation, 6 figures (formula, 1D radius 1 & 2, 2D radius (1,1,0) & (1,2,0), quick reference table). Serves as template for rewrite style. + +--- + +## Batch 4: Neighbor / Kernel Operations + +**Plugin:** SimplnxCore + OrientationAnalysis +**Filters:** 11 (cell-level cleanup, morphology, neighbor-list utilities) + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| AddBadData | SimplnxCore | Done | + +- [x] **AddBadDataFilter** (SimplnxCore) + - **Clarity:** Single dense paragraph with one run-on sentence; the filter's purpose (introduce realism into synthetic structures) is buried. + - **Completeness:** No example imagery, no parameter guidance. Mentions "Manhattan distances" with no context. Requires the reader to know about the *Convert Attribute Data Type* filter as a prerequisite. Group is "Synthetic Building (Misc)" which is an outlier vs. the other Batch 4 cleanup filters but is correct given the filter's purpose. + - **Accessibility:** Volume-fraction semantics are easy to misread (the *0.2* applies only to the affected cells, not the whole volume — a subtle but important point). + - **Figures Needed:** Diagram showing the two noise modes (random voxels scattered through volume vs. boundary voxels along feature surfaces). Visual of how a 0.2 volume fraction translates to actual changed-cell counts. + - **Real-World Viz:** Before/after of a synthetic microstructure with random noise applied; same with boundary noise applied. + - **Concept Links:** Manhattan distance, feature boundary cells, synthetic microstructure realism + - **Changes Made:** Added "Why Use This Filter?" section motivating the experimental-realism use case (matched cleanup pipelines for apples-to-apples comparison). Added "Random vs. Boundary Noise" section explaining the two independent modes. Added "Volume Fraction Semantics" section clarifying the per-eligible-cell meaning. Added "What 'Bad' Means in Output" section. Added explicit two-step prerequisite recipe (Compute Euclidean Distance Map → Convert Data Type). Added Required Input Sources. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| FillBadData | SimplnxCore | Done | +| ErodeDilateBadData | SimplnxCore | Done | +| ErodeDilateMask | SimplnxCore | Done | +| ErodeDilateCoordinationNumber | SimplnxCore | Done | +| ReplaceElementAttributesWithNeighborValues | SimplnxCore | Done | +| NeighborOrientationCorrelation | OrientationAnalysis | Done | +| BadDataNeighborOrientationCheck | OrientationAnalysis | Done | + +- [x] **FillBadDataFilter** (SimplnxCore) + - **Changes Made:** Rewrote lead-in to distinguish "small noise (filled)" vs "large defects (preserved)". Restructured implementation-detail Phase 1-4 into a concise "How This Filter Works" 3-step summary. Added "Minimum Defect Size Units" section stating cells/integer voxel count with conversion formula and typical ranges (5-50 for noise, 500-5000 for preserving real pores). Promoted "Store Defects as New Phase" option to its own section. Trimmed performance discussion to a brief note. Added Required Input Sources. + +- [x] **ErodeDilateBadDataFilter** (SimplnxCore) + - **Changes Made:** Removed stray backtick. Restructured into Dilation/Erosion/When-to-Use/Iterations-and-Direction sections. Named the morphological *opening* (erode-then-dilate) and *closing* (dilate-then-erode) patterns explicitly. Stated iterations are in **cell-layers**. Documented the X/Y/Z directional toggle for anisotropic morphology. Added Required Input Sources. + +- [x] **ErodeDilateMaskFilter** (SimplnxCore) + - **Changes Made:** Defined "mask" inline as a boolean cell-level array with cross-link to Multi-Threshold Objects. Added "When to Use" with concrete examples (erode = discard unreliable boundary cells; dilate = recover over-thresholded valid cells). Stated iterations are in **cell-layers**. Documented X/Y/Z directional toggle motivation (anisotropic serial-section resolution). Added Required Input Sources. + +- [x] **ErodeDilateCoordinationNumberFilter** (SimplnxCore) + - **Changes Made:** Stated coordination-number range is **0 to 6** with worked examples (CN=0 inside, CN=6 isolated voxel, CN=4-5 thin protrusion). Cross-linked "isotropic coarsening" definition to RequireMinimumSizeFeatures. Promoted "Loop Until Gone" to its own section with single-pass-vs-full-smoothing guidance. Added "When to Use This Filter" section calling out salt-and-pepper cleanup. Added Required Input Sources. + +- [x] **ReplaceElementAttributesWithNeighborValuesFilter** (SimplnxCore) + - **Changes Made:** Added generic "How This Filter Works" section before EBSD vendor-specific examples. Promoted "Comparison Operator" to its own subsection with use-case guidance for higher-is-better (CI, IQ) vs lower-is-better (MAD, Error) scalars. Added "Loop Until Gone" subsection with caution about flood-fill behavior. Promoted the "too much replacement" warning to its own "Caution: Flood Fill Behavior" section. Reframed EBSD examples as "Example Use Cases". Added Required Input Sources. + +- [x] **NeighborOrientationCorrelationFilter** (OrientationAnalysis) + - **Changes Made:** Added lead-in distinguishing this filter from sister filter ReplaceElementAttributesWithNeighborValues. Restructured algorithm into 4 numbered steps. Promoted *Cleanup Level* to its own subsection with **1-6 range** stated explicitly and worked guidance for each value (6=conservative, 4-5=moderate, 2-3=aggressive, 1=flood-fill). Cross-linked sister filters and EBSD readers. Added Required Input Sources. + +- [x] **BadDataNeighborOrientationCheckFilter** (OrientationAnalysis) + - **Changes Made:** Verified the doc title matches humanName() ("Neighbor Orientation Comparison (Bad Data)"); kept as-is. Added lead-in distinguishing this filter (mask-only update) from NeighborOrientationCorrelation (full-attribute replacement) and recommending sequencing. Promoted *Required Number of Neighbors* to its own section with **1-6 range** stated explicitly. Added cross-references to Multi-Threshold Objects, EBSD readers, and the sister filter. Added Required Input Sources. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| RequireMinNumNeighbors | SimplnxCore | Done | +| ComputeNeighborhoods | SimplnxCore | Done | +| ComputeNeighborListStatistics | SimplnxCore | Done | + +- [x] **RequireMinNumNeighborsFilter** (SimplnxCore) + - **Changes Made:** Rewrote lead with explicit motivation (isolated single-feature islands from segmentation). Cross-linked "isotropic coarsening" to the shared definition in RequireMinimumSizeFeatures. Stated threshold is in **count of contiguous neighbors**. Added inspection-recommendation (look at *Number of Neighbors* output before choosing). Added Required Input Sources. + +- [x] **ComputeNeighborhoodsFilter** (SimplnxCore) + - **Changes Made:** Added lead-in motivating the use case (clustering, second-nearest-neighbor analysis). Defined Equivalent Sphere Diameter inline with cross-link to Compute Feature Sizes. Stated *Multiplier* is **dimensionless**. Added typical-value guidance for the multiplier (1.0 immediate neighbors, 2.0-3.0 second-nearest, 5.0+ broader clustering). Added Required Input Sources. + +- [x] **ComputeNeighborListStatisticsFilter** (SimplnxCore) + - **Changes Made:** Added concrete motivating example (summarizing per-feature neighbor misorientations from ComputeFeatureNeighborMisorientations). Restructured statistics list with inline descriptions. Stated outputs inherit units from input. Added Required Input Sources listing the four common NeighborList producers across both plugins. + +--- + +## Batch 5: Geometry Creation / Manipulation + +**Plugin:** SimplnxCore +**Filters:** 15 (geometry creation, transformation, resampling, cropping/padding, mesh generation, partitioning) + +### Tier 1 — Critical + +None. No filter in this batch has a non-expert blocker. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| CreateGeometry | SimplnxCore | Done | +| ApplyTransformationToGeometry | SimplnxCore | Done | +| RotateSampleRefFrame | SimplnxCore | Done | +| ResampleImageGeom | SimplnxCore | Done | +| ResampleRectGridToImageGeom | SimplnxCore | Done | +| PadImageGeometry | SimplnxCore | Done | +| QuickSurfaceMesh | SimplnxCore | Done | +| InitializeImageGeomCellData | SimplnxCore | Done | + +- [x] **CreateGeometryFilter** (SimplnxCore) + - **Clarity:** Comprehensive but very long (~19KB); the 8-geometry-type taxonomy is buried in dense prose. + - **Completeness:** Excellent — covers all 8 geometry types with examples, including a complete worked example for importing from text files. Possibly too much for a single filter doc. + - **Accessibility:** Heavy DREAM3D-NX terminology assumed (Element, Attribute Matrix, shared vertex list). + - **Figures Needed:** Side-by-side infographic showing all 8 geometry types (Image, Rectilinear Grid, Vertex, Edge, Triangle, Quadrilateral, Tetrahedral, Hexahedral) with their defining elements illustrated. + - **Real-World Viz:** None additional needed; the text import workflow could use a quick diagram. + - **Units Clarity:** Spacing units ("microns per pixel" example) called out — good. + - **Concept Links:** Geometry types, Element type, shared vertex list, winding/right-hand rule, Attribute Matrix + - **Notes:** "DREAM3D Review (Geometry)" group is unusual — verify this is intended. Typo "dimenionality" appears multiple times. Each geometry-type section duplicates content from per-type filters. Consider promoting the geometry-type taxonomy into a shared concept page and trimming this doc to filter-specific guidance. + +- [x] **ApplyTransformationToGeometryFilter** (SimplnxCore) + - **Clarity:** Strong before/after image sequences explaining the successive-rotation artifact problem. Excellent caveat. + - **Completeness:** Has duplicate transformation-type listing (bullets at lines 96-103 and the same content as a table at lines 107-114). One needs to go. + - **Accessibility:** Node vs Image distinction is critical and well-explained; row-major matrix encoding explained. + - **Figures Needed:** Already has many. Could add a diagram explaining the four-element axis-angle representation. + - **Real-World Viz:** Already excellent. + - **Units Clarity:** Rotation angle units (degrees) explicit; translation in geometry's coordinate units; scale dimensionless. + - **Concept Links:** transformation matrix, axis-angle, row-major matrix order, interpolation modes + - **Notes:** Remove the duplicated transformation-type listing. Convert "[Combine Transformation Matrices](CombineTransformationMatricesFilter.md)" link to a proper MyST link (already is). Add Required Input Sources. The relative `./Filter.md` should be checked — current uses both `./` and bare forms. + +- [x] **RotateSampleRefFrameFilter** (SimplnxCore) + - **Clarity:** Verified-only-for-axis-aligned-90/180 warning is at the top — good. Distinction from ApplyTransformation (sample reference frame vs geometric rotation) is not made explicit. + - **Completeness:** Has rotation matrix equivalent shown. Note about origin shift after rotation is valuable. + - **Accessibility:** "Sample reference frame" jargon assumed; the term needs first-use definition. + - **Figures Needed:** Diagram showing sample frame rotation (the axes of the sample relabeled) vs geometric rotation (the data physically rotated). + - **Real-World Viz:** Already has EBSD rotation example. + - **Units Clarity:** Rotation angle in degrees; axis is dimensionless unit vector. + - **Concept Links:** sample reference frame, EBSD frame convention, axis-angle rotation + - **Notes:** Add explicit "When to Use vs ApplyTransformation" guidance. Make verified-axis-only banner more prominent. Cross-link to SetImageGeomOriginScaling for the origin reset workflow. Add Required Input Sources. + +- [x] **ResampleImageGeomFilter** (SimplnxCore) + - **Clarity:** Three resampling modes (Spacing, Scaling, Exact Dimensions) each with worked numerical examples. Clear. + - **Completeness:** "No interpolation, closest cell wins" behavior noted. Renumber Features + NeighborList removal warning present. + - **Accessibility:** Spacing/dimensions/scaling distinction depends on understanding Image Geometry. + - **Figures Needed:** Before/after voxel-grid diagram showing how a 2x spacing reduction halves the cell count. + - **Real-World Viz:** Cubic Small IN100 sliced at different resolutions side-by-side. + - **Units Clarity:** Spacing values are in **physical units** (same as input geometry's spacing); scaling is **percent**; exact dimensions are in **cells**. + - **Concept Links:** spacing vs scaling vs dimensions, closest-cell resampling, Feature renumbering + - **Notes:** Cross-link to ApplyTransformation is present but uses `./` path; convert to plain MyST form. Add explicit units callouts per mode. Add Required Input Sources. + +- [x] **ResampleRectGridToImageGeomFilter** (SimplnxCore) + - **Clarity:** Brief, just describes the "last one wins" rule. + - **Completeness:** Missing: when to use this, how to specify the target image geometry's spacing/dimensions, what happens when target is finer than source. + - **Accessibility:** Rectilinear Grid concept not introduced. + - **Figures Needed:** Side-by-side diagram of variable-spacing RectGrid → regular Image Geom with the "last one wins" cells highlighted. + - **Real-World Viz:** A real RectGrid resampled to a uniform Image Geom. + - **Units Clarity:** Target spacing in physical units. + - **Concept Links:** Rectilinear Grid vs Image Geometry, downsampling vs upsampling + - **Notes:** Add "When to Use" section. Explain why "last one wins" was chosen (interpolation is wrong for label data). Add Required Input Sources. + +- [x] **PadImageGeometryFilter** (SimplnxCore) + - **Clarity:** Very brief; the figures are helpful but the prose underdocuments the "default padding value" semantics. + - **Completeness:** Doesn't explain what the *Update Origin* option does or when to use it. + - **Accessibility:** "Default padding value" is undefined. + - **Figures Needed:** Already has before/after. Could add a 3-panel diagram showing Update Origin ON vs OFF. + - **Real-World Viz:** Before/after with both Update Origin settings. + - **Units Clarity:** Pad amounts are in **cells/voxels**. Default value is in whatever units the target array uses. + - **Concept Links:** padding, image extension, origin shift + - **Notes:** Expand "default padding value" to "Each padded cell is initialized to the user-specified Default Value, which is interpreted in the same units as each cell-level array being padded". Document *Update Origin* and *Update Spacing* options. Add Required Input Sources. + +- [x] **QuickSurfaceMeshFilter** (SimplnxCore) + - **Clarity:** Deprecation notice at top recommending "Surface Nets". Node Types table is excellent. Triangle-pair-per-cell-face algorithm explained. + - **Completeness:** Has good images for each Node Type. The Verify Triangle Winding reference is implicit; needs a link. + - **Accessibility:** "Stair stepped" surface mesh result not pictured directly. + - **Figures Needed:** Already has plenty. Could use a small diagram of how a single voxel face becomes 2 triangles. + - **Real-World Viz:** Already present. + - **Concept Links:** voxel-face-to-triangle conversion, Node Types, FaceLabels convention, mesh windings + - **Notes:** Improve deprecation banner — make clear when to use this vs Surface Nets. Convert "see Verify Triangle Winding documentation" to a MyST link. Add Required Input Sources (FeatureIds from a segment filter). + +- [x] **InitializeImageGeomCellDataFilter** (SimplnxCore) + - **Clarity:** Three modes (Manual, Random, Random With Range) are listed but the "subvolume" parameter is undefined. + - **Completeness:** Missing: how is the subvolume specified (min/max cell indices? physical bounds?). What data types support each random mode? What about boolean arrays? + - **Accessibility:** Reader has to guess the subvolume specification UI. + - **Figures Needed:** Diagram showing a subvolume highlighted within a larger volume; before/after. + - **Real-World Viz:** Before/after on a real cube showing the initialized subvolume. + - **Units Clarity:** Subvolume bounds in **cells/voxels** vs **physical units** — must be stated. + - **Concept Links:** subvolume, cell-level initialization, random number generation seed + - **Notes:** Document the subvolume specification mode and units. Note random-mode behavior for boolean, integer, and float types separately. Document the random seed parameter. Add Required Input Sources. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| CreateImageGeometry | SimplnxCore | Done | +| CombineTransformationMatrices | SimplnxCore | Done | +| SetImageGeomOriginScaling | SimplnxCore | Done | +| CropImageGeometry | SimplnxCore | Done | +| AppendImageGeometry | SimplnxCore | Done | +| PartitionGeometry | SimplnxCore | Done | +| ComputeCoordinatesImageGeom | SimplnxCore | Done | + +- [x] **CreateImageGeometryFilter** (SimplnxCore) + - **Clarity:** Deprecation banner is right under the title but as a level-2 heading, making it look like its own section. Confusing. + - **Completeness:** Dimensions/Spacing/Origin definitions are good. + - **Accessibility:** Same dense terminology as CreateGeometry. + - **Figures Needed:** Dimensions/origin/spacing diagram (would also serve SetImageGeomOriginScaling and ResampleImageGeom). + - **Real-World Viz:** N/A — filter creates rather than transforms data. + - **Units Clarity:** Already states spacing example "microns per pixel". + - **Concept Links:** Image Geometry dimensions/origin/spacing + - **Notes:** Move deprecation notice into a clear callout. Fix "dimenionality" typo. Cross-link to CreateGeometry filter. Add Required Input Sources note (none — geometry is created from user parameters). + +- [x] **CombineTransformationMatricesFilter** (SimplnxCore) + - **Clarity:** Brief and adequate. Output format documented. + - **Completeness:** Missing motivating context for why you'd combine matrices (the answer is in ApplyTransformation — referenced indirectly there). + - **Accessibility:** Assumes user knows row-major 4x4 convention. + - **Figures Needed:** Optional — a diagram showing two 4x4 matrices multiplying into a single 4x4 result. + - **Real-World Viz:** N/A. + - **Units Clarity:** N/A (matrix is dimensionless apart from translation components). + - **Concept Links:** matrix composition, transformation order, row-major matrix order + - **Notes:** Add a short "Why Use This Filter" pointing to ApplyTransformationToGeometry's caveat about successive image-geometry transformations. Note that matrices are applied left-to-right in the order listed. Add Required Input Sources. + +- [x] **SetImageGeomOriginScalingFilter** (SimplnxCore) + - **Clarity:** Title says "Set Origin & Spacing" but body only describes the origin parameters. Spacing is implicit. + - **Completeness:** "Put Input Origin at the Center of Geometry" option mentioned but not explained in detail. + - **Accessibility:** OK for the limited content provided. + - **Figures Needed:** Diagram showing origin-at-corner vs origin-at-center. + - **Real-World Viz:** N/A. + - **Units Clarity:** Origin coordinates and spacing are in physical units. + - **Concept Links:** Image Geometry origin, spacing + - **Notes:** Document both Origin and Spacing parameter sets. Document the linkable parameters (only-change-origin, only-change-spacing options). Expand the "Put Origin at Center" explanation. Add Required Input Sources. + +- [x] **CropImageGeometryFilter** (SimplnxCore) + - **Clarity:** Three worked examples with images. Inclusive-bounds note is critical and called out. + - **Completeness:** Voxels-vs-physical-coordinates mode is implicit; the "Use Physical Bounds" parameter should be stated explicitly. + - **Accessibility:** Voxel index 0-based convention is implied via examples. + - **Figures Needed:** Already adequate. + - **Real-World Viz:** Already present. + - **Units Clarity:** Bounds are in **cells (0-based, inclusive)** OR **physical units (depending on parameter)** — explicit per-mode. + - **Concept Links:** ROI cropping, inclusive bounds, voxel indexing + - **Notes:** Add explicit "Bounds Mode" subsection naming the parameter that toggles voxels vs physical. State units per mode. Update NeighborList warning to use the standard pattern shared with RequireMinimumSizeFeatures. + +- [x] **AppendImageGeometryFilter** (SimplnxCore) + - **Clarity:** Exhaustive examples for X/Y/Z directions with figures. + - **Completeness:** "Resolution" terminology used in one place — should be "Spacing" per the modern simplnx convention. + - **Accessibility:** Good. + - **Figures Needed:** Already comprehensive. + - **Real-World Viz:** Already present. + - **Units Clarity:** Append happens in cell-count units along the chosen direction; the *Check Spacing* option checks physical-unit match. + - **Concept Links:** geometry concatenation, mirroring, spacing check + - **Notes:** Replace remaining "Resolution" with "Spacing" for consistency. Cross-link to CreateImageGeometry for the geometry-definition concepts. Add Required Input Sources. + +- [x] **PartitionGeometryFilter** (SimplnxCore) + - **Clarity:** Four modes with excellent visual examples and walk-throughs. + - **Completeness:** "Reconstruction (Reconstruction)" group/subgroup is a stutter — verify. + - **Accessibility:** Long doc but well-organized with figures. + - **Figures Needed:** Already excellent. + - **Real-World Viz:** Already present. + - **Units Clarity:** Cell Length is in physical units; Number of Cells Per Axis is in **integer cell counts**; Origin in physical units; Min/Max in physical units. + - **Concept Links:** spatial partitioning, partition grid, out-of-bounds handling, vertex mask + - **Notes:** Verify group "Reconstruction (Reconstruction)". Add a short lead-in explaining why partition (spatial analysis, sub-volume statistics, parallel processing prep). Add Required Input Sources. + +- [x] **ComputeCoordinatesImageGeomFilter** (SimplnxCore) + - **Clarity:** "Implicit vs explicit" framing is jargon; the example output is clear. + - **Completeness:** Three output modes documented with raster scheme. + - **Accessibility:** Reader benefits from concrete example, which is provided. + - **Figures Needed:** Optional — a small voxel-grid diagram with one cell highlighted showing its (i,j,k) index and (x,y,z) physical position. + - **Real-World Viz:** N/A — output is numerical. + - **Units Clarity:** Physical coordinates in geometry's physical units; indices are **integer cell indices (0-based)**. + - **Concept Links:** cell indexing scheme, physical coordinates, ijk vs xyz, raster order + - **Notes:** Rewrite "implicit/explicit" framing in plain language ("makes the per-cell coordinates available as a regular cell-level array"). Add a "When to Use" — typically for CSV/text export workflows. Add Required Input Sources (Image Geometry). + +--- + +## Batch 6: Data Manipulation + +**Plugin:** SimplnxCore +**Filters:** 21 (create / copy / delete / rename / move / combine / split / convert / initialize / calculate) + +### Tier 1 — Critical + +None. No filter in this batch is incomprehensible to a non-expert. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| CreateAttributeMatrix | SimplnxCore | Done | +| CreateDataGroup | SimplnxCore | Done | +| DeleteData | SimplnxCore | Done | +| RenameDataObject | SimplnxCore | Done | +| MoveData | SimplnxCore | Done | +| CopyFeatureArrayToElementArray | SimplnxCore | Done | +| CreateFeatureArrayFromElementArray | SimplnxCore | Done | +| ConditionalSetValue | SimplnxCore | Done | +| ConvertColorToGrayScale | SimplnxCore | Done | +| ReshapeDataArray | SimplnxCore | Done | + +- [ ] **CreateAttributeMatrixFilter** (SimplnxCore) + - **Clarity:** Extremely brief (only ~20 lines). Lone example does not explain what an Attribute Matrix conceptually represents. + - **Completeness:** Missing the *why* (tuple-dimensions discipline for arrays in the same matrix), the *when* (typical use cases — creating a Feature Attribute Matrix, an Ensemble Attribute Matrix), and the relationship to DataGroup. + - **Accessibility:** Assumes the user already knows what an Attribute Matrix is. + - **Figures Needed:** Optional — a hierarchy diagram showing Image Geometry → Cell Attribute Matrix → arrays would also serve CreateGeometry/CreateDataGroup. + - **Concept Links:** Attribute Matrix, tuple dimensions, DataGroup vs Attribute Matrix + - **Notes:** Add "What is an Attribute Matrix?" subsection. Cross-link to CreateDataGroup with explicit when-to-use-which guidance. Note tuple-dimension consistency requirement. + +- [ ] **CreateDataGroupFilter** (SimplnxCore) + - **Clarity:** Only 1 paragraph; says "unlike AttributeMatrix, DataGroups are capable of holding any DataObject of any size" but doesn't explain when to choose one over the other. + - **Completeness:** Missing typical use case (organizing related arrays of different sizes, creating an output structure for a future filter). + - **Concept Links:** DataGroup, AttributeMatrix + - **Notes:** Expand. Cross-reference CreateAttributeMatrix and explain the choice: DataGroup for heterogeneous content, Attribute Matrix when all child arrays must share tuple dimensions. + +- [ ] **DeleteDataFilter** (SimplnxCore) + - **Clarity:** Two use cases (memory and name collisions) clearly explained. + - **Completeness:** Missing: cascade behavior (does deleting a Geometry also delete its Attribute Matrices? Does deleting an Attribute Matrix delete its child arrays?), what happens to downstream filters that reference the deleted object. + - **Concept Links:** cascade delete, object lifetimes + - **Notes:** Document the cascade behavior. Add explicit warning: subsequent filters that selected the deleted object will fail preflight. + +- [ ] **RenameDataObjectFilter** (SimplnxCore) + - **Clarity:** Single sentence. + - **Completeness:** Missing: what happens to filter parameters downstream that reference the old name (they won't auto-update — preflight will fail). What name collisions are allowed/disallowed. + - **Notes:** Expand to one paragraph. Warn about downstream filter parameter references not updating automatically. + +- [ ] **MoveDataFilter** (SimplnxCore) + - **Clarity:** Brief but covers the tuple-count requirement. + - **Completeness:** Missing: examples (moving a computed array into a Feature Attribute Matrix; moving an array between DataGroups). What happens to arrays that are children of the moved object. + - **Concept Links:** parent-child hierarchy, tuple validation + - **Notes:** Add concrete examples. Explain that tuple-dimension *shape* doesn't need to match — only the *number of tuples*. + +- [ ] **CopyFeatureArrayToElementArrayFilter** (SimplnxCore) + - **Clarity:** "Xmdf visualization files write only the Element attributes" is jargon and almost the entire rationale. + - **Completeness:** Missing: general "when to use" (broadcasting a per-Feature scalar to every cell of that feature for visualization), parameter description. + - **Notes:** Lead with the general purpose (broadcast Feature-level value back to all cells of the Feature). Explain the Xmdf-export reason as one specific use case rather than the only one. Add Required Input Sources. + +- [ ] **CreateFeatureArrayFromElementArrayFilter** (SimplnxCore) + - **Clarity:** "the value of the *last element copied*" is buried as the central footgun. + - **Completeness:** Missing: warning that this filter is destructive when used on per-cell scalars that vary within a feature (since most cells get discarded). When to use vs. ComputeArrayStatistics (which computes per-feature means). + - **Notes:** Promote the "last element copied" caveat to a Warning section. Cross-reference ComputeArrayStatistics for averaging behavior. Add Required Input Sources. + +- [ ] **ConditionalSetValueFilter** (SimplnxCore) + - **Clarity:** Two modes (conditional mask vs value-replacement) buried in one dense sentence. + - **Completeness:** Mode parameter (*Use Conditional Mask*) is the central control but not promoted. + - **Notes:** Split the two modes into their own subsections. Document *Use Conditional Mask* explicitly. Add Required Input Sources. + +- [ ] **ConvertColorToGrayScaleFilter** (SimplnxCore) + - **Clarity:** Four conversion algorithms documented with formulas. + - **Completeness:** Missing: when to use (preprocessing color images for downstream grayscale-only filters), expected input format (uint8 RGB/RGBA), output type. + - **Notes:** Add "When to Use" lead-in. State input/output array types and component shapes. Add Required Input Sources (ITK image reader). + +- [ ] **ReshapeDataArrayFilter** (SimplnxCore) + - **Clarity:** Critical footgun warning ("DOES NOT MOVE ANY VALUES IN MEMORY") is buried at line 11. + - **Completeness:** Stride-mismatch example is good but the warning needs more prominence given that misuse silently produces wrong results. + - **Concept Links:** strides, row-major / C-order storage, tuple dimensions + - **Notes:** Promote the "no memory rearrangement" warning into a top-level Warning section. Add a "When NOT to Use" callout. Add Required Input Sources. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| CreateDataArray | SimplnxCore | Done | +| CreateDataArrayAdvanced | SimplnxCore | Done | +| CopyDataObject | SimplnxCore | Done | +| CombineAttributeArrays | SimplnxCore | Done | +| ConcatenateDataArrays | SimplnxCore | Done | +| SplitDataArrayByComponent | SimplnxCore | Done | +| SplitDataArrayByTuple | SimplnxCore | Done | +| ExtractComponentAsArray | SimplnxCore | Done | +| ConvertData | SimplnxCore | Done | +| ArrayCalculator | SimplnxCore | Done | +| InitializeData | SimplnxCore | Done | + +- [ ] **CreateDataArrayFilter** (SimplnxCore) + - **Notes:** Already has good data-type ranges table and semicolon-notation example. Minor polish: state that Number of Components must be ≥ 1; explicitly note that this filter creates a *single component dimension* (use CreateDataArrayAdvanced for multi-dimension components). Add Required Input Sources (none). + +- [ ] **CreateDataArrayAdvancedFilter** (SimplnxCore) + - **Notes:** Documents 4 initialization modes (Fill, Incremental, Random, Random With Range) and Step Operation. Mostly good. Polish: state component-dimension product must be ≥ 1; clarify that multi-dimensional components (e.g., 3x3 tensor) are supported here. Cross-link CreateDataArray as the simpler version. + +- [ ] **CopyDataObjectFilter** (SimplnxCore) + - **Notes:** Clear; "deep copy" semantics for BaseGroup containers documented. Polish: cross-link Copy to New Parent option more explicitly; add Required Input Sources (none). + +- [ ] **CombineAttributeArraysFilter** (SimplnxCore) + - **Notes:** Already has worked examples and figures. Polish: cross-link "Concatenate Data Arrays" already present; mention the use case of building a Vertex coordinates array from three separate x/y/z arrays. Add Required Input Sources. + +- [ ] **ConcatenateDataArraysFilter** (SimplnxCore) + - **Notes:** Brief but clear. Cross-link to Combine Attribute Arrays is present. Polish: state that the result is always 1-D (already does); add example. + +- [ ] **SplitDataArrayByComponentFilter** (SimplnxCore) + - **Notes:** Clear worked example. Polish: minor copy-edit ("unput" → "input"); state the "specifying a subset of components" mode more cleanly; cross-link Combine Attribute Arrays as the inverse operation (already does). + +- [ ] **SplitDataArrayByTupleFilter** (SimplnxCore) + - **Notes:** Clear worked example. Polish: cross-link Split Data Array (By Component) present. Polish: state units on tuple counts (integer counts). + +- [ ] **ExtractComponentAsArrayFilter** (SimplnxCore) + - **Notes:** Title in cpp is "Extract/Remove Components" — verify match. Brief but covers the 3 operation modes. Polish: add a worked example showing the 3 modes; add Required Input Sources. + +- [ ] **ConvertDataFilter** (SimplnxCore) + - **Notes:** Already very thorough with up/down casting and signed/unsigned warnings. Polish: cross-link to Reshape Data Array for the related-but-different "interpret data differently" use case. Add Required Input Sources. + +- [ ] **ArrayCalculatorFilter** (SimplnxCore) + - **Notes:** Already extremely thorough — operator tables, multi-component handling, explicit array name escaping, multiple worked examples. Polish: minor only. Cross-link to Convert Angles to Degrees or Radians (already mentioned). Add Required Input Sources. + +- [ ] **InitializeDataFilter** (SimplnxCore) + - **Notes:** Content is good but the prose is rambly. Polish: restructure each initialization mode into its own subsection with a brief intro and bullet list of nuances rather than nested bullet trees. Move boolean entry rules to a single dedicated subsection. + +--- + +## Batches 8-9: Not Yet Triaged + +The following batches have been identified in the design spec but have not yet been triaged. Each batch will be triaged at the start of its work cycle. (Batch 7 was triaged 2026-06-10; see the Batch 7 section below.) + +## Batch 2: Alignment Filters + +**Plugin:** OrientationAnalysis + SimplnxCore +**Filters:** 5 + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| AlignSectionsMutualInformation | OrientationAnalysis | Done | +| AlignSectionsMisorientation | OrientationAnalysis | Done | +| AlignSectionsList | SimplnxCore | Done | + +- [x] **AlignSectionsMutualInformationFilter** (OrientationAnalysis) + - **Clarity:** Functional but domain-heavy; mutual information concept not explained for non-experts + - **Figures Needed:** Diagram showing 7x7 grid search with high/low MI regions + - **Real-World Viz:** Pipeline screenshot showing input/output shift arrays + - **Concept Links:** mutual information, feature segmentation, 7x7 grid search, local minima + - **Changes Made:** Added "What is Mutual Information?" section. Added "When to Use This Method" guidance. Restructured algorithm into clear numbered steps with named subsections. Explained misorientation tolerance parameter. Cross-referenced other alignment methods. + +- [x] **AlignSectionsMisorientationFilter** (OrientationAnalysis) + - **Clarity:** Clear algorithm steps but non-experts need misorientation definition; background subtraction underdocumented + - **Figures Needed:** Diagram of 7x7 grid search with before/after alignment; background subtraction concept + - **Real-World Viz:** Example output shifts for a real dataset + - **Concept Links:** misorientation angle, cell-to-cell pairing, 7x7 grid search, local minima, background shift removal + - **Changes Made:** Added "When to Use This Method" guidance with cross-references to alternatives. Restructured algorithm with clear step descriptions. Separated local minima warning, masking, and linear background subtraction into named subsections. + +- [x] **AlignSectionsListFilter** (SimplnxCore) + - **Clarity:** Core concept clear but overwhelmed by backwards compatibility cruft and file format specs + - **Figures Needed:** Flowchart showing relative vs cumulative shift interpretation + - **Real-World Viz:** Typical usage showing output from another alignment filter feeding into this one + - **Concept Links:** relative shifts, cumulative shifts, slice ordering, CSV import + - **Changes Made:** Rewrote lead paragraph to explain the three use cases. Clarified relative vs cumulative with concise definitions. Consolidated file import instructions into a single streamlined section. Moved legacy format details into a brief "Note on Legacy Files" section. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| AlignSectionsFeatureCentroid | SimplnxCore | Done | + +- [x] **AlignSectionsFeatureCentroidFilter** (SimplnxCore) + - **Clarity:** Clear and accessible; centroid-based alignment is straightforward + - **Figures Needed:** Diagram showing centroid calculation on adjacent slices before/after alignment + - **Real-World Viz:** Before/after visualization of aligned sections + - **Concept Links:** centroid, cell resolution, reference slice, background shift removal + - **Changes Made:** Restructured into clear subsections (When to Use, How It Works, Reference Slice, Linear Background Subtraction). Added comparison note about local minima advantage over other methods. + +### Tier 4 — Adequate + +| Filter | Plugin | Status | +|--------|--------|--------| +| AlignGeometries | SimplnxCore | No Changes Needed | + +- [x] **AlignGeometriesFilter** (SimplnxCore) + - **Notes:** 32 lines. Two simple alignment methods (Origin and Centroid) clearly explained. No domain jargon. Adequate as-is. + +--- + +## Batch 3: Segmentation / Feature Identification + +**Plugin:** SimplnxCore + OrientationAnalysis +**Filters:** 10 (3 core segmentation + 7 feature identification/post-processing) + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| MergeTwins | OrientationAnalysis | Done | + +- [x] **MergeTwinsFilter** (OrientationAnalysis) + - **Clarity:** Very sparse (~27 lines). Cubic-High restriction stated in caps but no context on why twins are merged; Sigma-3 and `<111>` axis terminology used with no definitions. + - **Completeness:** Only one paragraph of description; no output array description; no guidance on typical tolerance values; no before/after imagery. + - **Accessibility:** Assumes reader knows what a twin is, what Sigma-3 notation means, and how to interpret `<111>` direction notation. + - **Figures Needed:** Sigma-3 twin relationship diagram; visual explanation of axis tolerance vs. angle tolerance. + - **Real-World Viz:** Before/after microstructure showing twin variants merged into the parent grain. + - **Concept Links:** twin boundaries, Sigma-3, FCC, `<111>` axis, misorientation + - **Changes Made:** Added "What is a Twin?" section explaining Sigma-3, FCC annealing twins, and CSL notation. Added "Why Merge Twins?" section giving the downstream-analysis motivation (grain counting, size distributions, neighbor stats). Restructured algorithm into numbered steps on the Feature level. Added "Parameter Guidance" with explicit degree units and typical tolerance ranges. Added "Required Input Sources" section listing each upstream filter that must run first. Added "Limitations" clarifying Cubic-High/m3m restriction, FCC-only practical applicability, and Sigma-3-only detection. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| ScalarSegmentFeatures | SimplnxCore | Done | +| CAxisSegmentFeatures | OrientationAnalysis | Done | +| EBSDSegmentFeatures | OrientationAnalysis | Done | +| RequireMinimumSizeFeatures | SimplnxCore | Done | +| ComputeFeatureNeighbors | SimplnxCore | Done | + +- [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 + - **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. + +- [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 + - **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. + +- [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 + - **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. + +- [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 + - **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. + +- [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 + - **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 + +| Filter | Plugin | Status | +|--------|--------|--------| +| IdentifySample | SimplnxCore | Done | +| ComputeSurfaceFeatures | SimplnxCore | Done | +| ComputeBiasedFeatures | SimplnxCore | Done | +| RemoveFlaggedFeatures | SimplnxCore | Done | + +- [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 + - **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(). + +- [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 + - **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. + +- [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 + - **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. + +- [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 + - **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). + +--- + +## Batch 7: I/O Filters (Read/Write) + +**Plugin:** SimplnxCore + OrientationAnalysis +**Filters:** 44 (24 readers + 20 writers) + +> **Scope note:** The design spec estimated ~15 I/O filters. The actual count is **44** once the full set of EBSD/HDF5 readers (Ang, Ctf, Channel5, H5Ebsd, H5Esprit, H5Oim, H5Oina, EnsembleInfo, GrainMapper3D) and the format-specific exporters (Abaqus, LAMMPS, SPParks, LosAlamos FFT, VTK, Avizo, INL, GBCD, StatsGen ODF, etc.) are included. Rewrites will be committed at each tier boundary, and the large Tier 2 group may be split into sub-commits by sub-theme (core data I/O, image/volume readers, simulation exporters, VTK/Avizo, EBSD readers, OrientationAnalysis writers). + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| ReadH5OinaData | OrientationAnalysis | Done | +| WriteGBCDGMTFile | OrientationAnalysis | Done | + +- [x] **ReadH5OinaDataFilter** (OrientationAnalysis) + - **Clarity:** Reads a single Oxford Aztec `.h5oina` file; vendor clearly identified. FORMAT VERSION 2.0 limitation and the Read HDF5 Dataset workaround are useful. + - **Completeness:** STRUCTURAL DEFECT (fixed) — the doc had hand-written `## Parameters` and `## Created Objects` tables and was missing the auto-table marker entirely. + - **Accessibility:** Same undefined EBSD jargon (Euler angles, crystal structures, reference frames) as the other EBSD readers. + - **Figures Needed:** Has Figure 1 (Hexagonal alignment) + a UI overview; a sample/crystal reference-frame diagram would help. + - **Real-World Viz:** IPF map of imported Aztec data. + - **Units Clarity:** `.h5oina` angles stated as radians (good); Z Spacing units (microns) now live in the parameter help text (the auto-table). + - **Concept Links:** Euler angles (Bunge Z-X-Z), crystal structures/Ensemble, lattice constants, sample/crystal reference frame, hexagonal symmetry, H5OINA v2.0 format + - **Changes Made:** DELETED the hand-written `## Parameters` and `## Created Objects` tables and INSERTED the `% Auto generated parameter table` marker (so the real parameter table now injects). Added a "What This Filter Produces" prose paragraph explaining the imported EBSD data in plain language (orientation as Euler angles, per-pixel phase, pattern-quality metrics, per-phase Ensemble data) instead of a stale type table. Fixed the phi2 +30° bullet that wrongly referenced "(.ctf) files" → "`.h5oina` files". Reworded the historical reference-frame note from ".ctf file" to "Oxford data". Converted the two `{ref}` rotation links and the bold-only "Threshold Objects" to MyST links; fixed the Read HDF5 Dataset link to the cross-plugin `../SimplnxCore/` form. Added a "Downstream Processing" note cross-linking Convert Orientation Representation. Fixed typo "agment" → "augment". Normalized footer to "## DREAM3D-NX Help". + +- [x] **WriteGBCDGMTFileFilter** (OrientationAnalysis) + - **Clarity:** Was one sentence; never explained what a GBCD pole figure is, what the `.dat` contains, or why an engineer would want one. + - **Completeness:** No parameter explanation beyond "phase index"; the Misorientation Axis-Angle parameter was undocumented. No Required Input Sources. + - **Accessibility:** "GBCD", "GMT", "pole figure", "phase index" all undefined. GMT URL (`gmt.soest.hawaii.edu`) was stale. + - **Figures Needed:** Data-flow diagram: GBCD data (from Compute GBCD) → this filter → `.dat` → GMT → rendered pole figure (shows the external toolchain). + - **Real-World Viz:** Already has a rendered GMT pole figure image (caption now explains MRD contours). + - **Units Clarity:** Phase index now stated as 1-based dimensionless index; misorientation angle stated in degrees, axis (h,k,l) dimensionless. + - **Concept Links:** GBCD, GMT, pole figure, stereographic projection, Ensemble/phase data, MRD + - **Changes Made:** Major rewrite. Added "What is a GBCD Pole Figure?" defining grain boundary, GBCD, misorientation, pole figure, and MRD in plain language. Added "What This Filter Does" making explicit that GMT is an external toolkit and this filter only writes its input `.dat` file (with the Compute GBCD → this filter → GMT toolchain spelled out). Added "Parameter Guidance" documenting Phase of Interest (1-based index), the previously-undocumented Misorientation Axis-Angle (angle in degrees + crystal axis h,k,l, with the Σ3 example), and Output GMT File. Added a Required Input Sources section naming [Compute GBCD](ComputeGBCDFilter.md) (GBCD) and the EBSD readers (Crystal Structures). Fixed the GMT URL to generic-mapping-tools.org. Improved the figure caption to explain the MRD contours. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| ReadHDF5Dataset | SimplnxCore | Done | +| WriteBinaryData | SimplnxCore | Done | +| ReadStlFile | SimplnxCore | Done | +| ReadVtkStructuredPoints | SimplnxCore | Done | +| ReadVolumeGraphicsFile | SimplnxCore | Done | +| WriteAbaqusHexahedron | SimplnxCore | Done | +| WriteLAMMPSFile | SimplnxCore | Done | +| WriteSPParksSites | SimplnxCore | Done | +| WriteLosAlamosFFT | SimplnxCore | Done | +| ReadDeformKeyFileV12 | SimplnxCore | Done | +| WriteVtkRectilinearGrid | SimplnxCore | Done | +| WriteVtkStructuredPoints | SimplnxCore | Done | +| WriteAvizoRectilinearCoordinate | SimplnxCore | Done | +| WriteAvizoUniformCoordinate | SimplnxCore | Done | +| ReadDREAM3D | SimplnxCore | Done | +| ReadEnsembleInfo | OrientationAnalysis | Done | +| ReadAngData | OrientationAnalysis | Done | +| ReadCtfData | OrientationAnalysis | Done | +| ReadChannel5Data | OrientationAnalysis | Done | +| ReadH5Ebsd | OrientationAnalysis | Done | +| ReadH5EspritData | OrientationAnalysis | Done | +| ReadH5OimData | OrientationAnalysis | Done | +| WriteGBCDTriangleData | OrientationAnalysis | Done | +| WritePoleFigure | OrientationAnalysis | Done | + +- [x] **ReadHDF5DatasetFilter** (SimplnxCore) + - **Clarity:** Element-count matching rule is explained, but the worked examples confuse more than clarify (Example 1 is an error case; Example 2's arithmetic is internally inconsistent). + - **Completeness:** Missing description of key parameters (which dataset(s) to select, the file path, multi-dataset import in one pass). Only the dimension math is covered. + - **Accessibility:** Assumes the reader knows HDF5 dataset vs group; "component/tuple dimensions", "attribute matrix" undefined. + - **Figures Needed:** Diagram of a flat HDF5 dataset (N elements) reshaped into tuples × components. + - **Real-World Viz:** Screenshot of the HDF5 tree dataset-selection UI. + - **Units Clarity:** N/A (element counts, dimensionless). + - **Concept Links:** HDF5 dataset/group, component dimensions, tuple dimensions, attribute matrix, total element count + - **Changes Made:** Added a one-line definition of HDF5 and first-use definitions of tuple vs component dimensions. Described the dataset-selection behavior and the optional Attribute-Matrix parent placement in prose. Replaced the three inconsistent worked examples (including the '4-dims-labeled-3D' / mismatched-arithmetic case) with three internally consistent ones built on the rule total-element-count = tuples x components. Added Required Input Sources (None -- external .h5/.hdf5 file) and a License & Copyright section. + +- [x] **WriteBinaryDataFilter** (SimplnxCore) + - **Clarity:** Thin — one sentence plus an Endianess section. Does not state output file naming, extension, multi-component behavior, or that no header is written. + - **Completeness:** Only Endianess documented. Missing output directory/naming, raw-no-header behavior, on-disk component ordering, file extension parameter. + - **Accessibility:** The Endianess section itself is clear; the problem is omission. + - **Figures Needed:** None. + - **Real-World Viz:** Optional screenshot of the output files (low priority). + - **Units Clarity:** N/A. + - **Concept Links:** endianness, raw binary (no header), component ordering, output file naming + - **Changes Made:** Expanded the thin description to the actual behavior (one raw file per **Data Array**, `` naming with default `.bin`, interleaved components, no header written). Added the explicit warning that the user must record type/dims/endianness, and a cross-link to read the files back with [Read Raw Binary](ReadRawBinaryFilter.md). Italicized the endianness values; fixed the run-on/period grammar. + +- [x] **ReadStlFileFilter** (SimplnxCore) + - **Clarity:** Dives straight into binary layout/attribute-byte-count without first stating in plain terms that STL is a triangle surface mesh and the output is a Triangle Geometry. + - **Completeness:** Covers binary format, vendor detection, strictness, a Python fix script. Never states ASCII STL is unsupported; no mention of produced arrays/normals. + - **Accessibility:** Heading typo "## IMPORANT NOTES". Strictness warning repeated verbatim twice. Aimed at STL-format experts. + - **Figures Needed:** Illustration of one triangle (normal + 3 vertices) and how triangles form a surface mesh. + - **Real-World Viz:** Screenshot of an STL surface as a Triangle Geometry. + - **Units Clarity:** STL is unitless — one sentence stating coordinates are in the file author's units (dimensionless to the reader). + - **Concept Links:** Triangle Geometry, surface mesh, STL binary format, attribute byte count, face normals + - **Changes Made:** Added a plain-language opening (an STL file is a list of triangles -> **Triangle Geometry**, with Face Normals/Labels). Fixed the 'IMPORANT NOTES' heading typo. Added an explicit binary-only / ASCII-rejected caveat (confirmed against preflight). Collapsed the duplicated attribute-byte-count warning; noted STL coordinates are unitless. Required Input Sources: None; fixed the Wikipedia anchor. + +- [x] **ReadVtkStructuredPointsFilter** (SimplnxCore) + - **Clarity:** Core idea clear (legacy VTK structured-points → Image Geometry) but POINT_DATA vs CELL_DATA and "eight values per voxel" will confuse non-experts without a figure. Uses legacy SIMPL "Data Container" wording. + - **Completeness:** Explains attribute types, binary/ASCII, point vs cell data with an example. Missing: behavior when both POINT_DATA and CELL_DATA present (output naming/paths). + - **Accessibility:** "STRUCTURED_POINTS", "POINT_DATA", "CELL_DATA", "LOOKUP_TABLE" only partly explained. + - **Figures Needed:** A voxel cube showing cell-center value vs the 8 corner (point) values. + - **Real-World Viz:** Screenshot of the example GrainIds dataset as an Image Geometry. + - **Units Clarity:** State spacing/origin come from the file; length units file-defined. + - **Concept Links:** Image Geometry, Cell Attribute Matrix, structured points, point vs cell data, voxel corners vs center, SCALARS/VECTORS + - **Changes Made:** Replaced legacy 'Data Container' with **Image Geometry** throughout. Added a Point Data vs Cell Data subsection and described the two-output naming (`VTK Cell Data` / `VTK Point Data`) when both are present. Added the missing DREAM3D-NX Help footer and a License section, plus a Spacing/Origin/Units note. Required Input Sources: None. + +- [x] **ReadVolumeGraphicsFileFilter** (SimplnxCore) + - **Clarity:** Thin one-paragraph description; a non-expert won't know "Volume Graphics" data is a CT/VGStudio export. + - **Completeness:** Underspecified — no output geometry type, volume data type, cropping support, or created array named. Only caveat is "both files in same directory". + - **Accessibility:** "Volume Graphics data files" is a vendor term used without explanation. + - **Figures Needed:** Optional small diagram of the `.vgi` (metadata) + `.vol` (raw voxels) pairing. + - **Real-World Viz:** Screenshot of a CT volume from a `.vgi`/`.vol` pair. + - **Units Clarity:** Says units come from the `.vgi`; expand to state which units and that spacing/origin derive from it. + - **Concept Links:** Image Geometry, `.vgi`/`.vol` file pair, spacing/dimensions/units, CT volume + - **Changes Made:** Normalized the group to IO (Input). Defined Volume Graphics data (.vgi metadata + .vol raw voxels; a CT/VGStudio export). Stated the output is an **Image Geometry** with a single float32 density Cell array and origin (0,0,0) (confirmed from preflight); noted no sub-volume extraction. Added an Example Pipelines heading and Required Input Sources: None. + +- [x] **WriteAbaqusHexahedronFilter** (SimplnxCore) + - **Clarity:** Non-expert won't know Abaqus is a commercial FEA package or why one exports a voxel grid to it. Jumps into `.inp` files without framing the Image-Geometry → hexahedral-mesh conversion. + - **Completeness:** Five output files listed but their relationship (master `*Include`s the others) only implied. The `Write Dummy Node` parameter referenced at top but never explained. + - **Accessibility:** "Abaqus", ".inp", "hexahedron", "C3D8", "Hourglass Stiffness", "stress-strain" undefined. The huge raw `_elset.inp` dump hurts readability. + - **Figures Needed:** Diagram of a voxel grid mapping to a hexahedral mesh (8 nodes per voxel). + - **Real-World Viz:** Screenshot of the exported mesh in Abaqus/CAE colored by grain. + - **Units Clarity:** Node coordinates are physical units (matching spacing) but never stated; "Hourglass Stiffness 250" has no units/explanation. + - **Concept Links:** Abaqus/FEA, hexahedral mesh, Image Geometry, FeatureIds, element sets (grains), nodes/elements + - **Changes Made:** Defined Abaqus and FEA; framed the filter as converting an **Image Geometry** voxel grid into a C3D8 8-node hexahedral mesh. Documented the five `.inp` files and the master-file `*Include` relationship, the *Write Dummy Node* and *Hourglass Stiffness* parameters, and that node coordinates are in physical units. Trimmed the large `_elset.inp` dump; added Required Input Sources (FeatureIds + Image Geometry). + +- [x] **WriteLAMMPSFileFilter** (SimplnxCore) + - **Clarity:** Non-expert won't know LAMMPS is a molecular-dynamics code. Purpose stated but why/when unclear. + - **Completeness:** No output-format example. "Example Pipelines" heading empty. Names "Insert Atoms" as producer (good, but informal). + - **Accessibility:** "LAMMPS" never expanded. Legacy "Vertex Data Container" wording. Self-reference "Export LAMMPS Filter" is the wrong name. + - **Figures Needed:** Optional before/after of features filled with atoms. + - **Real-World Viz:** Screenshot of the resulting atom configuration (OVITO/VMD). + - **Units Clarity:** Atom-coordinate units undocumented; state them. + - **Concept Links:** LAMMPS/molecular dynamics, atomistic representation, Vertex Geometry, Insert Atoms + - **Changes Made:** Expanded LAMMPS (Sandia molecular-dynamics code); replaced 'Vertex Data Container' with **Vertex Geometry**; fixed the 'Export LAMMPS Filter' self-reference. Added an output-format example and atom-coordinate units. Added Required Input Sources (Vertex Geometry, e.g. from Insert Atoms -- referenced in plain text since no Insert Atoms doc exists in the repo). Removed the empty Example Pipelines heading. + +- [x] **WriteSPParksSitesFilter** (SimplnxCore) + - **Clarity:** Terse and oddly worded ("LINE 4 evidently must be what is shown"); non-expert won't understand a "sites" file or site/value pairs. + - **Completeness:** No Required Input Sources (needs FeatureIds on an Image Geometry). Line-by-line explanation partial (lines 1, 8 unexplained). + - **Accessibility:** "SPPARKS" linked but not contextualized as a Kinetic Monte Carlo grain-growth simulator. "Kinetic Monte Carlo", "max neighbors", "xlo xhi" undefined. Header style `## Description ##` inconsistent. + - **Figures Needed:** None. + - **Real-World Viz:** None. + - **Units Clarity:** Dimension lines (0 200) are cell-index extents (dimensionless cell counts) — clarify vs physical units. + - **Concept Links:** SPPARKS/Kinetic Monte Carlo, sites, FeatureIds, Image Geometry, Cells + - **Changes Made:** Defined SPPARKS (Sandia Kinetic Monte Carlo microstructure simulator); rewrote the tentative 'LINE 4 evidently' wording authoritatively. Explained site/value = cell/FeatureId, clarified the box-extent lines are dimensionless cell-index counts, and explained the blank separator lines. Normalized '## X ##' headings; added Required Input Sources (FeatureIds on an Image Geometry). + +- [x] **WriteLosAlamosFFTFilter** (SimplnxCore) + - **Clarity:** Output column layout (Phi1 Phi Phi2 X Y Z Feature_ID Phase_ID) explained well, but non-expert won't know what an "FFT 3D simulation code" is for or what Euler angles/phases are. + - **Completeness:** Good format detail and a real reference. No Required Input Sources (needs Euler angles, FeatureIds, Phases on an Image Geometry). Empty "Example Pipelines" heading. + - **Accessibility:** "Euler angles", "Phi1/Phi/Phi2", "phase", "FFT" undefined for a general reader. + - **Figures Needed:** None. + - **Real-World Viz:** None. + - **Units Clarity:** Excellent — Euler angles in degrees, X/Y/Z integer indices, IDs from 1. Model for the batch; keep. + - **Concept Links:** FFT/crystal plasticity, Euler angles, phases, FeatureIds, Image Geometry, CellData + - **Changes Made:** Contextualized Euler angles and the Lebensohn FFT crystal-plasticity code; preserved the existing (model) units paragraph. Added Required Input Sources (Euler angles from an EBSD reader, FeatureIds, Phases) and removed the empty Example Pipelines heading. + +- [x] **ReadDeformKeyFileV12Filter** (SimplnxCore) + - **Clarity:** Two sentences. Non-expert won't know DEFORM is a metal-forming FEA package or what a "key file" is; can't tell what data results. + - **Completeness:** Very thin. Lists variable names (stress, strain, ndtmp) without explanation. Does not describe the resulting DataStructure (a Quad Geometry plus cell/node attribute matrices). + - **Accessibility:** "DEFORM v12", "key file", "ndtmp", "quadrilateral mesh", legacy "Data Container" all undefined. + - **Figures Needed:** Optional screenshot of the imported quad mesh colored by a variable. + - **Real-World Viz:** Render of the loaded DEFORM mesh colored by stress/strain. + - **Units Clarity:** N/A (importer); note imported variable units are whatever DEFORM exported. + - **Concept Links:** DEFORM/FEA, key file, Quad Geometry, nodes/cells, cell vs node variables + - **Changes Made:** Defined DEFORM (metal-forming finite-element package) and a v12 key file. Described the created **Quad Geometry** plus node- and cell-level arrays (ndtmp = nodal temperature); replaced 'Data Container' with Quad Geometry. Added an example key-file snippet; Required Input Sources: None. + +- [x] **WriteVtkRectilinearGridFilter** (SimplnxCore) + - **Clarity:** Never says what a "VTK legacy file" or "RECTILINEAR_GRID dataset" is, nor why one wants this (ParaView/VisIt interop). + - **Completeness:** Single sentence. No ASCII vs binary mention, vertex vs cell data, extension, or that input must be an Image Geometry. + - **Accessibility:** "VTK legacy file", "RECTILINEAR_GRID" undefined. + - **Figures Needed:** Optional shared diagram contrasting rectilinear-grid vs structured-points (variable vs uniform spacing). + - **Real-World Viz:** Screenshot of the `.vtk` in ParaView. + - **Units Clarity:** N/A in prose; confirm in param table. + - **Concept Links:** VTK legacy format, ASCII vs binary VTK, RectilinearGrid vs Image Geometry, ParaView/VisIt + - **Changes Made:** Expanded the one-sentence description; defined VTK legacy format and RECTILINEAR_GRID and named ParaView/VisIt. Explained the **Image Geometry** input is written as an explicit-coordinate rectilinear grid; documented ASCII vs binary. Added Required Input Sources (Image Geometry + cell arrays) and a cross-link to the structured-points variant. + +- [x] **WriteVtkStructuredPointsFilter** (SimplnxCore) + - **Clarity:** Assumes the reader knows STRUCTURED_POINTS. The one useful caveat ("only writes cell data") is present. + - **Completeness:** Very thin. Doesn't explain how structured points differs from rectilinear grid, or when to pick this writer. + - **Accessibility:** "VTK legacy file", "STRUCTURED_POINTS" undefined; indistinguishable from the rectilinear writer to a non-expert. + - **Figures Needed:** Shared diagram (uniform structured points vs variable rectilinear spacing). + - **Real-World Viz:** Screenshot in ParaView. + - **Units Clarity:** N/A in prose. + - **Concept Links:** VTK legacy format, structured points vs rectilinear grid, uniform spacing, ParaView/VisIt + - **Changes Made:** Defined STRUCTURED_POINTS (uniform-spacing image data) with the same VTK/ParaView framing; kept the cell-data-only caveat. Added a 'when to use vs [Write Vtk Rectilinear Grid]' note and ASCII/binary documentation; added Required Input Sources. + +- [x] **WriteAvizoRectilinearCoordinateFilter** (SimplnxCore) + - **Clarity:** Confusing opening ("Values should be present from segmentation … cannot be determined by this filter") — vague about what "values" means (the FeatureIds array). + - **Completeness:** Helpful raw AmiraMesh header example, but never says what Avizo is, what FeatureIds are, or that input is an Image Geometry + Int32 FeatureIds. Example contains garbled DateTime bytes. + - **Accessibility:** "Avizo", "AmiraMesh", "Rectilinear Coordinate", "FeatureIds", "segmentation" undefined. + - **Figures Needed:** None. + - **Real-World Viz:** Screenshot of the output in Avizo. + - **Units Clarity:** Example shows "Coordinates microns" — note the Avizo file hardcodes microns regardless of the geometry's actual units (caveat). + - **Concept Links:** Avizo/AmiraMesh format, FeatureIds, segmentation, RectilinearGrid vs Image Geometry, units (microns) + - **Changes Made:** Rewrote the confusing opening to state the **Image Geometry** + Int32 FeatureIds input plainly; defined Avizo and AmiraMesh. Cleaned the garbled DateTime bytes in the header example; added the hardcoded-microns caveat and ASCII/binary note; added a Group line, Required Input Sources, and a link to the Uniform variant. + +- [x] **WriteAvizoUniformCoordinateFilter** (SimplnxCore) + - **Clarity:** Same vague "Values should be present…" sentence; doesn't clarify FeatureIds input or how "Uniform" differs from "Rectilinear". + - **Completeness:** Example header present but contains empty/garbled fields (blank DateTime, truncated Content/BoundingBox). Avizo/AmiraMesh undefined. + - **Accessibility:** Same undefined jargon as the rectilinear variant. + - **Figures Needed:** None. + - **Real-World Viz:** Screenshot in Avizo. + - **Units Clarity:** "Coordinates microns" hardcoded; caveat needed. BoundingBox units/order should tie to spacing/origin. + - **Concept Links:** Avizo/AmiraMesh format, uniform vs rectilinear coordinates, FeatureIds, BoundingBox, units (microns) + - **Changes Made:** Same clarifications as the Rectilinear variant (FeatureIds input, Avizo/AmiraMesh definitions, microns caveat, cleaned garbled example fields). Added the one-line contrast (single uniform spacing/bounding box vs per-axis coordinate arrays) and a link to the Rectilinear variant; added Required Input Sources. + +- [x] **ReadDREAM3DFilter** (SimplnxCore) + - **Clarity:** Core action clear (reads the DataStructure from a `.dream3d` HDF5 file), but omits the most important behavior: selective/partial import. + - **Completeness:** Missing partial-import behavior, merge-into-current-DataStructure and name-collision behavior, pipeline-metadata read. Lacks the "Group (Subgroup)" header other docs carry. No Required Input Sources statement. + - **Accessibility:** ".dream3d", "HDF5", "legacy" used without a one-line gloss. + - **Figures Needed:** None. + - **Real-World Viz:** Screenshot of the import-data tree selector showing partial-import checkboxes. + - **Units Clarity:** N/A. + - **Concept Links:** `.dream3d` file, HDF5, DataStructure import, partial import, legacy SIMPL vs NX format + - **Changes Made:** Added the missing Group header (IO (Input)) and the key selective/partial-import behavior; explained imported objects merge into the current **DataStructure** at their paths (overwrite on collision) and that pipeline metadata may be read. Glossed .dream3d/HDF5/'legacy'; added Required Input Sources (None) and the standard footer. + +- [x] **ReadEnsembleInfoFilter** (OrientationAnalysis) + - **Clarity:** Mechanics (format, sections, keys) well laid out with tables and a worked example, but the *purpose* is buried in EBSD jargon. + - **Completeness:** Strong on format/enum tables/phase-numbering caveat. Missing: what an Ensemble attribute matrix is, that this filter creates one, where the output goes; `.ini`/`.txt` are the same format. + - **Accessibility:** Main blocker — Ensemble, Feature, Cell, Crystal Structure, Phase Type, Laue class all undefined. + - **Figures Needed:** None (tables serve well). + - **Real-World Viz:** None high-value. + - **Units Clarity:** N/A (enumerated integer codes, well documented). + - **Concept Links:** Ensemble Info, Ensemble/phase attribute matrix, Crystal Structure / Laue class, Phase Type, Feature vs Cell, ASCII `.ini`/`.txt` + - **Changes Made:** Added a plain-language opening defining *ensemble* = phase and clarifying the filter reads a .ini/.txt file and writes an **Ensemble Attribute Matrix** into an existing Data Container. Added one-line glosses for Crystal Structure and Phase Type before the enum tables; documented downstream statistics consumers; removed the empty Example Pipelines heading. + +- [x] **ReadAngDataFilter** (OrientationAnalysis) + - **Clarity:** Reads a single EDAX/TSL `.ang` into an Image Geometry. Good, but never explains what the imported data MEANS (Euler angles, phases, CI, IQ named but undefined). + - **Completeness:** Field-ordering block useful but raw jargon; does not say phi1/Phi/phi2 ARE the three Euler angles (Bunge). Mask/threshold guidance present. + - **Accessibility:** Heavy undefined jargon (Euler angles, crystal/sample reference frame, Confidence Index, Image Quality, phase, ODF, IPF, hexagonal grid). + - **Figures Needed:** Sample vs crystal reference-frame diagram. + - **Real-World Viz:** IPF map of a freshly imported Small IN100 `.ang` slice. + - **Units Clarity:** Weak — should state `.ang` angles are in radians; step size/origin in microns; reference-frame rotations in degrees. + - **Concept Links:** Euler angles (Bunge), sample/crystal reference frame, confidence index, image quality, phases, IPF/ODF, hex-vs-square grid + - **Changes Made:** Glossed phi1/Phi/phi2 as the three Euler angles; defined crystal/sample reference frames and Confidence Index/Image Quality. Fixed 'he following'; converted the Hex-Grid `{ref}` and the bold-only 'Threshold Objects' to MyST links; fixed the broken 'Ensemble Attribute Matrix' bold; added Downstream Processing and Required Input Sources. + +- [x] **ReadCtfDataFilter** (OrientationAnalysis) + - **Clarity:** Clearly reads an Oxford/HKL `.ctf` into an Image Geometry. Good vendor ID. + - **Completeness:** Good on HKL default transforms, radians/degrees conversion, hexagonal phi2 +30°. Created-array meanings not explained. + - **Accessibility:** Same undefined jargon; hexagonal section highly expert-oriented (flagged as edge case). + - **Figures Needed:** Has Figure 1 (Hexagonal_Axis_Alignment); a reference-frame diagram would still help. + - **Real-World Viz:** IPF map before/after the +30° phi2 correction, or correct-vs-wrong radians/degrees. + - **Units Clarity:** Better than Ang (notes `.ctf` usually degrees, NX expects radians); still missing origin/step-size (microns). + - **Concept Links:** Euler angles, sample/crystal reference frame, radians vs degrees, hexagonal symmetry/Bravais lattice, pole figure/IPF + - **Changes Made:** Fixed the intro broken bold and the mangled Figure 1 caption; marked the hexagonal-alignment section Advanced. Converted `{ref}` and bold-only filter mentions to MyST links; added Downstream Processing (Convert Orientation Representation) and Required Input Sources. + +- [x] **ReadChannel5DataFilter** (OrientationAnalysis) + - **Clarity:** Reads an Oxford Channel 5 `.cpr`/`.crc` pair into an Image Geometry. Uses `ImageGeometry`/`ImageDataContainer` as code, inconsistent with the **Image Geometry** bolding used elsewhere. + - **Completeness:** Mirrors the Ctf doc; good note that `.cpr`/`.crc` angles are radians and that Error=0 marks valid TRUE. Created-array meanings not explained. + - **Accessibility:** Same undefined jargon; hexagonal section copied verbatim and wrongly says "(.ctf) files". + - **Figures Needed:** Has Figure 1; reference-frame diagram still helpful. + - **Real-World Viz:** IPF map of an imported Channel 5 dataset. + - **Units Clarity:** Good on radians; missing origin/step-size (microns). + - **Concept Links:** Euler angles, sample/crystal reference frame, hexagonal symmetry, pole figures, IPF, `.cpr`/`.crc` pair + - **Changes Made:** Fixed the broken bold and caption; corrected the phi2 +30-degree bullet that wrongly referenced '.ctf' to Channel 5 (.cpr/.crc). Standardized code-style 'ImageGeometry' to **Image Geometry**; removed the empty Example Pipelines heading; converted links to MyST and added Required Input Sources. + +- [x] **ReadH5EbsdFilter** (OrientationAnalysis) + - **Clarity:** Good — states it reads a `.h5ebsd` built by *Import Orientation File(s) to H5EBSD*; the UI screenshot + checkbox/slice-subset/transform description is genuinely helpful. The one reader with a real upstream dependency. + - **Completeness:** Strong on transforms, angle representation, slice subsetting, correct-vs-incorrect IPF example. Created-array meanings rely on auto-table (correct). Could note headless parameter equivalents for UI features. + - **Accessibility:** Same domain jargon undefined, but the IF-steel correct/incorrect example is excellent. + - **Figures Needed:** Already has UI + correct/incorrect + Hexagonal alignment figures; a reference-frame concept diagram would still help. + - **Real-World Viz:** Already present (IF-steel IPF maps). + - **Units Clarity:** Reference-frame rotations in degrees OK; lines 42/46 are missing the word "degrees" ("apparent 30 shifts", "add 30 to phi2"). + - **Concept Links:** H5Ebsd intermediate format, Euler angle representation (deg/rad), sample/crystal reference frame, slice stacking/subsetting, hexagonal symmetry, IPF + - **Changes Made:** Added a Required Input Sources section stating the .h5ebsd must be built by [Import Orientation File(s) to H5EBSD](EbsdToH5EbsdFilter.md). Converted the three `{ref}` links to MyST; fixed the truncated '30' -> '30 degrees' (two places) and 'excellant' typo; marked the hexagonal section Advanced; added Downstream Processing. + +- [x] **ReadH5EspritDataFilter** (OrientationAnalysis) + - **Clarity:** Clearly reads a single Bruker Nano Esprit `.h5`; before/after UI screenshots for Z Spacing and scan selection help. + - **Completeness:** Good — documents Z Spacing, multi-scan selection, X/Y Step=0 → 1.0 fallback, recommended rotation filters. "MAD" used without expansion. + - **Accessibility:** Same undefined jargon; "MAD" (Mean Angular Deviation) not expanded. + - **Figures Needed:** Has two UI screenshots; reference-frame diagram would help. + - **Real-World Viz:** IPF map of an imported multi-scan Bruker volume (illustrate Z-stacking). + - **Units Clarity:** Best of the `.h5` readers — Z Spacing "microns between each layer". Origin units not stated. + - **Concept Links:** Euler angles, sample/crystal reference frame, scan/slice (Z) stacking, MAD/image quality, Z spacing (microns), multi-scan files + - **Changes Made:** Expanded MAD -> Mean Angular Deviation on first use; converted all `{ref}` links to MyST; noted the zero-step fallback is 1.0 micron. Fixed the broken bold; added Downstream Processing and Required Input Sources; removed the empty Example Pipelines heading. + +- [x] **ReadH5OimDataFilter** (OrientationAnalysis) + - **Clarity:** Clearly reads an EDAX OIMAnalysis `.h5`. UI screenshots referenced for Z Spacing / scan selection. + - **Completeness:** Good — multi-slice import, the valuable unique "Perform Slice By Slice Transform" caveat, thresholding. Created-array meanings rely on auto-table (correct). + - **Accessibility:** Same undefined jargon; slice-by-slice transform note is clear and practical. + - **Figures Needed:** Two UI screenshots; reference-frame diagram would help. + - **Real-World Viz:** IPF map of imported multi-slice EDAX `.h5` showing the slice-by-slice transform consequence. + - **Units Clarity:** Weaker than Esprit — Z Spacing units (microns) not stated here; origin units absent. + - **Concept Links:** Euler angles, sample/crystal reference frame, slice-by-slice transform, scan/slice stacking, confidence index/image quality, IPF + - **Changes Made:** Stated Z Spacing and Origin units as microns (confirmed from parameters); cross-linked the 'Perform Slice By Slice Transform' mention to Rotate Sample Reference Frame. Converted `{ref}` links to MyST, fixed the broken bold, defined CI/IQ; added Downstream Processing and Required Input Sources; removed the empty Example Pipelines heading. + +- [x] **WriteGBCDTriangleDataFilter** (OrientationAnalysis) + - **Clarity:** Decent — writes per-triangle GBCD info (inward/outward Euler angles, normals, areas) with sample output. A general reader won't know why this matters or what "inward/outward" means. + - **Completeness:** Good example with column legend, but the legend has a numbering bug ("Column 8: surface area" should be Column 10; cols 7-9 are the normal). No parameter explanation, no Required Input Sources. + - **Accessibility:** "GBCD", "Euler angles", "triangle normals", "right/left hand average orientation" undefined. Cites Rohrer without a reference link. + - **Figures Needed:** Boundary-triangle diagram: two grains, their average orientations (left/right), triangle normal, area — maps to the columns. + - **Real-World Viz:** Optional screenshot of a surface mesh colored by feature. + - **Units Clarity:** Euler angles stated as RADIANS (good). Normals are unitless direction cosines — say so. Area units (square microns?) not stated. + - **Concept Links:** GBCD, Euler angles, triangle/surface mesh, feature average orientation, crystal structures + - **Changes Made:** Rewrote the description in plain language (grain boundary, **Triangle Geometry**, Euler angles, normal, area). Fixed the column-legend numbering bug (surface area is column 10, not 8). Stated units (Euler radians, unitless normals, square-micron areas), defined inward/outward (left/right) orientations, added a Rohrer citation, and added Required Input Sources naming each producer. NOTE: the same column-legend bug also exists in the C++ algorithm's emitted file header. + +- [x] **WritePoleFigureFilter** (OrientationAnalysis) + - **Clarity:** Output Options sections clear and well organized, but never defines "pole figure"; "modified Lambert square", "unit circle interpolation", "Laue Class" appear undefined. + - **Completeness:** Good coverage + example images. Missing Required Input Sources. The "In a practical sense…" bullet list (Cell Euler Angles, Phases, Mask; Ensemble Laue Class, Material Names) is effectively a hand-written input-array list — borderline defect; reframe as Required Input Sources. + - **Accessibility:** "pole figure", "Lambert projection/square", "Laue Class", "Ensemble", "stereographic" undefined. No MyST links. + - **Figures Needed:** Conceptual diagram of the stereographic/Lambert projection (3D orientation → 2D unit circle). + - **Real-World Viz:** Already shows colorized vs discrete examples; optionally a labeled example (color bar, hemisphere label, phase name). + - **Units Clarity:** "Lambert Image Size (Pixels)" and output size are pixels — state in prose. Euler angles radians (good). + - **Concept Links:** pole figure, Lambert projection, stereographic projection, Laue class/crystal structure, Ensemble/Feature data, IPF, GBCD + - **Changes Made:** Added a plain-language pole-figure definition and first-use definitions of Lambert/stereographic projection and Laue Class. Converted the hand-written 'In a practical sense' input-array list into a proper Required Input Sources section; stated pixel units for image sizes; matched the doc to the current refactored parameters; kept the example images. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| ReadCSVFile | SimplnxCore | Done | +| ReadStringDataArray | SimplnxCore | Done | +| ReadTextDataArray | SimplnxCore | Done | +| WriteASCIIData | SimplnxCore | Done | +| WriteFeatureDataCSV | SimplnxCore | Done | +| ReadImage | SimplnxCore | Done | +| ReadImageStack | SimplnxCore | Done | +| ReadNIfTIFile | SimplnxCore | Done | +| ReadZeissTxmFile | SimplnxCore | Done | +| ReadBinaryCTNorthstar | SimplnxCore | Done | +| WriteNodesAndElementsFiles | SimplnxCore | Done | +| WriteStlFile | SimplnxCore | Done | +| ReadGrainMapper3D | OrientationAnalysis | Done | +| WriteINLFile | OrientationAnalysis | Done | +| WriteStatsGenOdfAngleFile | OrientationAnalysis | Done | + +- [x] **ReadCSVFileFilter** (SimplnxCore) + - **Changes Made:** Converted the bold-only 'Combine Attribute Arrays' mention to a MyST link; gave the 10 identical image alt-texts unique descriptive alts; added Required Input Sources (None). + +- [x] **ReadStringDataArrayFilter** (SimplnxCore) + - **Changes Made:** Fixed typos 'Created Arra Path' and 'mulplying'; converted the quoted 'Read CSV Filter' to a MyST link; added Required Input Sources (None). + +- [x] **ReadTextDataArrayFilter** (SimplnxCore) + - **Changes Made:** Fixed typos 'Created Arra Path', 'mulplying', 'Componenets'; converted 'Read CSV Filter' to a MyST link; added a descriptive image alt; confirmed via the cpp there is no 'New Line' delimiter option here; added Required Input Sources (None). + +- [x] **WriteASCIIDataFilter** (SimplnxCore) + - **Changes Made:** Cleaned the cluttered Group line to 'IO (Output)'; added a 'Maximum Tuples Per Line' description (units = tuples per row, multiple-files mode); noted inputs are user-selected Data Arrays. + +- [x] **WriteFeatureDataCSVFilter** (SimplnxCore) + - **Changes Made:** Defined **Feature** on first use; explained the leading output line is the total Feature count; added Required Input Sources naming [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) and Compute Feature Neighbor Misorientations. + +- [x] **ReadImageFilter** (SimplnxCore) + - **Changes Made:** Added an up-front 'single 2D image' note with a link to the stack reader; stated Origin/Spacing units; added Required Input Sources (None). + +- [x] **ReadImageStackFilter** (SimplnxCore) + - **Changes Made:** Fixed the title to match humanName 'Read Images [3D Stack]'; converted the bold Read Image mention to a MyST link; added a 'File List and Slice Ordering' subsection; defined the luminosity algorithm; stated spacing/origin units; added Required Input Sources (None). + +- [x] **ReadNIfTIFileFilter** (SimplnxCore) + - **Changes Made:** Removed the hand-written `## Parameters` table that duplicated the auto-table (kept the Caveats list); added plain-language glosses for sform/qform/pixdim/vox_offset/scl_slope/scl_inter; noted spacing units come from the file (often mm); added Required Input Sources (None). + +- [x] **ReadZeissTxmFileFilter** (SimplnxCore) + - **Changes Made:** Expanded 'xCT' to X-ray computed tomography on first use; stated spacing/origin/units are read from the file and named the created output array; normalized trailing-## headings; added Required Input Sources (None). + +- [x] **ReadBinaryCTNorthstarFilter** (SimplnxCore) + - **Changes Made:** Normalized the Group line to 'IO (Input)'; defined CT on first use; named the created output array; noted the subvolume start/end are zero-based inclusive voxels; added Required Input Sources (None). + +- [x] **WriteNodesAndElementsFilesFilter** (SimplnxCore) + - **Changes Made:** Added Required Input Sources (any node-based geometry from a meshing/geometry-creation filter); fixed the 'requried' typo; stated node coordinates are in the geometry's physical units. + +- [x] **WriteStlFileFilter** (SimplnxCore) + - **Changes Made:** Fixed the 'implict' typo; clarified the 2-component Features array holds the two Feature IDs on either side of each triangle; noted vertex coordinates are in the Triangle Geometry's units; added Required Input Sources (Triangle Geometry + Face Labels). + +- [x] **ReadGrainMapper3DFilter** (OrientationAnalysis) + - **Changes Made:** Added a GrainMapper3D/XNovo LabDCT gloss; clarified the two IPF-color options; added a millimeters-vs-microns downstream caveat; added Required Input Sources (None). + +- [x] **WriteINLFileFilter** (OrientationAnalysis) + - **Changes Made:** Annotated the output columns with explicit units (Euler radians, positions/step sizes microns); explained the Symmetry column holds crystal-symmetry codes (43 = cubic m-3m, 62 = hexagonal); added Required Input Sources. + +- [x] **WriteStatsGenOdfAngleFileFilter** (OrientationAnalysis) + - **Changes Made:** Expanded ODF to Orientation Distribution Function on first use; fixed 'can not' -> 'cannot'; noted weight and sigma are dimensionless; added Required Input Sources (Euler angles from an EBSD reader; optional Mask from Multi-Threshold Objects). + +### Tier 4 — Adequate + +| Filter | Plugin | Status | +|--------|--------|--------| +| ReadRawBinary | SimplnxCore | Done (minor) | +| WriteImage | SimplnxCore | Done (minor) | +| WriteDREAM3D | SimplnxCore | Done (minor) | + +- [x] **ReadRawBinaryFilter** (SimplnxCore) + - **Changes Made:** Added a 'Required Input Sources: None' note. No other changes — the doc was already a model for the batch. + +- [x] **WriteImageFilter** (SimplnxCore) + - **Changes Made:** Added a Required Input Sources section naming the image readers / image-processing producers. No other changes — already publication-ready. + +- [x] **WriteDREAM3DFilter** (SimplnxCore) + - **Changes Made:** Added the missing Group (Subgroup) header and a Required Input Sources note (none; overwrites existing file). No other changes — already thorough. + +## Batch 8: Image Processing / ITK Wrappers + +**Plugin:** ITKImageProcessing +**Filters:** 88 (ITK-wrapped image-processing filters) + +> Triaged 2026-06-11. Tier split: T1=14, T2=45, T3=26, T4=3. These descriptions were lifted from ITK; the guiding question is whether a general engineer can understand the filter and set its parameters WITHOUT reading ITK's Doxygen. User decisions: trivial intensity ops get minimal-clean treatment; Required Input Sources is a light generic note (ITK inputs are generic scalar images). +> +> **Recurring ITK defects to sweep:** stale `## DREAM3D Mailing Lists` footer (~17 docs); raw Doxygen math `\f[ \f]`/`\f$ \f$` (BinaryThreshold, RescaleIntensity, Normalize, CurvatureFlow, MinMaxCurvatureFlow); mangled `.* ClassName`/`\sa`/`\li` See-Also artifacts dumped inline (pervasive); C++/developer symbols (`itk::`, `NumericTraits<>`, 'templated over', `Set*()` methods, `m_*`); hand-duplicated parameter tables missing the auto-table marker (IsoContourDistance, GradientMagnitudeRecursiveGaussian, ImportFijiMontage, ThresholdMaximumConnectedComponents). +> +> **Bugs / mismatches found:** ITKGrayscaleErode says 'Erosion takes the maximum' (should be minimum); ITKExpNegative describes a user-provided constant K the filter does not expose; ITKLog has no description text; ITKThreshold lists Above/Below/Outside methods not exposed as params; ITKAdaptiveHistogramEqualization prose may describe alpha/beta that are not exposed — all to verify against the cpp during rewrite. +> +> **Shared concepts to author once and reuse:** morphology (erosion/dilation/opening/closing + the structuring element / kernel radius in pixels); projection-along-an-axis (Projection Dimension); connectivity (Fully Connected = face-only vs face+edge+vertex); distance maps (signed = inside negative; squared-distance and use-image-spacing toggles). **Naming collisions:** ITK Read Image / Read Images [3D Stack] vs the SimplnxCore filters of the same human name — disambiguate and cross-link. + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| ITKCurvatureAnisotropicDiffusionImageFilter | ITKImageProcessing | Done | +| ITKGradientAnisotropicDiffusionImageFilter | ITKImageProcessing | Done | +| ITKCurvatureFlowImageFilter | ITKImageProcessing | Done | +| ITKMinMaxCurvatureFlowImageFilter | ITKImageProcessing | Done | +| ITKBinaryOpeningByReconstructionImageFilter | ITKImageProcessing | Done | +| ITKBinaryThinningImageFilter | ITKImageProcessing | Done | +| ITKMorphologicalGradientImageFilter | ITKImageProcessing | Done | +| ITKClosingByReconstructionImageFilter | ITKImageProcessing | Done | +| ITKOpeningByReconstructionImageFilter | ITKImageProcessing | Done | +| ITKBinaryThresholdImageFilter | ITKImageProcessing | Done | +| ITKDoubleThresholdImageFilter | ITKImageProcessing | Done | +| ITKIsoContourDistanceImageFilter | ITKImageProcessing | Done | +| ITKMorphologicalWatershedImageFilter | ITKImageProcessing | Done | +| ITKMorphologicalWatershedFromMarkersImageFilter | ITKImageProcessing | Done | + +- [x] **ITKCurvatureAnisotropicDiffusionImageFilter** (ITKImageProcessing) + - **Changes Made:** Added a plain-language 'what is anisotropic diffusion' lead and an MCDE note; stripped itk:: symbols; documented the previously-undocumented Conductance Scaling Update Interval; kept the TimeStep/Conductance/Iterations guidance with stability values; fixed the stale footer; cleaned the See-Also. + +- [x] **ITKGradientAnisotropicDiffusionImageFilter** (ITKImageProcessing) + - **Changes Made:** Added a plain-language Perona-Malik / edge-stopping lead; stripped itk:: symbols and fixed the copy-paste 'CurvatureND' reference; documented Conductance Scaling Update Interval; promoted the bare URLs to a See-Also; fixed the stale footer. + +- [x] **ITKCurvatureFlowImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced the raw Doxygen math with a plain contour-curvature explanation; trimmed the solver-internals/padding paragraphs; added a concrete TimeStep typical value; fixed the stale footer; kept the Sethian reference. + +- [x] **ITKMinMaxCurvatureFlowImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced ALL raw Doxygen math with a plain explanation of the min/max scale switch; defined Stencil Radius in pixels with a typical value; added TimeStep/iterations guidance; fixed the stale footer. + +- [x] **ITKBinaryOpeningByReconstructionImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined reconstruction and the shape-preservation advantage over plain opening; fixed the \sa run-on; stated Kernel Radius in pixels and defined Foreground/Background/Fully Connected; kept the figure and Kernel Type table; light Required Input Sources note. + +- [x] **ITKBinaryThinningImageFilter** (ITKImageProcessing) + - **Changes Made:** Removed the 'parameterized over...' and 'To do: Make this filter ND.*' fragments; defined skeleton/medial axis and restated the 2D-only behavior as a plain caveat; light Required Input Sources note; kept the Gonzalez/Woods reference. + +- [x] **ITKMorphologicalGradientImageFilter** (ITKImageProcessing) + - **Changes Made:** Rewrote the description from scratch: morphological gradient = dilation - erosion = edge magnitude; stripped the ITK boilerplate/cross-ref tail; stated Kernel Radius in pixels; kept the Kernel Type table. + +- [x] **ITKClosingByReconstructionImageFilter** (ITKImageProcessing) + - **Changes Made:** Fixed the garbled 'levels raises' and broken PreserveIntensities sentences; defined Preserve Intensities and Fully Connected; stated Kernel Radius in pixels; explained the reconstruction concept; kept the Soille reference. + +- [x] **ITKOpeningByReconstructionImageFilter** (ITKImageProcessing) + - **Changes Made:** As with Closing-by-Reconstruction: fixed the garbled sentences, defined Preserve Intensities + Fully Connected, stated Kernel Radius in pixels, explained reconstruction. + +- [x] **ITKBinaryThresholdImageFilter** (ITKImageProcessing) + - **Changes Made:** Converted the raw Doxygen \f[...\f] piecewise math to a MyST $$ block; stripped NumericTraits/'templated over' text; stated Lower/Upper are in intensity units (usually set only one) and Inside/Outside are uint8 labels; kept the figure. + +- [x] **ITKDoubleThresholdImageFilter** (ITKImageProcessing) + - **Changes Made:** Mapped Threshold1-4 to the narrow (T2-T3) inside wide (T1-T4) hysteresis ranges with the ordering requirement and intensity units; removed the broken ITK See-Also bullets; defined Fully Connected; fixed the stale footer. + +- [x] **ITKIsoContourDistanceImageFilter** (ITKImageProcessing) + - **Changes Made:** Led with a plain definition (for a level-set/signed image, the distance from near-contour pixels to the zero contour); defined level set/iso-contour/narrowband; DELETED the hand-written Parameters/Required/Created tables and ADDED the auto-table marker; described Far Value correctly as a clamp distance (default 10) — NOTE the cpp FarValue docstring is a copy-paste bug; fixed the stale footer. + +- [x] **ITKMorphologicalWatershedImageFilter** (ITKImageProcessing) + - **Changes Made:** Led with the terrain/flooding analogy; defined catchment basin and watershed line; documented Level (intensity, over-segmentation control), Mark Watershed Line, Fully Connected; noted the over-segmentation tendency, the Relabel follow-up, and the marker-controlled variant; stripped TOutputImage; kept the Soille/IJ reference. + +- [x] **ITKMorphologicalWatershedFromMarkersImageFilter** (ITKImageProcessing) + - **Changes Made:** Removed the redundant title parenthetical; led with the marker-controlled watershed concept; documented Mark Watershed Line and Fully Connected; added a prominent note that the NX wrapper currently exposes only a single input array (no separate marker-image parameter) — flagged for verification; fixed the malformed See-Also and stale footer. + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| ITKSigmoidImageFilter | ITKImageProcessing | Done | +| ITKIntensityWindowingImageFilter | ITKImageProcessing | Done | +| ITKRescaleIntensityImageFilter | ITKImageProcessing | Done | +| ITKDiscreteGaussianImageFilter | ITKImageProcessing | Done | +| ITKSmoothingRecursiveGaussianImageFilter | ITKImageProcessing | Done | +| ITKMedianImageFilter | ITKImageProcessing | Done | +| ITKAdaptiveHistogramEqualizationImageFilter | ITKImageProcessing | Done | +| ITKBinaryDilateImageFilter | ITKImageProcessing | Done | +| ITKBinaryErodeImageFilter | ITKImageProcessing | Done | +| ITKBinaryMorphologicalClosingImageFilter | ITKImageProcessing | Done | +| ITKBinaryMorphologicalOpeningImageFilter | ITKImageProcessing | Done | +| ITKBinaryContourImageFilter | ITKImageProcessing | Done | +| ITKDilateObjectMorphologyImageFilter | ITKImageProcessing | Done | +| ITKErodeObjectMorphologyImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleDilateImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleErodeImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleMorphologicalClosingImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleMorphologicalOpeningImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleFillholeImageFilter | ITKImageProcessing | Done | +| ITKGrayscaleGrindPeakImageFilter | ITKImageProcessing | Done | +| ITKBlackTopHatImageFilter | ITKImageProcessing | Done | +| ITKWhiteTopHatImageFilter | ITKImageProcessing | Done | +| ITKThresholdImageFilter | ITKImageProcessing | Done | +| ITKOtsuMultipleThresholdsImageFilter | ITKImageProcessing | Done | +| ITKThresholdMaximumConnectedComponentsImageFilter | ITKImageProcessing | Done | +| ITKHConvexImageFilter | ITKImageProcessing | Done | +| ITKHMaximaImageFilter | ITKImageProcessing | Done | +| ITKHMinimaImageFilter | ITKImageProcessing | Done | +| ITKApproximateSignedDistanceMapImageFilter | ITKImageProcessing | Done | +| ITKDanielssonDistanceMapImageFilter | ITKImageProcessing | Done | +| ITKSignedDanielssonDistanceMapImageFilter | ITKImageProcessing | Done | +| ITKSignedMaurerDistanceMapImageFilter | ITKImageProcessing | Done | +| ITKGradientMagnitudeRecursiveGaussianImageFilter | ITKImageProcessing | Done | +| ITKZeroCrossingImageFilter | ITKImageProcessing | Done | +| ITKConnectedComponentImageFilter | ITKImageProcessing | Done | +| ITKRelabelComponentImageFilter | ITKImageProcessing | Done | +| ITKLabelContourImageFilter | ITKImageProcessing | Done | +| ITKMaximumProjectionImageFilter | ITKImageProcessing | Done | +| ITKMeanProjectionImageFilter | ITKImageProcessing | Done | +| ITKMedianProjectionImageFilter | ITKImageProcessing | Done | +| ITKMinimumProjectionImageFilter | ITKImageProcessing | Done | +| ITKStandardDeviationProjectionImageFilter | ITKImageProcessing | Done | +| ITKSumProjectionImageFilter | ITKImageProcessing | Done | +| ITKBinaryProjectionImageFilter | ITKImageProcessing | Done | +| ITKImportFijiMontageFilter | ITKImageProcessing | Done | + +- [x] **ITKSigmoidImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined the sigmoid S-curve remap with MyST math; documented Alpha (transition width), Beta (center), Output Min/Max; light Required Input Sources. + +- [x] **ITKIntensityWindowingImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined the window/level remap; fixed the mangled See-Also fragment and 'RealType'; stated all four params in intensity units. + +- [x] **ITKRescaleIntensityImageFilter** (ITKImageProcessing) + - **Changes Made:** Converted the Doxygen formula to MyST; clarified only Output Min/Max are user-set (input auto-detected); fixed the mangled See-Also. + +- [x] **ITKDiscreteGaussianImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined Gaussian blur; clarified Variance = sigma^2 with units (px^2 / physical^2); documented MaximumKernelWidth/MaximumError/UseImageSpacing; removed the ITK artifact + class list. + +- [x] **ITKSmoothingRecursiveGaussianImageFilter** (ITKImageProcessing) + - **Changes Made:** Led with the constant-time-vs-sigma advantage; Sigma units; explained Normalize Across Scale; fixed the stale footer and stray '|'. + +- [x] **ITKMedianImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined the median filter (salt-and-pepper removal, edge-preserving); Radius in pixels (window 2r+1); removed the operator<()/class-list artifact. + +- [x] **ITKAdaptiveHistogramEqualizationImageFilter** (ITKImageProcessing) + - **Changes Made:** Confirmed alpha/beta ARE exposed in the cpp; added pixels unit to Radius; documented alpha/beta/window; light Required Input Sources. + +- [x] **ITKBinaryDilateImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined dilation (grows foreground); documented Foreground/Background/BoundaryToForeground and Kernel Radius (pixels); stripped C++ symbols + See-Also run-on; cross-linked siblings. + +- [x] **ITKBinaryErodeImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined erosion (shrinks foreground; eroded->Background); replaced the NonpositiveMin() wording; Kernel Radius (pixels); cross-linked siblings. + +- [x] **ITKBinaryMorphologicalClosingImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined closing = dilate-then-erode (fills small holes); Foreground Value, Kernel Radius (pixels), Safe Border; stripped ITK Related-Filters; cross-linked siblings. + +- [x] **ITKBinaryMorphologicalOpeningImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined opening = erode-then-dilate (removes small specks); fixed 'Dilatation'; Foreground/Background, Kernel Radius (pixels); cross-linked siblings. + +- [x] **ITKBinaryContourImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined object-outline extraction; Foreground/Background values and Fully Connected (On=thicker); replaced SetFullyConnected(); cross-linked Label Contour. + +- [x] **ITKDilateObjectMorphologyImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined single-object dilation; Object Value + Kernel Radius (pixels); fixed the See-Also run-on; noted the distinction from Binary Dilate. + +- [x] **ITKErodeObjectMorphologyImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined single-object erosion; Object Value/Background Value + Kernel Radius (pixels); fixed the See-Also run-on; noted the distinction from Binary Erode. + +- [x] **ITKGrayscaleDilateImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined grayscale dilation = local max filter; Kernel Radius (pixels); stripped the ITK cross-ref tail. + +- [x] **ITKGrayscaleErodeImageFilter** (ITKImageProcessing) + - **Changes Made:** FIXED the factual error (erosion is the minimum, not maximum); defined grayscale erosion = local min; Kernel Radius (pixels); stripped the ITK tail. + +- [x] **ITKGrayscaleMorphologicalClosingImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined grayscale closing = dilate-then-erode (removes small dark features); Kernel Radius (pixels), Safe Border; stripped the mismatched ITK tail. + +- [x] **ITKGrayscaleMorphologicalOpeningImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined grayscale opening = erode-then-dilate (removes small bright features); Kernel Radius (pixels), Safe Border; stripped the ITK tail. + +- [x] **ITKGrayscaleFillholeImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined hole-filling (enclosed dark minima); documented Fully Connected; trimmed the geodesic-implementation noise; kept the Soille reference. + +- [x] **ITKGrayscaleGrindPeakImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined peak-removal (enclosed bright maxima; dual of Fillhole); documented Fully Connected; trimmed/fixed the geodesic implementation paragraph. + +- [x] **ITKBlackTopHatImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined black top-hat = closing minus image (small dark detail); Kernel Radius (pixels) tied to feature scale, Safe Border; removed the empty Related Filters heading. + +- [x] **ITKWhiteTopHatImageFilter** (ITKImageProcessing) + - **Changes Made:** Added a real description (image minus opening = small bright detail); Kernel Radius (pixels), Safe Border; removed the empty Related Filters heading. + +- [x] **ITKThresholdImageFilter** (ITKImageProcessing) + - **Changes Made:** Removed the phantom ThresholdAbove/Below/Outside method list; rewrote to the actual Lower/Upper/OutsideValue params (out-of-range -> OutsideValue, in-range kept); intensity units; contrasted with Binary Threshold. + +- [x] **ITKOtsuMultipleThresholdsImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined Otsu (automatic variance-maximizing thresholds; N+1-class label map); removed ITK class/setter/test names and fixed the mangled run-on; per-param guidance (thresholds/bins/offset/valley emphasis/bin midpoint). + +- [x] **ITKThresholdMaximumConnectedComponentsImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined the topological auto-threshold (maximizes object count above a minimum size); removed debug/ITK-method text, the broken sentence, and the personal-email block; fixed the stale footer; documented UpperBoundary/MinimumObjectSizeInPixels/Inside/Outside; replaced the hand Parameters prose. + +- [x] **ITKHConvexImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined h-convex (extracts peaks rising more than h above background); Height in intensity units, FullyConnected; stripped the mangled See-Also tail. + +- [x] **ITKHMaximaImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined h-maxima (suppresses maxima shallower than h); Height in intensity units; removed SetHeight + the mangled See-Also; cross-linked H Convex/H Minima. + +- [x] **ITKHMinimaImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined h-minima (fills minima shallower than h); Height + FullyConnected; stripped the mangled See-Also; replaced the non-NX HConcave reference. + +- [x] **ITKApproximateSignedDistanceMapImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined signed distance map (inside negative) via Chamfer approximation (pixels); concrete Inside/Outside Value example; demoted ITK siblings to See Also; fixed the stale footer. + +- [x] **ITKDanielssonDistanceMapImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined distance map + Voronoi partition + offset-vector outputs in lay terms; documented Input Is Binary / Squared Distance / Use Image Spacing (pixels vs physical); stripped itk::Offset/'4SED'; fixed the stale footer. + +- [x] **ITKSignedDanielssonDistanceMapImageFilter** (ITKImageProcessing) + - **Changes Made:** Stripped the \li markup and the 'parameterized over' text; fixed the broken ITK link; documented Inside Is Positive / Squared Distance / Use Image Spacing; fixed the stale footer. + +- [x] **ITKSignedMaurerDistanceMapImageFilter** (ITKImageProcessing) + - **Changes Made:** Trimmed the C++ type discussion; prominently flagged that Squared Distance defaults TRUE; documented Use Image Spacing / Background Value; fixed run-in sub-headers; kept the Maurer reference. + +- [x] **ITKGradientMagnitudeRecursiveGaussianImageFilter** (ITKImageProcessing) + - **Changes Made:** DELETED the hand Parameters/Required/Created tables and ADDED the missing auto-table marker; defined gradient magnitude (edge strength); emphasized Sigma is in image-spacing (physical) units; rewrote Normalize Across Scale; fixed the stale footer. + +- [x] **ITKZeroCrossingImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined zero-crossing edge detection on a signed input; stripped itk::/operator/NumericTraits text; restated the Foreground/Background label params; Required Input Sources = a signed (Laplacian-of-Gaussian) image; fixed the stale footer. + +- [x] **ITKConnectedComponentImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined connected components / label image; documented Fully Connected (+1-pixel note); noted the Relabel Component follow-up; stripped ITK method names + the useless See-Also; fixed the stale footer. + +- [x] **ITKRelabelComponentImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined relabel (consecutive, size-sorted; optional minimum size); documented Minimum Object Size in pixels and SortByObjectSize; stripped ITK method names + the InPlace paragraph + the mangled See-Also; Required Input Sources = a label image. + +- [x] **ITKLabelContourImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined label-region outline extraction; documented Background Value + Fully Connected (thicker-contours note); stripped SetFullyConnected(); moved the Insight-Journal URL to See Also; Required Input Sources = a label image. + +- [x] **ITKMaximumProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Added the shared projection concept (3D->2D, maximum along an axis); documented Projection Dimension (axis index) + Perform In-Place + the dimensionality note; trimmed the Doxygen See-Also. + +- [x] **ITKMeanProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Shared projection concept (mean along an axis); cross-linked Median for outlier sensitivity; removed the stray title parenthetical; trimmed the See-Also. + +- [x] **ITKMedianProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Shared projection concept (median along an axis; outlier-robust vs mean); removed the stray title parenthetical; trimmed the See-Also. + +- [x] **ITKMinimumProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Shared projection concept (minimum along an axis; dark-feature counterpart); removed the stray title parenthetical; trimmed the See-Also. + +- [x] **ITKStandardDeviationProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Shared projection concept (standard deviation along an axis; highlights variability); fixed the stale footer; deduped the See-Also. + +- [x] **ITKSumProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Shared projection concept (sum along an axis); added an overflow/data-type caution; fixed the stale footer; deduped the See-Also. + +- [x] **ITKBinaryProjectionImageFilter** (ITKImageProcessing) + - **Changes Made:** Refined the projection text; documented the logical-OR rule, Foreground/Background Value, Projection Dimension, Perform In-Place; deduped Related Filters; removed the ITK Doxygen link list. + +- [x] **ITKImportFijiMontageFilter** (ITKImageProcessing) + - **Changes Made:** Title matches humanName 'Read Fiji Montage (ITK)'; rewrote the output description in current DataStructure terms (per the cpp: per-tile Image Geometry -> Cell Attribute Matrix -> Image array); removed the hand-listed Length Unit / Output Data Type enums; fixed typos; replaced the stale Google-Groups footer; corrected the false 'same name' claim. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| ITKAbsImageFilter | ITKImageProcessing | Done | +| ITKAcosImageFilter | ITKImageProcessing | Done | +| ITKAsinImageFilter | ITKImageProcessing | Done | +| ITKAtanImageFilter | ITKImageProcessing | Done | +| ITKCosImageFilter | ITKImageProcessing | Done | +| ITKSinImageFilter | ITKImageProcessing | Done | +| ITKTanImageFilter | ITKImageProcessing | Done | +| ITKExpImageFilter | ITKImageProcessing | Done | +| ITKExpNegativeImageFilter | ITKImageProcessing | Done | +| ITKLogImageFilter | ITKImageProcessing | Done | +| ITKLog10ImageFilter | ITKImageProcessing | Done | +| ITKSqrtImageFilter | ITKImageProcessing | Done | +| ITKNotImageFilter | ITKImageProcessing | Done | +| ITKInvertIntensityImageFilter | ITKImageProcessing | Done | +| ITKBoundedReciprocalImageFilter | ITKImageProcessing | Done | +| ITKNormalizeImageFilter | ITKImageProcessing | Done | +| ITKNormalizeToConstantImageFilter | ITKImageProcessing | Done | +| ITKRegionalMaximaImageFilter | ITKImageProcessing | Done | +| ITKRegionalMinimaImageFilter | ITKImageProcessing | Done | +| ITKValuedRegionalMaximaImageFilter | ITKImageProcessing | Done | +| ITKValuedRegionalMinimaImageFilter | ITKImageProcessing | Done | +| ITKGradientMagnitudeImageFilter | ITKImageProcessing | Done | +| ITKLaplacianRecursiveGaussianImageFilter | ITKImageProcessing | Done | +| ITKMaskImageFilter | ITKImageProcessing | Done | +| ITKImageReaderFilter | ITKImageProcessing | Done | +| ITKMhaFileReaderFilter | ITKImageProcessing | Done | + +- [x] **ITKAbsImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced the 'itk::Math::abs()' line with a plain one-sentence description (absolute value / magnitude). + +- [x] **ITKAcosImageFilter** (ITKImageProcessing) + - **Changes Made:** Collapsed the templating/cast boilerplate to one sentence: arccosine; input [-1,1]; output in radians. + +- [x] **ITKAsinImageFilter** (ITKImageProcessing) + - **Changes Made:** One sentence: arcsine; input [-1,1]; output in radians. + +- [x] **ITKAtanImageFilter** (ITKImageProcessing) + - **Changes Made:** One sentence: arctangent; output in radians. + +- [x] **ITKCosImageFilter** (ITKImageProcessing) + - **Changes Made:** One sentence: cosine; values interpreted as radians; output [-1,1]. + +- [x] **ITKSinImageFilter** (ITKImageProcessing) + - **Changes Made:** Reworded to plain 'sine (values in radians)'; dropped std::sin; kept the figure. + +- [x] **ITKTanImageFilter** (ITKImageProcessing) + - **Changes Made:** Reworded to plain 'tangent (values in radians)'; dropped std::tan. + +- [x] **ITKExpImageFilter** (ITKImageProcessing) + - **Changes Made:** Reworded to 'natural exponential e^pixel'; dropped std::exp. + +- [x] **ITKExpNegativeImageFilter** (ITKImageProcessing) + - **Changes Made:** Verified NO K parameter is exposed (functor default-constructed, K fixed at 1); corrected the summary and description to exp(-x) instead of the phantom 'user-provided constant K'. + +- [x] **ITKLogImageFilter** (ITKImageProcessing) + - **Changes Made:** Added the missing description sentence (natural logarithm; input must be > 0); kept the figure. + +- [x] **ITKLog10ImageFilter** (ITKImageProcessing) + - **Changes Made:** Reworded to 'base-10 logarithm; input must be > 0'; dropped std::log10. + +- [x] **ITKSqrtImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced the std::sqrt line with a plain description (square root; non-negative input). + +- [x] **ITKNotImageFilter** (ITKImageProcessing) + - **Changes Made:** Removed the templated/bool text and the raw C++ code block + m_* symbols; plain description (integer image; 0->Foreground, non-zero->Background). + +- [x] **ITKInvertIntensityImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced 'SetMaximum' with plain Maximum-minus-pixel guidance (set Maximum to the largest intensity, e.g. 255 for 8-bit); trimmed ITK Author/Related-Filters. + +- [x] **ITKBoundedReciprocalImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced the dimension/scalar-type sentence with the 1/(1+x) description (bounded (0,1] for non-negative input). + +- [x] **ITKNormalizeImageFilter** (ITKImageProcessing) + - **Changes Made:** Converted the Doxygen $-sigma$/$+sigma$ to MyST math; removed the mangled See-Also fragment and internal class names; kept the integral-type caveat. + +- [x] **ITKNormalizeToConstantImageFilter** (ITKImageProcessing) + - **Changes Made:** Dropped the redundant title parenthetical; replaced 'SetConstant()' with the Constant parameter (dimensionless target sum, default 1); fixed the stale footer. + +- [x] **ITKRegionalMaximaImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined regional maxima; documented Flat Is Maxima + Fully Connected; noted Background/Foreground are output labels; fixed the stale footer; dropped ITK Author/See-Also. + +- [x] **ITKRegionalMinimaImageFilter** (ITKImageProcessing) + - **Changes Made:** Defined regional minima; de-duplicated the repeated author block; documented Flat Is Minima + Fully Connected; fixed the stale footer; dropped the non-NX HConcave See-Also. + +- [x] **ITKValuedRegionalMaximaImageFilter** (ITKImageProcessing) + - **Changes Made:** Moved the connectivity paragraph into the Description; trimmed the non-NX Related Filters; kept the FullyConnected explanation; added Required Input Sources. + +- [x] **ITKValuedRegionalMinimaImageFilter** (ITKImageProcessing) + - **Changes Made:** Added the FullyConnected/connectivity explanation (mirroring the Maxima doc); tidied the Related Filters run-on; dropped the non-NX entries. + +- [x] **ITKGradientMagnitudeImageFilter** (ITKImageProcessing) + - **Changes Made:** Replaced the duplicated description with a one-sentence gradient-magnitude definition + the noise-sensitivity contrast vs the Recursive Gaussian variant; removed the meaningless ITK building-block Related-Filters list. + +- [x] **ITKLaplacianRecursiveGaussianImageFilter** (ITKImageProcessing) + - **Changes Made:** Added the Laplacian-of-Gaussian definition + the Zero Crossing follow-up link; documented Sigma (image-spacing units) and Normalize Across Scale; fixed the stale footer. + +- [x] **ITKMaskImageFilter** (ITKImageProcessing) + - **Changes Made:** Rewrote the Description as plain prose (dropped 'templated over', the diff-marked code block, Wiki-Examples cruft); documented Outside Value; fixed the stale footer; kept the figure. + +- [x] **ITKImageReaderFilter** (ITKImageProcessing) + - **Changes Made:** Dropped the 'directly wraps an ITK filter' boilerplate; added a note distinguishing it from the SimplnxCore Read Image filter (same human name) + cross-link. (humanName: Read Image (ITK)) + +- [x] **ITKMhaFileReaderFilter** (ITKImageProcessing) + - **Changes Made:** Fixed the typos; added a cross-link to Read Image (ITK) noting this variant handles the embedded transform; trimmed the orthogonal-matrix Technical Discussion. + +### Tier 4 — Adequate + +| Filter | Plugin | Status | +|--------|--------|--------| +| ITKSquareImageFilter | ITKImageProcessing | Done | +| ITKImageWriterFilter | ITKImageProcessing | Done | +| ITKImportImageStackFilter | ITKImageProcessing | Done | + +- [x] **ITKSquareImageFilter** (ITKImageProcessing) + - **Changes Made:** Added the missing one-sentence description ('square of each pixel'). Otherwise adequate. + +- [x] **ITKImageWriterFilter** (ITKImageProcessing) + - **Changes Made:** No change needed — already clean and complete (humanName: Write Image (ITK)). + +- [x] **ITKImportImageStackFilter** (ITKImageProcessing) + - **Changes Made:** Dropped the 'directly wraps' boilerplate; added a note distinguishing it from the SimplnxCore Read Images [3D Stack] filter + cross-link. Otherwise adequate. (humanName: Read Images [3D Stack] (ITK)) + +## Batch 9: Remaining SimplnxCore Filters + +**Plugin:** SimplnxCore +**Filters:** 73 (catch-all for SimplnxCore filters not covered by Batches 1-7; the ITK plugin is Batch 8, deferred) + +> Triaged 2026-06-11. Tier split: T1=4, T2=35, T3=31, T4=3. Rewrites will be committed per tier (Tier 2 split into sub-theme sub-commits given its size). Recurring defects flagged: hand-duplicated parameter tables (HierarchicalSmooth; CreatePythonSkeleton — also missing the marker), a legacy `@ref` directive (ComputeBoundingBoxStats), Doxygen math/`@image` artifacts (Silhouette, FeatureFaceCurvature, PointSampleTriangleGeometry), legacy 'Data Container' wording (NearestPointFuseRegularGrids, RemoveFlaggedVertices, ExtractInternalSurfaces), and many bold-only filter mentions. + +### Tier 1 — Critical + +| Filter | Plugin | Status | +|--------|--------|--------| +| FlyingEdges3D | SimplnxCore | Done | +| TriangleDihedralAngle | SimplnxCore | Done | +| NearestPointFuseRegularGrids | SimplnxCore | Done | +| PointSampleEdgeGeometry | SimplnxCore | Done | + +- [x] **FlyingEdges3DFilter** (SimplnxCore) + - **Changes Made:** Expanded the one-sentence stub: added 'What is an Isosurface?' (contour-line analogy, isovalue), noted Flying Edges is a fast marching-cubes variant, added 'When to Use' contrasting with Surface Nets / Quick Surface Mesh for label maps, documented the Contour Value units (same as the data array) and Required Input Sources (Image Geometry + scalar array). Captioned the figure. + +- [x] **TriangleDihedralAngleFilter** (SimplnxCore) + - **Changes Made:** Replaced the 'matrix mathematics' stub with a plain explanation of the minimum interior angle as a mesh-quality metric (60 deg = equilateral, near-0 deg = sliver). Stated output units are degrees (0-60). Added Required Input Sources (Triangle Geometry from a surface-meshing filter). + +- [x] **NearestPointFuseRegularGridsFilter** (SimplnxCore) + - **Changes Made:** Replaced all legacy 'Data Container' terminology with Image Geometry. Explained Reference (destination) vs Sampling (source) roles, that assignment is by nearest cell-center using each grid's origin/spacing (no interpolation), and that the grids may differ in spacing/extent. Documented the Use Custom Fill Value behavior for out-of-overlap cells. Added Required Input Sources (the two Image Geometries). + +- [x] **PointSampleEdgeGeometryFilter** (SimplnxCore) + - **Changes Made:** Added the missing Group header (Sampling (Geometry)). Defined Edge Geometry, 'scan vector' (an additive-manufacturing laser-path segment), and 'edge ID'. Stated the Sampling Spacing units are millimeters and explained Cumulative Sample Distance. Added Required Input Sources (Edge Geometry from Slice Triangle Geometry / Create AM Scan Paths). + +### Tier 2 — Important + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeArrayStatistics | SimplnxCore | Done | +| ComputeBoundingBoxStats | SimplnxCore | Done | +| ComputeVolumeFractions | SimplnxCore | Done | +| ComputeFeatureClustering | SimplnxCore | Done | +| ComputeBoundaryElementFractions | SimplnxCore | Done | +| ComputeEuclideanDistMap | SimplnxCore | Done | +| ComputeMomentInvariants2D | SimplnxCore | Done | +| ComputeKMeans | SimplnxCore | Done | +| ComputeKMedoids | SimplnxCore | Done | +| Silhouette | SimplnxCore | Done | +| ApproximatePointCloudHull | SimplnxCore | Done | +| MapPointCloudToRegularGrid | SimplnxCore | Done | +| IterativeClosestPoint | SimplnxCore | Done | +| IdentifyDuplicateVertices | SimplnxCore | Done | +| ComputeTriangleAreas | SimplnxCore | Done | +| ComputeTriangleGeomCentroids | SimplnxCore | Done | +| ComputeTriangleGeomVolumes | SimplnxCore | Done | +| TriangleCentroid | SimplnxCore | Done | +| TriangleNormal | SimplnxCore | Done | +| FeatureFaceCurvature | SimplnxCore | Done | +| SharedFeatureFace | SimplnxCore | Done | +| SurfaceNets | SimplnxCore | Done | +| LaplacianSmoothing | SimplnxCore | Done | +| UncertainRegularGridSampleSurfaceMesh | SimplnxCore | Done | +| ExtractInternalSurfacesFromTriangleGeometry | SimplnxCore | Done | +| ReverseTriangleWinding | SimplnxCore | Done | +| VerifyTriangleWinding | SimplnxCore | Done | +| RemoveFlaggedEdges | SimplnxCore | Done | +| RemoveFlaggedTriangles | SimplnxCore | Done | +| CropVertexGeometry | SimplnxCore | Done | +| CombineNodeBasedGeometries | SimplnxCore | Done | +| PointSampleTriangleGeometry | SimplnxCore | Done | +| ExtractFeatureBoundaries2D | SimplnxCore | Done | +| RobustAutomaticThreshold | SimplnxCore | Done | +| ComputeVectorColors | SimplnxCore | Done | + +- [x] **ComputeArrayStatisticsFilter** (SimplnxCore) + - **Changes Made:** Fixed the stale group to 'Statistics'; defined Feature/Ensemble; condensed the redundant Ranges Breakdown Options 1-4; fixed spelling (aproiri/achived/occurance/exisitng); added Required Input Sources (Feature Ids producer). Kept the statistic-type table. + +- [x] **ComputeBoundingBoxStatsFilter** (SimplnxCore) + - **Changes Made:** Converted the legacy @ref directive and the Compute Array Statistics / Compute Feature Bounding Boxes mentions to MyST links; explained the 1-to-many cell-to-box mapping; stated bounds are in physical coordinate units; fixed 'columns'->'tuples'; added Required Input Sources. + +- [x] **ComputeVolumeFractionsFilter** (SimplnxCore) + - **Changes Made:** Reconciled the count-vs-volume-fraction wording (equal-volume cells make them identical); stated output is a per-Ensemble dimensionless fraction in [0,1] summing to 1; added Required Input Sources (Cell Phases); removed the empty Example Pipelines. + +- [x] **ComputeFeatureClusteringFilter** (SimplnxCore) + - **Changes Made:** Defined RDF (normalized histogram of inter-centroid distances) and Ensemble; added when/why (clustering/ordering detection, >1 vs <1 interpretation); stated distances are physical length units; added Required Input Sources (Compute Feature Centroids + Phases). + +- [x] **ComputeBoundaryElementFractionsFilter** (SimplnxCore) + - **Changes Made:** Defined a 'surface element' (one whose Surface Elements input value > 0); stated output is a [0,1] fraction (boundary/total per Feature); added Required Input Sources (Feature Ids + Surface Elements); removed the empty Example Pipelines. + +- [x] **ComputeEuclideanDistMapFilter** (SimplnxCore) + - **Changes Made:** Defined Feature boundary/GB, triple line/TJ, quadruple point/QP; stated the Manhattan output is an integer cell count and the Euclidean output is a physical float distance; added Required Input Sources (Feature Ids). + +- [x] **ComputeMomentInvariants2DFilter** (SimplnxCore) + - **Changes Made:** Added a plain-language definition of 2D moment invariants and what high/low Omega-1/Omega-2 indicate; stated Omega values dimensionless and Z Delta in cells; fixed typos (appllication/particales/'et. al'); fixed the missing newline before the citations; added Required Input Sources (Feature Ids + Feature Rect). + +- [x] **ComputeKMeansFilter** (SimplnxCore) + - **Changes Made:** Defined cluster/centroid/Voronoi tessellation/within-cluster variance; fixed the broken 'Ensemble Attribute Matrix' bold and typos (randomnes, tesselation); added MyST links to Compute K Medoids/DBSCAN/Silhouette and Required Input Sources. + +- [x] **ComputeKMedoidsFilter** (SimplnxCore) + - **Changes Made:** Defined cluster/Voronoi/topology (kept the good medoid definition); fixed the broken bold and typos (randomnes, arbirtary); added MyST links to Compute K Means/DBSCAN/Silhouette and Required Input Sources. + +- [x] **SilhouetteFilter** (SimplnxCore) + - **Changes Made:** Converted the Doxygen math delimiters to MyST $$/$ math; stated the output array location and dimensionless [-1,1] range; added MyST links to Compute K Means/K Medoids and Required Input Sources. + +- [x] **ApproximatePointCloudHullFilter** (SimplnxCore) + - **Changes Made:** Fixed typos (of/or, hve, To/The, 'is able of', 'faster that'); added Parameter Guidance stating grid resolution is in the point cloud's coordinate units and the empty-neighbor threshold is a 0-26 count; added Required Input Sources. + +- [x] **MapPointCloudToRegularGridFilter** (SimplnxCore) + - **Changes Made:** Added a downstream link to Interpolate Point Cloud to Regular Grid; stated Manual-mode dimensions are voxel counts; fixed the uint64-max off-by-one and the 'User may to trace' grammar; added Required Input Sources. + +- [x] **IterativeClosestPointFilter** (SimplnxCore) + - **Changes Made:** Fixed the all-'1.' list to 1-6 and the trailing-period heading; stated the output is a row-major flattened 4x4 transform (translation in coordinate units), reported always but applied only when the apply-transform option is on; cross-linked Apply Transformation to Geometry; added Required Input Sources (two Vertex Geometries). + +- [x] **IdentifyDuplicateVerticesFilter** (SimplnxCore) + - **Changes Made:** Defined 'duplicate' as all-three-coordinate equality within machine epsilon (no user tolerance); reworded the 'visual explanation' claim (the example is text); converted the italic RemoveFlaggedVertices to a MyST link; fixed the 'this filters output' apostrophe. + +- [x] **ComputeTriangleAreasFilter** (SimplnxCore) + - **Changes Made:** Defined Triangle Geometry; added when/why (mesh quality, statistic weighting); stated output area units (length^2); added Required Input Sources. + +- [x] **ComputeTriangleGeomCentroidsFilter** (SimplnxCore) + - **Changes Made:** Defined Feature/Face Labels ('owners')/nodes; stated centroid coordinate units; documented the -1 exterior-label edge case; added Required Input Sources (Triangle Geometry + Face Labels); removed the empty Example Pipelines. + +- [x] **ComputeTriangleGeomVolumesFilter** (SimplnxCore) + - **Changes Made:** Defined Feature/Face Labels/winding; added a watertight-requirement note; stated volume units (length^3); added Required Input Sources (closed Triangle Geometry + Face Labels); removed the empty Example Pipelines. + +- [x] **TriangleCentroidFilter** (SimplnxCore) + - **Changes Made:** Added when/why; stated centroid coordinate units; cross-linked the per-Feature Compute Feature Centroids from Triangle Geometry to disambiguate (this is per-triangle); added Required Input Sources. + +- [x] **TriangleNormalFilter** (SimplnxCore) + - **Changes Made:** Stated the output is a dimensionless unit 3-vector whose direction depends on winding; defined normal/cross-product/winding; fixed 'vertexes'->'vertices'; added Required Input Sources. + +- [x] **FeatureFaceCurvatureFilter** (SimplnxCore) + - **Changes Made:** Removed the stray @image latex Doxygen line; fixed the missing-space bold; replaced the Google-Groups mailing-list footer with the standard DREAM3D-NX Help footer; converted the bold Parameter-Notes filter mentions to a MyST-linked Required Input Sources list; defined curvature; stated units (principal/mean 1/length, Gaussian 1/length^2, directions dimensionless). + +- [x] **SharedFeatureFaceFilter** (SimplnxCore) + - **Changes Made:** Added a prose explanation of the Randomize Face IDs parameter (visualization-only ID permutation); defined Feature/Face Labels/Feature Attribute Matrix; added Required Input Sources (Triangle Geometry + Face Labels). + +- [x] **SurfaceNetsFilter** (SimplnxCore) + - **Changes Made:** Fixed typos (mush/equivelent/Traingle/FaceLables); converted the Verify Triangle Winding and QuickMesh mentions to MyST links; defined isosurface/marching cubes/triple line/winding; stated units (iterations dimensionless, max distance physical length); added Required Input Sources (Image Geometry + Feature Ids); fixed the non-standard footer. + +- [x] **LaplacianSmoothingFilter** (SimplnxCore) + - **Changes Made:** Fixed the corrupted ref [1] author and the malformed Belyaev URL; removed the dangling 'visit the tutorial' line; added alt text to the equation images; cross-linked Hierarchical Smoothing; stated Iteration Steps as a count and lambda/mu as dimensionless; added Required Input Sources (Triangle Geometry + Node Type). + +- [x] **UncertainRegularGridSampleSurfaceMeshFilter** (SimplnxCore) + - **Changes Made:** Defined Cells/rectilinear grid/conformal mesh/Feature; stated uncertainty and resolution/origin values are physical lengths; cross-linked the non-uncertain sibling; added Required Input Sources (Triangle Geometry + Face Labels). + +- [x] **ExtractInternalSurfacesFromTriangleGeometryFilter** (SimplnxCore) + - **Changes Made:** Fixed the two unclosed '**Vertex' bolds; replaced legacy 'Data Container' with 'data group'; added the missing DREAM3D-NX Help footer; cross-linked the Node Type producers (Surface Nets / Quick Surface Mesh); added Required Input Sources. + +- [x] **ReverseTriangleWindingFilter** (SimplnxCore) + - **Changes Made:** Defined 'winding' (vertex ordering that sets normal direction); cross-linked Verify Triangle Winding and Compute Triangle Normals; added Required Input Sources; removed the empty Example Pipelines. + +- [x] **VerifyTriangleWindingFilter** (SimplnxCore) + - **Changes Made:** Converted all bold/italic filter mentions to MyST links; defined 'winding' and 'negative volume'; fixed typos (Traingle/addtionally/preform/untounched/'difference n output'/Zero's/convience); reconciled the group to 'Surface Meshing (Connectivity/Arrangement)'; added Required Input Sources. + +- [x] **RemoveFlaggedEdgesFilter** (SimplnxCore) + - **Changes Made:** Defined Edge Geometry and 'mask'; fixed the group to 'Surface Meshing (Cleanup)'; added Required Input Sources (mask producer); fixed the footer /discussions link. + +- [x] **RemoveFlaggedTrianglesFilter** (SimplnxCore) + - **Changes Made:** Fixed the Vertices->Triangles copy-paste error; defined Triangle Geometry/Face Data/mask; fixed the group to 'Surface Meshing (Cleanup)'; added Required Input Sources; corrected the example-pipeline name. + +- [x] **CropVertexGeometryFilter** (SimplnxCore) + - **Changes Made:** Expanded the thin doc; stated Min/Max are physical coordinates (not cell indices) with inclusive bounds; replaced the stale 'DREAM3D Review (Cropping/Cutting)' group with 'Geometry (Cropping/Cutting)'; cross-linked Crop Edge/Image Geometry; added Required Input Sources and the missing footer. + +- [x] **CombineNodeBasedGeometriesFilter** (SimplnxCore) + - **Changes Made:** Defined node-based and higher/lower-order geometry; clarified vertex-index renumbering and that duplicate vertices are NOT merged; set the group to 'Core (Combining)'; added Required Input Sources. + +- [x] **PointSampleTriangleGeometryFilter** (SimplnxCore) + - **Changes Made:** Added descriptive alt text to the equation PNGs (corrected to the actual barycentric sqrt form); fixed 'beloning'; removed a stale sample-count table that no longer matches the parameter; added a random-sampling/seed note; fixed the stale 'DREAM3D Review (Geometry)' group to 'Sampling (Geometry)'; added Required Input Sources. + +- [x] **ExtractFeatureBoundaries2DFilter** (SimplnxCore) + - **Changes Made:** Defined Feature IDs/Image Geometry/Edge Geometry/overscan; fixed '.d3dpipline'->'.d3dpipeline'; replaced the stale subgroup with 'Surface Meshing (Generation)'; converted bold filter mentions to MyST links; added image alt text and Required Input Sources. + +- [x] **RobustAutomaticThresholdFilter** (SimplnxCore) + - **Changes Made:** Fixed the stale group to 'Threshold'; stated the robust/automatic rationale up front; defined gradient magnitude / 2-norm; replaced the suspect a_i*g_i/g_i equation with a prose weighted-average description; replaced the nonexistent 'Find Derivatives' reference with the real gradient-magnitude producer (ITK Gradient Magnitude Image Filter) as a MyST link and Required Input Sources. + +- [x] **ComputeVectorColorsFilter** (SimplnxCore) + - **Changes Made:** Expanded the description: input is a 3-component float32 vector Cell array, output is uint8 RGB (0-255), each vector is normalized (direction only); documented the mask/bad-voxel behavior; added Required Input Sources. + +### Tier 3 — Polish + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeArrayHistogram | SimplnxCore | Done | +| ComputeArrayHistogramByFeature | SimplnxCore | Done | +| ComputeDifferencesMap | SimplnxCore | Done | +| ComputeNumFeatures | SimplnxCore | Done | +| ComputeSurfaceAreaToVolume | SimplnxCore | Done | +| ComputeFeaturePhases | SimplnxCore | Done | +| ComputeFeaturePhasesBinary | SimplnxCore | Done | +| ComputeFeatureBounds | SimplnxCore | Done | +| ComputeFeatureCentroids | SimplnxCore | Done | +| ComputeFeatureRect | SimplnxCore | Done | +| ComputeLargestCrossSections | SimplnxCore | Done | +| ComputeCoordinateThreshold | SimplnxCore | Done | +| DBSCAN | SimplnxCore | Done | +| InterpolatePointCloudToRegularGrid | SimplnxCore | Done | +| ExtractVertexGeometry | SimplnxCore | Done | +| ComputeVertexToTriangleDistances | SimplnxCore | Done | +| LabelTriangleGeometry | SimplnxCore | Done | +| HierarchicalSmooth | SimplnxCore | Done | +| RegularGridSampleSurfaceMesh | SimplnxCore | Done | +| SliceTriangleGeometry | SimplnxCore | Done | +| RemoveFlaggedVertices | SimplnxCore | Done | +| CropEdgeGeometry | SimplnxCore | Done | +| CombineStlFiles | SimplnxCore | Done | +| MultiThresholdObjects | SimplnxCore | Done | +| CreateColorMap | SimplnxCore | Done | +| ChangeAngleRepresentation | SimplnxCore | Done | +| RandomizeFeatureIds | SimplnxCore | Done | +| ExecuteProcess | SimplnxCore | Done | +| CreatePythonSkeleton | SimplnxCore | Done | +| ExtractPipelineToFile | SimplnxCore | Done | +| CreateAMScanPaths | SimplnxCore | Done | + +- [x] **ComputeArrayHistogramFilter** (SimplnxCore) + - **Changes Made:** Trimmed the long raw 'Old Faithful' data dump; defined 'mode' on first use; stated bin bounds inherit the input array units; added Required Input Sources (None). + +- [x] **ComputeArrayHistogramByFeatureFilter** (SimplnxCore) + - **Changes Made:** Defined Feature/Feature Id; added Required Input Sources (Feature Ids producer); removed the empty Example Pipelines. + +- [x] **ComputeDifferencesMapFilter** (SimplnxCore) + - **Changes Made:** Stated the output inherits the input type/shape/location; added a brief Required Input Sources (None -- generic arrays); removed the empty Example Pipelines. + +- [x] **ComputeNumFeaturesFilter** (SimplnxCore) + - **Changes Made:** Defined Ensemble/phase; stated the output is a per-Ensemble count array; added Required Input Sources (Compute Feature Phases). + +- [x] **ComputeSurfaceAreaToVolumeFilter** (SimplnxCore) + - **Changes Made:** Defined 'aliasing'; stated the ratio units (1/length) and that sphericity is dimensionless; linked Compute Boundary Cells; added Required Input Sources (Feature Ids). + +- [x] **ComputeFeaturePhasesFilter** (SimplnxCore) + - **Changes Made:** Defined Feature/Ensemble/Element; stated the per-Feature phase output; added Required Input Sources (Feature Ids + Cell Phases). + +- [x] **ComputeFeaturePhasesBinaryFilter** (SimplnxCore) + - **Changes Made:** Added a generic non-materials framing; stated the boolean-mask input and binary Ensemble output; added Required Input Sources (Multi-Threshold Objects); removed the empty Example Pipelines. + +- [x] **ComputeFeatureBoundsFilter** (SimplnxCore) + - **Changes Made:** Stated bounds are physical coordinates (not cell indices); fixed the 'Dimesions' typo and the doubled ';;'; defined Feature/Cell; added Required Input Sources (Feature Ids). + +- [x] **ComputeFeatureCentroidsFilter** (SimplnxCore) + - **Changes Made:** Stated centroids are physical coordinates (3-component float32, not pixel indices); defined Feature/Cell; added Required Input Sources (Feature Ids). + +- [x] **ComputeFeatureRectFilter** (SimplnxCore) + - **Changes Made:** Fixed 'This values'->'These values'; clarified Pixel coords are zero-based voxel indices; cross-linked Compute Feature Bounding Boxes; added Required Input Sources. + +- [x] **ComputeLargestCrossSectionsFilter** (SimplnxCore) + - **Changes Made:** Stated the area is square physical units (cellCount x in-plane voxel area, confirmed from the cpp); described the per-feature float32 output; added Required Input Sources (Feature Ids). + +- [x] **ComputeCoordinateThresholdFilter** (SimplnxCore) + - **Changes Made:** Converted the prose Remove Flagged Vertices/Edges/Triangles mentions to MyST links; stated the rectangle min/max and sphere center/radius are physical coordinate units. + +- [x] **DBSCANFilter** (SimplnxCore) + - **Changes Made:** Converted eight bold/quoted inter-filter mentions to MyST links; fixed typos (sqaure_root, preforming/preform, 'vise versa'); added Required Input Sources. + +- [x] **InterpolatePointCloudToRegularGridFilter** (SimplnxCore) + - **Changes Made:** Converted the italic Map Point Cloud to Regular Grid to a MyST link; added Required Input Sources (Vertex Geometry producer). + +- [x] **ExtractVertexGeometryFilter** (SimplnxCore) + - **Changes Made:** Standardized the Rectilinear Grid / Vertex Geometry naming; added Required Input Sources. + +- [x] **ComputeVertexToTriangleDistancesFilter** (SimplnxCore) + - **Changes Made:** Fixed the 4x 'Geoemtry' typo; stated distance units (length unit); noted normals must be present/consistent for sign correctness; added Required Input Sources (Vertex + Triangle Geometry). + +- [x] **LabelTriangleGeometryFilter** (SimplnxCore) + - **Changes Made:** Added Required Input Sources with a note that STL is a common CAD mesh format; fixed the footer /discussions link. + +- [x] **HierarchicalSmoothFilter** (SimplnxCore) + - **Changes Made:** Removed the hand-written Parameters table (it duplicated the auto-table), replacing it with prose; added a MyST link to Laplacian Smoothing; added Required Input Sources; normalized the non-standard footer; removed the empty Example Pipelines. + +- [x] **RegularGridSampleSurfaceMeshFilter** (SimplnxCore) + - **Changes Made:** Stated Origin/Spacing physical units and Dimensions as voxel counts; cross-linked the Uncertain variant; added Required Input Sources (Triangle Geometry + Face Labels). + +- [x] **SliceTriangleGeometryFilter** (SimplnxCore) + - **Changes Made:** Fixed typos (geoemtry, bewteen, perimieter); stated Slice Spacing/range/area/perimeter are in the geometry's physical units; added Required Input Sources. + +- [x] **RemoveFlaggedVerticesFilter** (SimplnxCore) + - **Changes Made:** Replaced legacy 'Data Container' wording with NX terminology; added Required Input Sources (the boolean-mask producer). + +- [x] **CropEdgeGeometryFilter** (SimplnxCore) + - **Changes Made:** Added the missing Group header (Core (Conversion)); stated Min/Max are physical units, not indices; removed the empty Example Pipelines; cross-linked Crop Geometry (Image). + +- [x] **CombineStlFilesFilter** (SimplnxCore) + - **Changes Made:** Defined STL on first use; converted the bold Import/Write STL mentions to MyST links. + +- [x] **MultiThresholdObjectsFilter** (SimplnxCore) + - **Changes Made:** Defined Cell/Attribute Matrix/EBSD context; added Required Input Sources naming EBSD readers as typical producers; removed the empty Example Pipelines. + +- [x] **CreateColorMapFilter** (SimplnxCore) + - **Changes Made:** Added the missing Group header (Core (Image)); added Required Input Sources (scalar array + optional mask); noted the preset table is hand-maintained; removed the empty Example Pipelines; fixed the License line. + +- [x] **ChangeAngleRepresentationFilter** (SimplnxCore) + - **Changes Made:** Added a Required Input Sources one-liner naming EBSD readers as typical angle producers (units content already exemplary). + +- [x] **RandomizeFeatureIdsFilter** (SimplnxCore) + - **Changes Made:** Defined Feature Ids/Attribute Matrix/NeighborList; documented that the cpp exposes no seed parameter (not reproducible); added Required Input Sources; fixed the License line. + +- [x] **ExecuteProcessFilter** (SimplnxCore) + - **Changes Made:** Stated the absolute-path requirement; documented the Should Block / Timeout (ms) parameters; added an explicit Required Input Sources: None. + +- [x] **CreatePythonSkeletonFilter** (SimplnxCore) + - **Changes Made:** Removed the hand-written Configuration parameter list and ADDED the missing auto-table marker; added the missing Group header (Core (Generation)); added Required Input Sources: None. + +- [x] **ExtractPipelineToFileFilter** (SimplnxCore) + - **Changes Made:** Added the missing Group header (IO (Output)) and the missing DREAM3D-NX Help footer; noted the no-embedded-pipeline behavior; added Required Input Sources: None; fixed the License line. + +- [x] **CreateAMScanPathsFilter** (SimplnxCore) + - **Changes Made:** Added a Units section (Hatch Spacing/Length in geometry coordinate units, Hatch Rotation Angle in degrees per the cpp label); converted the quoted SliceTriangleGeometry to a MyST link and promoted it to Required Input Sources. + +### Tier 4 — Adequate + +| Filter | Plugin | Status | +|--------|--------|--------| +| ComputeFeatureSizes | SimplnxCore | Done | +| ComputeBoundaryCells | SimplnxCore | Done | +| ComputeGroupingDensity | SimplnxCore | Done | + +- [x] **ComputeFeatureSizesFilter** (SimplnxCore) + - **Changes Made:** Added Required Input Sources (Feature Ids from a segmentation filter). Otherwise adequate as triaged. + +- [x] **ComputeBoundaryCellsFilter** (SimplnxCore) + - **Changes Made:** Stated the output range 0-6 and volume-edge handling; added Required Input Sources (Feature Ids). Otherwise adequate. + +- [x] **ComputeGroupingDensityFilter** (SimplnxCore) + - **Changes Made:** Converted the quoted 'Compute Feature Neighborhoods' to a MyST link (and fixed the dangling quote); added Required Input Sources (Parent IDs, neighbor lists, Feature Volumes). Otherwise model-quality. + +--- + +## Real-World Visualization Wishlist + +These are pipeline-generated screenshots/visualizations that would enhance the documentation but require DREAM3DNX automation tooling (future work). + +| Filter | Desired Visualization | Priority | +|--------|----------------------|----------| +| ComputeAvgCAxes | IPF color map showing C-axis orientations per grain | Medium | +| ComputeCAxisLocations | C-axis direction map colored by orientation | Medium | +| ComputeGBCD | GBCD pole figure output from Write GBCD Pole Figure filter | High | +| ComputeSchmids | Microstructure colored by Schmid factor under a loading direction | High | +| ComputeKernelAvgMisorientations | KAM map showing orientation gradients within grains | High | +| ComputeAvgOrientations | IPF color map showing average orientation assignment per grain | Medium | +| ComputeFeatureReferenceMisorientations | Color scale legend for existing images; additional loading conditions | Low | +| ComputeShapes | Features colored by aspect ratio or Omega3 value | Medium | +| ComputeTwinBoundaries | Microstructure with twin boundaries highlighted and incoherence heat map | Medium | +| ComputeSlipTransmissionMetrics | Feature pairs with high vs low transmission metrics visualized | Medium | +| ComputeBoundaryStrengths | Boundary mesh colored by M' or fip values | Medium | +| AlignSectionsFeatureCentroid | Before/after comparison showing when centroid alignment is appropriate vs when it fails (e.g., sample with consistent vs inconsistent mask regions) | High | +| AlignSectionsMisorientation | Before/after slice alignment showing corrected vs uncorrected sections; side-by-side comparison of alignment with mask vs without mask showing when masking is needed (e.g., sample with mounting material or voids at edges) | High | +| AlignSectionsMutualInformation | Before/after alignment comparison; side-by-side with misorientation method | Medium | +| AlignSectionsList | Typical workflow showing shift output from another alignment filter used as input | Low | +| ITKNormalizeImage | Before/after images showing normalization effect with parameters used to generate result | High | +| ITKRescaleIntensityImage | Before/after images showing rescaling effect with parameters used to generate result | High | +| ScalarSegmentFeatures | Before/after FeatureIds map from a scalar-based segmentation (e.g., image-quality thresholding) | Medium | +| CAxisSegmentFeatures | Before/after segmentation on hexagonal (e.g., Ti) EBSD data | Medium | +| EBSDSegmentFeatures | EBSD IPF map → segmented grains visualization (flagship EBSD workflow) | High | +| MergeTwins | Before/after microstructure showing twin variants merged into parent grain | High | +| IdentifySample | Before/after showing overscan cleanup on a real FIB-SEM dataset | Low | +| RequireMinimumSizeFeatures | Before/after microstructure with minimum-size filter applied | Medium | +| RemoveFlaggedFeatures | Side-by-side comparison of Remove vs Extract vs Extract-then-Remove operation modes | Medium | +| ComputeFeatureNeighbors | Grain map colored by number of neighbors | Medium | +| AddBadData | Synthetic structure before and after random noise; same with boundary noise | High | +| FillBadData | Conceptual diagram: small defects (filled) vs large defects (preserved) at threshold | Medium | +| ErodeDilateBadData | Multi-frame iteration sequence diagram (iter 0 → 3) for both erode and dilate | High | +| ErodeDilateBadData | Erode-then-dilate ("opening") removing isolated single-cell noise but preserving a larger pore | Medium | +| ErodeDilateMask | Directional erosion (X-only vs uniform) on a mask | Medium | +| ErodeDilateCoordinationNumber | 3x3x3 cell cluster diagram with coordination numbers labeled (CN=6 isolated, CN=3 edge, etc.) | High | +| ReplaceElementAttributesWithNeighborValues | Conceptual diagram: flagged cell + neighbors with chosen replacement highlighted by max/min | Medium | +| NeighborOrientationCorrelation | Cell-with-6-neighbors diagram showing Cleanup Level=2,4,6 outcomes side by side | High | +| BadDataNeighborOrientationCheck | Voxel-and-neighbors diagram showing the false→true flip when criterion is met | Medium | +| RequireMinNumNeighbors | Microstructure before/after with isolated low-neighbor-count grains absorbed | Medium | +| ComputeNeighborhoods | Histogram of neighborhood counts for a real microstructure | Low | +| ComputeNeighborListStatistics | Example feature with its neighbor-misorientation list and computed statistics | Low | +| CreateGeometry | Side-by-side infographic of all 8 geometry types (Image, RectGrid, Vertex, Edge, Triangle, Quad, Tet, Hex) | High | +| CreateImageGeometry / SetImageGeomOriginScaling | Image Geometry dimensions/origin/spacing diagram (shared concept) | High | +| ApplyTransformationToGeometry | Axis-angle representation diagram | Medium | +| RotateSampleRefFrame | Sample frame rotation vs geometric rotation comparison | High | +| ResampleImageGeom | Before/after voxel grid showing 2x spacing reduction halving cell count | Medium | +| ResampleRectGridToImageGeom | Variable-spacing RectGrid → uniform Image Geom with "last one wins" cells highlighted | Medium | +| CropImageGeometry | Already adequate | - | +| PadImageGeometry | 3-panel diagram showing Update Origin ON vs OFF | Medium | +| AppendImageGeometry | Already comprehensive | - | +| QuickSurfaceMesh | Single voxel face → 2 triangles diagram | Low | +| PartitionGeometry | Already excellent | - | +| InitializeImageGeomCellData | Subvolume highlight before/after on real cube | Medium | +| CombineTransformationMatrices | Two 4x4 matrices multiplying into a single result | Low | +| ComputeCoordinatesImageGeom | Voxel grid with one cell highlighted showing (i,j,k) and (x,y,z) | Low | +| ReadImageStack | N 2D slices stacking into a 3D volume (Z = slice count) | Medium | +| ReadHDF5Dataset | Flat HDF5 dataset (N elements) reshaped into tuples x components | Medium | +| ReadStlFile | One triangle (normal + 3 vertices); many triangles forming a surface mesh | Low | +| ReadVtkStructuredPoints | Voxel cube showing cell-center value vs 8 corner (point) values | Medium | +| ReadH5Ebsd / ReadAng / ReadCtf | Sample vs crystal reference-frame diagram (why a rotation is needed); IPF map of freshly imported data | High | +| WriteAbaqusHexahedron | Image-geometry voxel grid mapping to a hexahedral element mesh (8 nodes per voxel) | Medium | +| WriteGBCDGMTFile | Data-flow: Compute GBCD -> Write GBCD GMT File -> .dat -> GMT -> rendered pole figure | High | +| WriteGBCDTriangleData | Boundary triangle: two grains, left/right average orientations, normal vector, area | Medium | +| WritePoleFigure | Stereographic/Lambert projection: 3D orientation/pole projected onto the 2D unit circle | High | +| WriteVtkRectilinearGrid / WriteVtkStructuredPoints | Rectilinear grid (variable spacing) vs structured points (uniform spacing) side by side | Medium | +| ReadDREAM3D | Import-data tree selector UI showing partial-import checkboxes | Medium | + +--- + +## Concept Pages Needed (Future Work) + +Domain concepts that appear across 3+ filters and should eventually become shared reference pages: + +| Concept | Filters That Need It | +|---------|---------------------| +| C-Axis / Hexagonal Crystals | ComputeAvgCAxes, ComputeCAxisLocations, ComputeFeatureNeighborCAxisMisalignments, ComputeFeatureReferenceCAxisMisorientations | +| Quaternions & Orientation Representations | ComputeAvgCAxes, ComputeAvgOrientations, ComputeCAxisLocations, ConvertOrientations | +| Misorientation | ComputeKernelAvgMisorientations, ComputeFeatureNeighborMisorientations, ComputeFeatureReferenceMisorientations, ComputeGBCD | +| Slip Systems & Crystal Plasticity | ComputeSchmids, ComputeSlipTransmissionMetrics, ComputeBoundaryStrengths | +| Grain Boundaries | ComputeGBCD, ComputeGBCDMetricBased, ComputeGBPDMetricBased, ComputeTwinBoundaries | +| Feature IDs & Grains | Nearly all filters | +| Reference Frames (Sample vs Crystal) | ComputeAvgCAxes, ComputeCAxisLocations, ComputeSchmids | +| Burn Algorithm / Segmentation | ScalarSegmentFeatures, CAxisSegmentFeatures, EBSDSegmentFeatures | +| Feature Cleanup / Isotropic Coarsening | RequireMinimumSizeFeatures, RemoveFlaggedFeatures | +| Cell vs Feature vs Ensemble Data | ScalarSegmentFeatures, RequireMinimumSizeFeatures, ComputeFeatureNeighbors, and most feature-level filters | +| Morphological Erosion / Dilation / Opening | ErodeDilateBadData, ErodeDilateMask, ErodeDilateCoordinationNumber | +| Coordination Number / Face Neighbors | ErodeDilateCoordinationNumber, NeighborOrientationCorrelation, BadDataNeighborOrientationCheck | +| Equivalent Sphere Diameter | ComputeFeatureSizes, ComputeNeighborhoods, ComputeShapes | +| Geometry Types (Image, RectGrid, Vertex, Edge, Triangle, Quad, Tet, Hex) | CreateGeometry, CreateImageGeometry, and every geometry-aware filter | +| Transformation Matrices (4x4 row-major) | ApplyTransformationToGeometry, CombineTransformationMatrices, RotateSampleRefFrame | +| Sample Reference Frame vs Crystal Reference Frame | RotateSampleRefFrame (already listed above) | +| HDF5 File Format (datasets, groups, tuples vs components) | ReadHDF5Dataset, ReadDREAM3D, WriteDREAM3D, ReadH5Ebsd, ReadH5Esprit, ReadH5Oim, ReadH5Oina, ReadGrainMapper3D | +| VTK Legacy Formats (structured points vs rectilinear grid; ASCII vs binary) | ReadVtkStructuredPoints, WriteVtkStructuredPoints, WriteVtkRectilinearGrid | +| EBSD Vendor File Formats & What They Contain (Euler angles, CI/IQ/MAD, phases) | ReadAngData, ReadCtfData, ReadChannel5Data, ReadH5Ebsd, ReadH5EspritData, ReadH5OimData, ReadH5OinaData | +| External Simulation Exporters (FEA / MD / KMC / FFT input files) | WriteAbaqusHexahedron, WriteLAMMPSFile, WriteSPParksSites, WriteLosAlamosFFT, ReadDeformKeyFileV12 | +| Pole Figures & Projections (stereographic, Lambert, Laue class) | WritePoleFigure, WriteGBCDGMTFile, ComputeGBCD | diff --git a/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_grains.d3dstate b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_grains.d3dstate new file mode 100644 index 0000000000..e5c0cfa1bb --- /dev/null +++ b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_grains.d3dstate @@ -0,0 +1,429 @@ +{ + "charting_state": { + "0": { + "active_chart_tab": 0, + "active_view": true, + "chart_type_selectors": [ + { + "chart_type": 0, + "chart_type_visible": false + } + ], + "num_chart_tabs": 0 + }, + "dream3d_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + }, + "pipeline_state": { + "isDisabled": false, + "name": "Untitled Pipeline", + "pinnedParams": [], + "pipeline": [ + { + "args": { + "import_data_object": { + "value": { + "data_paths": [], + "file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d", + "path_import_policy": 0 + }, + "version": 2 + }, + "parameters_version": 1 + }, + "comments": "", + "filter": { + "name": "nx::core::ReadDREAM3DFilter", + "uuid": "0dbd31c7-19e0-4077-83ef-f4a6459a0e2d" + }, + "isDisabled": false + } + ], + "pipeline_uuid": "4c120bda-d8be-4784-894a-9ec8cc5c41f4", + "version": 1, + "workflowParams": [] + }, + "quadview_state": { + "0": { + "active_quad_view_tab": 0, + "active_view": true, + "num_quad_view_tabs": 1, + "quad_view_tab_states": { + "0": { + "active_array": "", + "active_component": -1, + "ambient": 0.2, + "array_lut_fct": null, + "array_scalar_opacity_fct": null, + "color_map_inverted": false, + "diffuse": 0.8, + "geometry_path": "", + "gi_reach": 0.0, + "length_units": "mm", + "light_follows_camera": true, + "max_intensity_blend": true, + "mean_blend": false, + "min_intensity_blend": false, + "perPaneViewActionState": [ + {}, + {}, + {}, + {} + ], + "reslice_mode": false, + "shading_enabled": false, + "show_annotations": true, + "show_color_legend": true, + "show_plane_widgets": false, + "specular": 0.2, + "specular_power": 20.0, + "ssao_enabled": false, + "thick_mode": false, + "volume_blend_mode": 0, + "volumetric_scattering": 0.0 + } + } + }, + "quad_view_files": [ + "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + ] + }, + "spreadsheet_state": { + "0": { + "active_spreadsheet_tab": 0, + "active_view": true, + "num_spreadsheet_tabs": 0, + "spreadsheet_type_selectors": [ + { + "chart_type": 0, + "chart_type_visible": false + } + ] + }, + "dream3d_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + }, + "state_file_version": 4, + "visualization_state": { + "split_view_state": { + "cells": [ + [ + { + "col_span": 1, + "row_span": 1, + "widget_state": { + "active_view": true, + "block_render": false, + "camera_center_of_rotation_x": -23.625, + "camera_center_of_rotation_y": 25.125, + "camera_center_of_rotation_z": -0.5, + "camera_focal_pt_x": -26.353316907594433, + "camera_focal_pt_y": 22.547708844875523, + "camera_focal_pt_z": -0.5, + "camera_parallel_scale": 33.14477492067222, + "camera_pos_x": -26.353316907594433, + "camera_pos_y": 22.547708844875523, + "camera_pos_z": 160.75006004466653, + "camera_view_angle": 30.0, + "camera_view_up_x": 0.0, + "camera_view_up_y": 1.0, + "camera_view_up_z": 0.0, + "check_context_menu": false, + "global_grid_axes": false, + "global_grid_axes_color": [ + 1.0, + 1.0, + 1.0 + ], + "global_grid_axes_opacity": 1.0, + "global_grid_axes_show_grid_lines": false, + "global_grid_axes_show_labels": true, + "global_grid_axes_spacingx": 0.0, + "global_grid_axes_spacingy": 0.0, + "global_grid_axes_spacingz": 0.0, + "global_grid_axes_title_x": "", + "global_grid_axes_title_y": "", + "global_grid_axes_title_z": "", + "num_render_layers": 2, + "own_context_menu": true, + "parallel_projection": 1, + "split_view_index": 1 + } + } + ] + ], + "col_widths": [ + 1.0 + ], + "grid_cols": 1, + "grid_rows": 1, + "grid_version": 1, + "row_heights": [ + 1.0 + ] + }, + "tree_view_state": [ + { + "item_children": [ + { + "item_children": [ + { + "item_data": { + "core_object_name": "2D Image/Slice View", + "core_object_name_suffix": 1, + "rep_view_implementations": [ + { + "active_array": "FeatureIds", + "active_component": -1, + "animation_duration": 0.5, + "color_map_inverted": false, + "color_preset": { + "Annotations": null, + "ColorSpace": "RGB", + "Creator": "Francesca Samsel, and Alan W. Scott", + "DefaultMap": true, + "IndexedColors": [], + "License": "", + "Name": "Fast", + "NanColor": [ + 0.0, + 1.0, + 0.0 + ], + "RGBPoints": [ + 0.0, + 0.05640000104904175, + 0.05640000104904175, + 0.4699999988079071, + 0.17159223556518555, + 0.24300000071525574, + 0.46035000681877136, + 0.8100000023841858, + 0.2984914779663086, + 0.3568143844604492, + 0.7450246214866638, + 0.9543676972389221, + 0.4321287274360657, + 0.6881999969482422, + 0.9300000071525574, + 0.9179099798202515, + 0.5, + 0.8994959592819214, + 0.944646418094635, + 0.7686567306518555, + 0.5882260203361511, + 0.9571079611778259, + 0.8338184952735901, + 0.5089156031608582, + 0.7061412334442139, + 0.927520751953125, + 0.6214389204978943, + 0.3153570592403412, + 0.8476395010948181, + 0.800000011920929, + 0.35199999809265137, + 0.1599999964237213, + 1.0, + 0.5899999737739563, + 0.07670000195503235, + 0.11947499960660934 + ], + "Source": "" + }, + "custom_range_max": 370.0, + "custom_range_min": 0.0, + "data_grid_visible": false, + "detach_color_settings": true, + "generate_histogram_data": false, + "global_grid_axes_color": [ + 1.0, + 1.0, + 1.0 + ], + "global_grid_axes_opacity": 1.0, + "global_grid_axes_show_grid_lines": false, + "global_grid_axes_show_labels": true, + "global_grid_axes_spacingx": 0.0, + "global_grid_axes_spacingy": 0.0, + "global_grid_axes_spacingz": 0.0, + "global_grid_axes_title_x": "", + "global_grid_axes_title_y": "", + "global_grid_axes_title_z": "", + "indexed_color_preset": { + "Annotations": null, + "ColorSpace": "", + "Creator": "", + "DefaultMap": false, + "IndexedColors": [ + 0.6509804129600525, + 0.8078431487083435, + 0.8901960849761963, + 0.12156862765550613, + 0.47058823704719543, + 0.7058823704719543, + 0.6980392336845398, + 0.8745098114013672, + 0.5411764979362488, + 0.20000000298023224, + 0.6274510025978088, + 0.1725490242242813, + 0.9843137264251709, + 0.6039215922355652, + 0.6000000238418579, + 0.8901960849761963, + 0.10196078568696976, + 0.10980392247438431, + 0.9921568632125854, + 0.7490196228027344, + 0.43529412150382996, + 1.0, + 0.49803921580314636, + 0.0, + 0.7921568751335144, + 0.6980392336845398, + 0.8392156958580017, + 0.4156862795352936, + 0.239215686917305, + 0.6039215922355652, + 1.0, + 1.0, + 0.6000000238418579 + ], + "License": "", + "Name": "Brewer Qualitative Paired", + "NanColor": [ + 1.0, + 1.0, + 0.6000000238418579 + ], + "RGBPoints": [], + "Source": "" + }, + "link_physical_units": false, + "nan_color_b": 0.0, + "nan_color_g": 0.0, + "nan_color_r": 0.0, + "render_window_index": 1, + "rep_linked": false, + "rep_split_id": 1, + "representation_visible": true, + "scalar_bar_visible": false, + "scalar_mapping": 1, + "show_box_tool": false, + "slice_dir": 0, + "slice_num": 0, + "solid_color_b": 255, + "solid_color_g": 255, + "solid_color_r": 255, + "source_position2_x": 0.1, + "source_position2_y": 0.5, + "source_position_x": 0.9, + "source_position_y": 0.175, + "toggle_left_slice_num": 0, + "toggle_right_slice_num": 0, + "transform_box_rotate_x": 0.0, + "transform_box_rotate_y": 0.0, + "transform_box_rotate_z": 0.0, + "transform_box_scale_x": 1.0, + "transform_box_scale_y": 1.0, + "transform_box_scale_z": 1.0, + "transform_box_translate_x": 0.0, + "transform_box_translate_y": 0.0, + "transform_box_translate_z": 0.0, + "use_decimation_during_interactions": false, + "using_custom_range": false, + "using_default_indexed_preset": true, + "using_default_preset": false, + "using_solid_color": false, + "values_as_categories": false + } + ] + }, + "item_type": "VXImageSliceRep " + } + ], + "item_data": { + "core_object_name": "DataContainer", + "current_preset": { + "Annotations": null, + "ColorSpace": "RGB", + "Creator": "Francesca Samsel, and Alan W. Scott", + "DefaultMap": true, + "IndexedColors": [], + "License": "", + "Name": "Fast", + "NanColor": [ + 0.0, + 1.0, + 0.0 + ], + "RGBPoints": [ + 0.0, + 0.05640000104904175, + 0.05640000104904175, + 0.4699999988079071, + 0.17159223556518555, + 0.24300000071525574, + 0.46035000681877136, + 0.8100000023841858, + 0.2984914779663086, + 0.3568143844604492, + 0.7450246214866638, + 0.9543676972389221, + 0.4321287274360657, + 0.6881999969482422, + 0.9300000071525574, + 0.9179099798202515, + 0.5, + 0.8994959592819214, + 0.944646418094635, + 0.7686567306518555, + 0.5882260203361511, + 0.9571079611778259, + 0.8338184952735901, + 0.5089156031608582, + 0.7061412334442139, + 0.927520751953125, + 0.6214389204978943, + 0.3153570592403412, + 0.8476395010948181, + 0.800000011920929, + 0.35199999809265137, + 0.1599999964237213, + 1.0, + 0.5899999737739563, + 0.07670000195503235, + 0.11947499960660934 + ], + "Source": "" + }, + "data_source_color_map_inverted": false, + "data_source_nan_color_b": 0, + "data_source_nan_color_g": 191, + "data_source_nan_color_r": 128, + "data_source_solid_color_b": 255, + "data_source_solid_color_g": 255, + "data_source_solid_color_r": 255, + "data_source_using_default_preset": true, + "data_source_visibility": true, + "imported_data_path": "DataContainer", + "render_window_index": [ + { + "core_object_visibility": true, + "render_window_index": 1 + } + ] + }, + "item_type": "VXDataSource" + } + ], + "item_data": { + "bridge_object_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d", + "bridge_object_item_name": "Untitled Pipeline", + "bridge_object_uuid": "4c120bda-d8be-4784-894a-9ec8cc5c41f4" + }, + "item_type": "NXToVXBridge" + } + ] + }, + "window_state": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48UXRBZHZhbmNlZERvY2tpbmdTeXN0ZW0gVmVyc2lvbj0iMSIgVXNlclZlcnNpb249IjEiIENvbnRhaW5lcnM9IjEiPjxDb250YWluZXIgRmxvYXRpbmc9IjAiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0ifCIgQ291bnQ9IjEiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0iLSIgQ291bnQ9IjIiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0ifCIgQ291bnQ9IjIiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0iLSIgQ291bnQ9IjIiPjxBcmVhIFRhYnM9IjEiIEN1cnJlbnQ9Im1fUGlwZWxpbmVEb2NrIj48V2lkZ2V0IE5hbWU9Im1fUGlwZWxpbmVEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PEFyZWEgVGFicz0iMiIgQ3VycmVudD0ibV9Cb29rbWFya3NEb2NrIj48V2lkZ2V0IE5hbWU9Im1fRmlsdGVyTGlzdERvY2siIENsb3NlZD0iMSIvPjxXaWRnZXQgTmFtZT0ibV9Cb29rbWFya3NEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PFNpemVzPjAgMCA8L1NpemVzPjwvU3BsaXR0ZXI+PEFyZWEgVGFicz0iNCIgQ3VycmVudD0ibV9WaXN1YWxpemF0aW9uRG9jayI+PFdpZGdldCBOYW1lPSJtX0ZpbHRlclBhcmFtZXRlcnNEb2NrIiBDbG9zZWQ9IjEiLz48V2lkZ2V0IE5hbWU9Im1fV29ya2Zsb3dQYXJhbWV0ZXJzRG9jayIgQ2xvc2VkPSIxIi8+PFdpZGdldCBOYW1lPSJtX1Zpc3VhbGl6YXRpb25Eb2NrIiBDbG9zZWQ9IjAiLz48V2lkZ2V0IE5hbWU9Im1fQ2hhcnRpbmdEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PFNpemVzPjAgMTA5NCA8L1NpemVzPjwvU3BsaXR0ZXI+PFNwbGl0dGVyIE9yaWVudGF0aW9uPSJ8IiBDb3VudD0iMyI+PEFyZWEgVGFicz0iMSIgQ3VycmVudD0ibV9PdXRwdXREb2NrIj48V2lkZ2V0IE5hbWU9Im1fT3V0cHV0RG9jayIgQ2xvc2VkPSIxIi8+PC9BcmVhPjxBcmVhIFRhYnM9IjEiIEN1cnJlbnQ9Im1fSXNzdWVzRG9jayI+PFdpZGdldCBOYW1lPSJtX0lzc3Vlc0RvY2siIENsb3NlZD0iMSIvPjwvQXJlYT48QXJlYSBUYWJzPSIxIiBDdXJyZW50PSJtX1Bpbm5lZFBhcmFtZXRlcnNEb2NrIj48V2lkZ2V0IE5hbWU9Im1fUGlubmVkUGFyYW1ldGVyc0RvY2siIENsb3NlZD0iMSIvPjwvQXJlYT48U2l6ZXM+MCAwIDAgPC9TaXplcz48L1NwbGl0dGVyPjxTaXplcz43ODkgMCA8L1NpemVzPjwvU3BsaXR0ZXI+PFNpemVzPjEwOTQgPC9TaXplcz48L1NwbGl0dGVyPjwvQ29udGFpbmVyPjwvUXRBZHZhbmNlZERvY2tpbmdTeXN0ZW0+Cg==", + "workflow_mode": false +} \ No newline at end of file diff --git a/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_ipf.d3dstate b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_ipf.d3dstate new file mode 100644 index 0000000000..20791f17c3 --- /dev/null +++ b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_ipf.d3dstate @@ -0,0 +1,429 @@ +{ + "charting_state": { + "0": { + "active_chart_tab": 0, + "active_view": true, + "chart_type_selectors": [ + { + "chart_type": 0, + "chart_type_visible": false + } + ], + "num_chart_tabs": 0 + }, + "dream3d_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + }, + "pipeline_state": { + "isDisabled": false, + "name": "Untitled Pipeline", + "pinnedParams": [], + "pipeline": [ + { + "args": { + "import_data_object": { + "value": { + "data_paths": [], + "file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d", + "path_import_policy": 0 + }, + "version": 2 + }, + "parameters_version": 1 + }, + "comments": "", + "filter": { + "name": "nx::core::ReadDREAM3DFilter", + "uuid": "0dbd31c7-19e0-4077-83ef-f4a6459a0e2d" + }, + "isDisabled": false + } + ], + "pipeline_uuid": "4c120bda-d8be-4784-894a-9ec8cc5c41f4", + "version": 1, + "workflowParams": [] + }, + "quadview_state": { + "0": { + "active_quad_view_tab": 0, + "active_view": true, + "num_quad_view_tabs": 1, + "quad_view_tab_states": { + "0": { + "active_array": "", + "active_component": -1, + "ambient": 0.2, + "array_lut_fct": null, + "array_scalar_opacity_fct": null, + "color_map_inverted": false, + "diffuse": 0.8, + "geometry_path": "", + "gi_reach": 0.0, + "length_units": "mm", + "light_follows_camera": true, + "max_intensity_blend": true, + "mean_blend": false, + "min_intensity_blend": false, + "perPaneViewActionState": [ + {}, + {}, + {}, + {} + ], + "reslice_mode": false, + "shading_enabled": false, + "show_annotations": true, + "show_color_legend": true, + "show_plane_widgets": false, + "specular": 0.2, + "specular_power": 20.0, + "ssao_enabled": false, + "thick_mode": false, + "volume_blend_mode": 0, + "volumetric_scattering": 0.0 + } + } + }, + "quad_view_files": [ + "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + ] + }, + "spreadsheet_state": { + "0": { + "active_spreadsheet_tab": 0, + "active_view": true, + "num_spreadsheet_tabs": 0, + "spreadsheet_type_selectors": [ + { + "chart_type": 0, + "chart_type_visible": false + } + ] + }, + "dream3d_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d" + }, + "state_file_version": 4, + "visualization_state": { + "split_view_state": { + "cells": [ + [ + { + "col_span": 1, + "row_span": 1, + "widget_state": { + "active_view": true, + "block_render": false, + "camera_center_of_rotation_x": -23.625, + "camera_center_of_rotation_y": 25.125, + "camera_center_of_rotation_z": -0.5, + "camera_focal_pt_x": -26.353316907594433, + "camera_focal_pt_y": 22.547708844875523, + "camera_focal_pt_z": -0.5, + "camera_parallel_scale": 33.14477492067222, + "camera_pos_x": -26.353316907594433, + "camera_pos_y": 22.547708844875523, + "camera_pos_z": 160.75006004466653, + "camera_view_angle": 30.0, + "camera_view_up_x": 0.0, + "camera_view_up_y": 1.0, + "camera_view_up_z": 0.0, + "check_context_menu": false, + "global_grid_axes": false, + "global_grid_axes_color": [ + 1.0, + 1.0, + 1.0 + ], + "global_grid_axes_opacity": 1.0, + "global_grid_axes_show_grid_lines": false, + "global_grid_axes_show_labels": true, + "global_grid_axes_spacingx": 0.0, + "global_grid_axes_spacingy": 0.0, + "global_grid_axes_spacingz": 0.0, + "global_grid_axes_title_x": "", + "global_grid_axes_title_y": "", + "global_grid_axes_title_z": "", + "num_render_layers": 2, + "own_context_menu": true, + "parallel_projection": 1, + "split_view_index": 1 + } + } + ] + ], + "col_widths": [ + 1.0 + ], + "grid_cols": 1, + "grid_rows": 1, + "grid_version": 1, + "row_heights": [ + 1.0 + ] + }, + "tree_view_state": [ + { + "item_children": [ + { + "item_children": [ + { + "item_data": { + "core_object_name": "2D Image/Slice View", + "core_object_name_suffix": 1, + "rep_view_implementations": [ + { + "active_array": "IPFColors", + "active_component": -1, + "animation_duration": 0.5, + "color_map_inverted": false, + "color_preset": { + "Annotations": null, + "ColorSpace": "RGB", + "Creator": "Francesca Samsel, and Alan W. Scott", + "DefaultMap": true, + "IndexedColors": [], + "License": "", + "Name": "Fast", + "NanColor": [ + 0.0, + 1.0, + 0.0 + ], + "RGBPoints": [ + 0.0, + 0.05640000104904175, + 0.05640000104904175, + 0.4699999988079071, + 0.17159223556518555, + 0.24300000071525574, + 0.46035000681877136, + 0.8100000023841858, + 0.2984914779663086, + 0.3568143844604492, + 0.7450246214866638, + 0.9543676972389221, + 0.4321287274360657, + 0.6881999969482422, + 0.9300000071525574, + 0.9179099798202515, + 0.5, + 0.8994959592819214, + 0.944646418094635, + 0.7686567306518555, + 0.5882260203361511, + 0.9571079611778259, + 0.8338184952735901, + 0.5089156031608582, + 0.7061412334442139, + 0.927520751953125, + 0.6214389204978943, + 0.3153570592403412, + 0.8476395010948181, + 0.800000011920929, + 0.35199999809265137, + 0.1599999964237213, + 1.0, + 0.5899999737739563, + 0.07670000195503235, + 0.11947499960660934 + ], + "Source": "" + }, + "custom_range_max": 431.457, + "custom_range_min": 0.0, + "data_grid_visible": false, + "detach_color_settings": true, + "generate_histogram_data": false, + "global_grid_axes_color": [ + 1.0, + 1.0, + 1.0 + ], + "global_grid_axes_opacity": 1.0, + "global_grid_axes_show_grid_lines": false, + "global_grid_axes_show_labels": true, + "global_grid_axes_spacingx": 0.0, + "global_grid_axes_spacingy": 0.0, + "global_grid_axes_spacingz": 0.0, + "global_grid_axes_title_x": "", + "global_grid_axes_title_y": "", + "global_grid_axes_title_z": "", + "indexed_color_preset": { + "Annotations": null, + "ColorSpace": "", + "Creator": "", + "DefaultMap": false, + "IndexedColors": [ + 0.6509804129600525, + 0.8078431487083435, + 0.8901960849761963, + 0.12156862765550613, + 0.47058823704719543, + 0.7058823704719543, + 0.6980392336845398, + 0.8745098114013672, + 0.5411764979362488, + 0.20000000298023224, + 0.6274510025978088, + 0.1725490242242813, + 0.9843137264251709, + 0.6039215922355652, + 0.6000000238418579, + 0.8901960849761963, + 0.10196078568696976, + 0.10980392247438431, + 0.9921568632125854, + 0.7490196228027344, + 0.43529412150382996, + 1.0, + 0.49803921580314636, + 0.0, + 0.7921568751335144, + 0.6980392336845398, + 0.8392156958580017, + 0.4156862795352936, + 0.239215686917305, + 0.6039215922355652, + 1.0, + 1.0, + 0.6000000238418579 + ], + "License": "", + "Name": "Brewer Qualitative Paired", + "NanColor": [ + 1.0, + 1.0, + 0.6000000238418579 + ], + "RGBPoints": [], + "Source": "" + }, + "link_physical_units": false, + "nan_color_b": 0.0, + "nan_color_g": 0.0, + "nan_color_r": 0.0, + "render_window_index": 1, + "rep_linked": false, + "rep_split_id": 1, + "representation_visible": true, + "scalar_bar_visible": false, + "scalar_mapping": 1, + "show_box_tool": false, + "slice_dir": 0, + "slice_num": 0, + "solid_color_b": 255, + "solid_color_g": 255, + "solid_color_r": 255, + "source_position2_x": 0.1, + "source_position2_y": 0.5, + "source_position_x": 0.9, + "source_position_y": 0.175, + "toggle_left_slice_num": 0, + "toggle_right_slice_num": 0, + "transform_box_rotate_x": 0.0, + "transform_box_rotate_y": 0.0, + "transform_box_rotate_z": 0.0, + "transform_box_scale_x": 1.0, + "transform_box_scale_y": 1.0, + "transform_box_scale_z": 1.0, + "transform_box_translate_x": 0.0, + "transform_box_translate_y": 0.0, + "transform_box_translate_z": 0.0, + "use_decimation_during_interactions": false, + "using_custom_range": false, + "using_default_indexed_preset": true, + "using_default_preset": false, + "using_solid_color": false, + "values_as_categories": false + } + ] + }, + "item_type": "VXImageSliceRep " + } + ], + "item_data": { + "core_object_name": "DataContainer", + "current_preset": { + "Annotations": null, + "ColorSpace": "RGB", + "Creator": "Francesca Samsel, and Alan W. Scott", + "DefaultMap": true, + "IndexedColors": [], + "License": "", + "Name": "Fast", + "NanColor": [ + 0.0, + 1.0, + 0.0 + ], + "RGBPoints": [ + 0.0, + 0.05640000104904175, + 0.05640000104904175, + 0.4699999988079071, + 0.17159223556518555, + 0.24300000071525574, + 0.46035000681877136, + 0.8100000023841858, + 0.2984914779663086, + 0.3568143844604492, + 0.7450246214866638, + 0.9543676972389221, + 0.4321287274360657, + 0.6881999969482422, + 0.9300000071525574, + 0.9179099798202515, + 0.5, + 0.8994959592819214, + 0.944646418094635, + 0.7686567306518555, + 0.5882260203361511, + 0.9571079611778259, + 0.8338184952735901, + 0.5089156031608582, + 0.7061412334442139, + 0.927520751953125, + 0.6214389204978943, + 0.3153570592403412, + 0.8476395010948181, + 0.800000011920929, + 0.35199999809265137, + 0.1599999964237213, + 1.0, + 0.5899999737739563, + 0.07670000195503235, + 0.11947499960660934 + ], + "Source": "" + }, + "data_source_color_map_inverted": false, + "data_source_nan_color_b": 0, + "data_source_nan_color_g": 191, + "data_source_nan_color_r": 128, + "data_source_solid_color_b": 255, + "data_source_solid_color_g": 255, + "data_source_solid_color_r": 255, + "data_source_using_default_preset": true, + "data_source_visibility": true, + "imported_data_path": "DataContainer", + "render_window_index": [ + { + "core_object_visibility": true, + "render_window_index": 1 + } + ] + }, + "item_type": "VXDataSource" + } + ], + "item_data": { + "bridge_object_file_path": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d", + "bridge_object_item_name": "Untitled Pipeline", + "bridge_object_uuid": "4c120bda-d8be-4784-894a-9ec8cc5c41f4" + }, + "item_type": "NXToVXBridge" + } + ] + }, + "window_state": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48UXRBZHZhbmNlZERvY2tpbmdTeXN0ZW0gVmVyc2lvbj0iMSIgVXNlclZlcnNpb249IjEiIENvbnRhaW5lcnM9IjEiPjxDb250YWluZXIgRmxvYXRpbmc9IjAiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0ifCIgQ291bnQ9IjEiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0iLSIgQ291bnQ9IjIiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0ifCIgQ291bnQ9IjIiPjxTcGxpdHRlciBPcmllbnRhdGlvbj0iLSIgQ291bnQ9IjIiPjxBcmVhIFRhYnM9IjEiIEN1cnJlbnQ9Im1fUGlwZWxpbmVEb2NrIj48V2lkZ2V0IE5hbWU9Im1fUGlwZWxpbmVEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PEFyZWEgVGFicz0iMiIgQ3VycmVudD0ibV9Cb29rbWFya3NEb2NrIj48V2lkZ2V0IE5hbWU9Im1fRmlsdGVyTGlzdERvY2siIENsb3NlZD0iMSIvPjxXaWRnZXQgTmFtZT0ibV9Cb29rbWFya3NEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PFNpemVzPjAgMCA8L1NpemVzPjwvU3BsaXR0ZXI+PEFyZWEgVGFicz0iNCIgQ3VycmVudD0ibV9WaXN1YWxpemF0aW9uRG9jayI+PFdpZGdldCBOYW1lPSJtX0ZpbHRlclBhcmFtZXRlcnNEb2NrIiBDbG9zZWQ9IjEiLz48V2lkZ2V0IE5hbWU9Im1fV29ya2Zsb3dQYXJhbWV0ZXJzRG9jayIgQ2xvc2VkPSIxIi8+PFdpZGdldCBOYW1lPSJtX1Zpc3VhbGl6YXRpb25Eb2NrIiBDbG9zZWQ9IjAiLz48V2lkZ2V0IE5hbWU9Im1fQ2hhcnRpbmdEb2NrIiBDbG9zZWQ9IjEiLz48L0FyZWE+PFNpemVzPjAgMTA5NCA8L1NpemVzPjwvU3BsaXR0ZXI+PFNwbGl0dGVyIE9yaWVudGF0aW9uPSJ8IiBDb3VudD0iMyI+PEFyZWEgVGFicz0iMSIgQ3VycmVudD0ibV9PdXRwdXREb2NrIj48V2lkZ2V0IE5hbWU9Im1fT3V0cHV0RG9jayIgQ2xvc2VkPSIxIi8+PC9BcmVhPjxBcmVhIFRhYnM9IjEiIEN1cnJlbnQ9Im1fSXNzdWVzRG9jayI+PFdpZGdldCBOYW1lPSJtX0lzc3Vlc0RvY2siIENsb3NlZD0iMSIvPjwvQXJlYT48QXJlYSBUYWJzPSIxIiBDdXJyZW50PSJtX1Bpbm5lZFBhcmFtZXRlcnNEb2NrIj48V2lkZ2V0IE5hbWU9Im1fUGlubmVkUGFyYW1ldGVyc0RvY2siIENsb3NlZD0iMSIvPjwvQXJlYT48U2l6ZXM+MCAwIDAgPC9TaXplcz48L1NwbGl0dGVyPjxTaXplcz43ODkgMCA8L1NpemVzPjwvU3BsaXR0ZXI+PFNpemVzPjEwOTQgPC9TaXplcz48L1NwbGl0dGVyPjwvQ29udGFpbmVyPjwvUXRBZHZhbmNlZERvY2tpbmdTeXN0ZW0+Cg==", + "workflow_mode": false +} \ No newline at end of file diff --git a/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_pilot.d3dpipeline b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_pilot.d3dpipeline new file mode 100644 index 0000000000..d793376c55 --- /dev/null +++ b/docs/figure-generation/EBSDSegmentFeatures/ebsd_segment_pilot.d3dpipeline @@ -0,0 +1,130 @@ +{ + "isDisabled": false, + "name": "ebsd_segment_pilot.d3dpipeline", + "pinnedParams": [], + "pipeline": [ + { + "args": { + "cell_attribute_matrix_name": { "value": "Cell Data", "version": 1 }, + "cell_ensemble_attribute_matrix_name": { "value": "Cell Ensemble Data", "version": 1 }, + "input_file": { "value": "/Users/mjackson/Workspace1/DREAM3D_Data/Data/SmallIN100/Slice_1.ang", "version": 1 }, + "output_image_geometry_path": { "value": "DataContainer", "version": 1 }, + "parameters_version": 1 + }, + "comments": "Read single EDAX .ang slice -> DataContainer", + "filter": { "name": "nx::core::ReadAngDataFilter", "uuid": "5b062816-79ac-47ce-93cb-e7966896bcbd" }, + "isDisabled": false + }, + { + "args": { + "euler_angles_array_path": { "value": "DataContainer/Cell Data/EulerAngles", "version": 1 }, + "parameters_version": 1, + "rotation_axis_angle": { "value": [0.0, 0.0, 1.0, 90.0], "version": 1 } + }, + "comments": "Rotate Euler reference frame for EDAX convention", + "filter": { "name": "nx::core::RotateEulerRefFrameFilter", "uuid": "0458edcd-3655-4465-adc8-b036d76138b5" }, + "isDisabled": false + }, + { + "args": { + "input_image_geometry_path": { "value": "DataContainer", "version": 1 }, + "keep_input_geometry_origin": { "value": false, "version": 1 }, + "output_image_geometry_path": { "value": "DataContainer", "version": 1 }, + "parameters_version": 1, + "remove_original_geometry": { "value": true, "version": 1 }, + "rotate_slice_by_slice": { "value": false, "version": 1 }, + "rotation_axis_angle": { "value": [0.0, 1.0, 0.0, 180.0], "version": 1 }, + "rotation_matrix": { "value": [[0.0,0.0,0.0],[0.0,0.0,0.0],[0.0,0.0,0.0]], "version": 1 }, + "rotation_representation_index": { "value": 0, "version": 1 } + }, + "comments": "Rotate sample reference frame for EDAX convention", + "filter": { "name": "nx::core::RotateSampleRefFrameFilter", "uuid": "d2451dc1-a5a1-4ac2-a64d-7991669dcffc" }, + "isDisabled": false + }, + { + "args": { + "array_thresholds_object": { + "value": { + "inverted": false, + "thresholds": [ + { "array_path": "DataContainer/Cell Data/Confidence Index", "comparison": 0, "component_index": 0, "inverted": false, "type": "array", "union": 0, "value": 0.1 } + ], + "type": "collection", + "union": 0 + }, + "version": 2 + }, + "created_mask_type": { "value": 10, "version": 1 }, + "custom_false_value": { "value": 0.0, "version": 1 }, + "custom_true_value": { "value": 1.0, "version": 1 }, + "output_data_array_name": { "value": "Mask", "version": 1 }, + "parameters_version": 1, + "use_custom_false_value": { "value": false, "version": 1 }, + "use_custom_true_value": { "value": false, "version": 1 } + }, + "comments": "Build Mask from Confidence Index >= 0.1", + "filter": { "name": "nx::core::MultiThresholdObjectsFilter", "uuid": "4246245e-1011-4add-8436-0af6bed19228" }, + "isDisabled": false + }, + { + "args": { + "input_orientation_array_path": { "value": "DataContainer/Cell Data/EulerAngles", "version": 1 }, + "input_representation_index": { "value": 0, "version": 1 }, + "output_orientation_array_name": { "value": "Quats", "version": 1 }, + "output_representation_index": { "value": 2, "version": 1 }, + "parameters_version": 1 + }, + "comments": "Convert Euler angles -> Quaternions (needed by Segment Features)", + "filter": { "name": "nx::core::ConvertOrientationsFilter", "uuid": "501e54e6-a66f-4eeb-ae37-00e649c00d4b" }, + "isDisabled": false + }, + { + "args": { + "cell_euler_angles_array_path": { "value": "DataContainer/Cell Data/EulerAngles", "version": 1 }, + "cell_ipf_colors_array_name": { "value": "IPFColors", "version": 1 }, + "cell_phases_array_path": { "value": "DataContainer/Cell Data/Phases", "version": 1 }, + "crystal_structures_array_path": { "value": "DataContainer/Cell Ensemble Data/CrystalStructures", "version": 1 }, + "mask_array_path": { "value": "DataContainer/Cell Data/Mask", "version": 1 }, + "parameters_version": 1, + "reference_dir": { "value": [0.0, 0.0, 1.0], "version": 1 }, + "use_mask": { "value": true, "version": 1 } + }, + "comments": "Compute IPF colors -> IPFColors (the BEFORE coloring)", + "filter": { "name": "nx::core::ComputeIPFColorsFilter", "uuid": "64cb4f27-6e5e-4dd2-8a03-0c448cb8f5e6" }, + "isDisabled": false + }, + { + "args": { + "active_array_name": { "value": "Active", "version": 1 }, + "cell_feature_attribute_matrix_name": { "value": "Cell Feature Data", "version": 1 }, + "cell_mask_array_path": { "value": "DataContainer/Cell Data/Mask", "version": 1 }, + "cell_phases_array_path": { "value": "DataContainer/Cell Data/Phases", "version": 1 }, + "cell_quats_array_path": { "value": "DataContainer/Cell Data/Quats", "version": 1 }, + "crystal_structures_array_path": { "value": "DataContainer/Cell Ensemble Data/CrystalStructures", "version": 1 }, + "feature_ids_array_name": { "value": "FeatureIds", "version": 1 }, + "input_image_geometry_path": { "value": "DataContainer", "version": 1 }, + "is_periodic": { "value": false, "version": 1 }, + "misorientation_tolerance": { "value": 5.0, "version": 1 }, + "neighbor_scheme_index": { "value": 0, "version": 1 }, + "parameters_version": 2, + "randomize_features": { "value": true, "version": 1 }, + "use_mask": { "value": true, "version": 1 } + }, + "comments": "Segment Features (Misorientation) -> FeatureIds (the AFTER coloring). randomize_features=true for visually distinct grain colors.", + "filter": { "name": "nx::core::EBSDSegmentFeaturesFilter", "uuid": "1810c2c7-63e3-41db-b204-a5821e6271c0" }, + "isDisabled": false + }, + { + "args": { + "export_file_path": { "value": "/Users/mjackson/Workspace1/DREAM3D-Build/NX-Com-Qt69-Vtk95-Rel/Bin/Data/Output/DocFigures/ebsd_segment_pilot.dream3d", "version": 1 }, + "parameters_version": 1, + "write_xdmf_file": { "value": false, "version": 1 } + }, + "comments": "Write everything to a regenerable .dream3d (not committed)", + "filter": { "name": "nx::core::WriteDREAM3DFilter", "uuid": "b3a95784-2ced-41ec-8d3d-0242ac130003" }, + "isDisabled": false + } + ], + "version": 1, + "workflowParams": [] +} diff --git a/docs/filter-figure-style.md b/docs/filter-figure-style.md new file mode 100644 index 0000000000..bd847b5d7b --- /dev/null +++ b/docs/filter-figure-style.md @@ -0,0 +1,109 @@ +# Filter Documentation Figure Style Guide + +Visual style and file conventions for figures generated to support filter documentation. Established during the documentation review project (batches 1+) so that figures across plugins look consistent. Reference palette: `docs/style_palette_final.svg` in this repo. + +## When to Add a Figure + +**Add a figure when:** + +- The filter operates on spatial data and the spatial relationship matters (kernels, neighborhoods, alignment, neighbor counts). +- The filter has a multi-step algorithm that benefits from a flowchart or sequence diagram. +- The filter transforms data in a way easier to show than describe (orientation conversions, geometry operations). +- The filter has parameters whose effect is non-obvious (kernel radius, dilation iterations, coordination number). + +**Skip a figure when:** + +- The filter performs a simple mathematical operation (radians-to-degrees, threshold). +- The filter is a basic I/O operation (read file, write file). +- The filter's behavior is fully captured by its parameter names (delete data, rename data). + +## Font + +``` +'Segoe UI', 'Helvetica Neue', Arial, sans-serif +``` + +| Element | Size | Weight | Color | +|---------|------|--------|-------| +| Figure title | 17-18px | Bold (700) | #2C3E50 | +| Section heading | 14px | Semibold (600) | #2C3E50 | +| Body text | 13px | Regular (400) | #555555 | +| Captions / notes | 11px | Italic | #888888 | + +## Color Palette + +### Primary (Diagram Elements) + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Focus | Dark Blue | #2874A6 | Center cell, primary element, section headers | +| Active | Light Blue | #AED6F1 | Kernel neighbors, included elements | +| Inactive | Light Gray | #E8ECF0 | Outside kernel, excluded elements | + +### Semantic Accents + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Danger / Warning | Red | #E74C3C | Thread-safety warnings, invalid approaches, common mistakes | +| Good / Correct | Green | #27AE60 | Recommended approaches, valid results, correct measurements | +| Annotation | Purple | #8E44AD | Brackets, dimensions, labels, measurements | +| Tip / Highlight | Amber | #E67E22 | Tips, parameters of interest, optional recommendations | + +### Supporting + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Primary text | Dark Slate | #2C3E50 | Headings, primary labels | +| Secondary text | Medium Gray | #5D6D7E | Secondary labels, descriptions | +| Card background | White | #FFFFFF | Figure card background | +| Formula background | Pale Blue | #EBF5FB | Formula / equation highlight boxes | +| Warning background | Pale Red | #FDEDEC | Warning callout box fill | +| Success background | Pale Green | #EAFAF1 | Success callout box fill | +| Annotation background | Pale Purple | #F4ECF7 | Note callout box fill | +| Tip background | Pale Amber | #FEF5E7 | Tip callout box fill | +| Page background | Off-white | #F0F2F5 | Outer page fill (when used) | + +## Callout Boxes + +Four semantic callout box types are available: + +- **Warning (Red)** — `!` icon, #FDEDEC background, #E74C3C border. For dangers and things to watch out for. +- **Good / Correct (Green)** — checkmark icon, #EAFAF1 background, #27AE60 border. For recommended approaches. +- **Note (Purple)** — `i` icon, #F4ECF7 background, #8E44AD border. For general annotations and clarifications. +- **Tip (Amber)** — star icon, #FEF5E7 background, #E67E22 border. For tips and highlights. + +## Section Headers + +Colored bars with white text, using the semantic color that best fits the section content. Default to blue (#2874A6) for neutral sections. + +## File Format and Naming + +- **Author as SVG.** Hand-write or generate the source. +- **Convert to PNG at 2x resolution** using `rsvg-convert -z 2 source.svg -o source.png`. The 2x scale provides a clean appearance on high-DPI displays. +- **Keep both SVG and PNG** in the plugin's `/docs/Images/` directory (e.g., `src/Plugins/OrientationAnalysis/docs/Images/`). +- **Reference the PNG** in the filter documentation markdown, not the SVG. +- **Naming convention:** `_.png`. Examples: + - `ComputeKernelAvgMisorientations_1D_Radius1.png` + - `ComputeAvgCAxes_HexagonalCAxis.png` + - `ComputeSchmids_SchmidFactor.png` + +## Markdown Reference Pattern + +Use the figure caption as the alt text and as a short Fig. N descriptor: + +```markdown +![Fig. 1: The geometric relationship between the tensile axis, slip plane, and slip direction that defines the Schmid factor.](Images/ComputeSchmids_SchmidFactor.png) +``` + +For paired before/after figures, use a 2-column table: + +```markdown +| Before | After | +|----------------------------------|----------------------------------| +| ![](Images/ExampleFilter_1.png) | ![](Images/ExampleFilter_2.png) | +``` + +## Reference SVGs + +- `docs/style_palette_final.svg` — canonical color palette, font, and callout box styles. Open in any SVG viewer to copy colors. +- Existing finished figures in `src/Plugins/OrientationAnalysis/docs/Images/` (especially `ComputeKernelAvgMisorientations_*.svg` and `ComputeAvgCAxes_HexagonalCAxis.svg`) are good reference templates to fork from. diff --git a/docs/style_palette_final.svg b/docs/style_palette_final.svg new file mode 100644 index 0000000000..877e1680cb --- /dev/null +++ b/docs/style_palette_final.svg @@ -0,0 +1,257 @@ + + + + + + + + + + + + + + + + + + DREAM3DNX Figure Style Guide + Option A Refined: Ocean Blues + Semantic Accents + + + + + + + + Color Palette + + + Primary (Focus / Active / Inactive) + + + Focus + #2874A6 + + + Active + #AED6F1 + + + Inactive + #E8ECF0 + + + + Semantic Accents + + + Danger + #E74C3C + + + Good + #27AE60 + + + Annotation + #8E44AD + + + + Supporting + + + Text + #2C3E50 + + + Secondary Text + #5D6D7E + + + Highlight + #E67E22 + + + Backgrounds + + + Card BG + #FFFFFF + + + Formula BG + #EBF5FB + + + Page BG + #F0F2F5 + + + Warning BG + #FDEDEC + + + Success BG + #EAFAF1 + + + + + + + + + Typography + + Figure Title — 17-18px Bold + Section Heading — 14px Semibold + Body text and descriptions — 13px Regular, color #555 + Captions and notes — 11px Italic, color #888 + + Font Stack: + 'Segoe UI', 'Helvetica Neue', Arial, sans-serif + Cross-platform sans-serif with consistent rendering. + + + + + + + + Demo: Conceptual Diagram (Kernel Radius = 1) + + + + + ... + + + + + -1 + + + + Center + + + + +1 + + + + + ... + + + + + + R = 1 + + + + + R = 1 + + + + + + Kernel Size = 3 cells + + + + + + Focus / Center + + Active neighbor + + Outside kernel + + Annotation + + Good / Correct + + Warning / Danger + + + + + + + + + Demo: Semantic Callout Boxes + + + + + ! + Warning / Danger + DataArray is NOT thread-safe for concurrent access. + Writing to different indices from multiple threads may fail. + + + + + ✓ + Good / Correct + Use getDataRefAs<T>() when the parameter has + already validated that the object exists. + + + + + i + Note / Annotation + All Cells in the kernel are weighted equally during + averaging, though they are not equidistant from center. + + + + + ★ + Tip / Highlight + Setting Z Radius to 0 restricts the kernel to a + single 2D slice — useful for thin-section data. + + + + + + + + Demo: Formula Box + + + Kernel Size = (2 × Radius) + 1 + + + + + + + + Usage Rules + + + + Blue — Default for all primary diagram elements (focus, active, borders, headers) + + + Purple — General annotations: brackets, dimensions, labels, measurements + + + Green — Positive semantics: correct approach, recommended, valid result + + + Red — Negative semantics: danger, thread-safety warning, common mistake, invalid + + + Amber — Tips, highlights, parameters of interest, optional but recommended + + \ No newline at end of file diff --git a/docs/superpowers/specs/2026-04-12-documentation-review-design.md b/docs/superpowers/specs/2026-04-12-documentation-review-design.md new file mode 100644 index 0000000000..cb5aea99d2 --- /dev/null +++ b/docs/superpowers/specs/2026-04-12-documentation-review-design.md @@ -0,0 +1,327 @@ +# DREAM3DNX Filter Documentation Review — Design Spec + +**Date:** 2026-04-12 +**Scope:** ~295 filter documentation files across SimplnxCore (154), OrientationAnalysis (53), and ITKImageProcessing (88) +**Branch:** Single PR when all batches are complete + +--- + +## 1. Goals + +### Primary Goals + +1. **Clarity for non-domain-experts** — Documentation should be understandable by a general engineer or scientist (audience B) who understands data processing concepts but may not know EBSD, crystallography, or microstructure terminology. +2. **Accessibility for non-native English speakers** — Straightforward language, short sentences, consistent terminology. Avoid idioms and ambiguous phrasing. +3. **Figures where they help** — Add conceptual diagrams for filters where visual explanation meaningfully aids understanding. Not every filter needs a figure (e.g., unit conversion filters don't). +4. **Parameter guidance** — Help users determine if a filter is appropriate for their use case and what parameter values to use. + +### Non-Goals (Future Work) + +- **Documentation architecture consolidation** — The existing concept docs are scattered across `wrapping/python/docs/source/`, `DREAM3DNX/Documentation/Sphinx/source/Concepts/`, and `Downloads/dream3d_infographics/`. Consolidating these into a single canonical location is a future task, not part of this review. +- **Sphinx format migration** — Current filter docs are Markdown. Converting to RST or standardizing format is a future task. +- **Real-world pipeline visualizations** — Pipeline-generated screenshots require DREAM3DNX automation tooling that is still in progress. This review will build a wishlist of desired visualizations, but generating them is a future task. + +--- + +## 2. Target Audience + +**Audience (B): General engineer/scientist** + +- Understands data processing, arrays, filtering, statistics concepts +- May know something about EBSD or have data they want to process +- Looks to DREAM3D to help with processing and needs help figuring out if a filter is appropriate +- May not know crystallography, quaternions, Euler angles, microstructure terminology +- English may not be their primary language + +The documentation should serve both this audience AND domain experts. Domain experts need parameter guidance and edge case documentation; non-experts need conceptual explanations of what the filter does and when to use it. + +--- + +## 3. Review Process + +### Phase 1: Triage Pass + +Claude autonomously reviews all ~295 filter docs and produces a tracker document (`docs/documentation_review_tracker.md`) that categorizes every filter into a priority tier. + +**Triage Rubric — 5 Dimensions:** + +| Dimension | What We're Assessing | +|-----------|---------------------| +| **Clarity** | Can audience (B) understand what the filter does and when to use it? | +| **Completeness** | Are all parameters explained? Are edge cases/caveats documented? | +| **Accessibility** | Is the language straightforward? Are domain terms explained or defined on first use? | +| **Figures Needed** | Would a conceptual diagram meaningfully help understanding? | +| **Real-World Viz** | Would a pipeline-generated screenshot/visualization add value? (wishlist only) | +| **Units Clarity** | Are all numeric parameters (sizes, distances, radii, tolerances, offsets) documented with explicit units (cells/voxels, degrees, physical units, dimensionless)? | + +Additionally, track: +- **Concept Links** — Domain concepts that should link to shared concept pages (e.g., Quaternions, Feature IDs, Image Geometry). When the same concept appears across 3+ filters, that signals a future shared concept page. + +**Priority Tiers:** + +| Tier | Description | Expected Action | +|------|-------------|-----------------| +| **Tier 1 (Critical)** | Domain-heavy filters with sparse or expert-only docs. Non-expert cannot understand what the filter does. | Major rewrite: add conceptual explanation, define terms, add figures | +| **Tier 2 (Important)** | Docs are functional but assume too much domain knowledge, or would clearly benefit from figures. | Moderate rewrite: add context, simplify language, generate figures | +| **Tier 3 (Polish)** | Docs are mostly clear but could benefit from minor language cleanup, consistency, or term definitions. | Light editing: clarify wording, add term definitions inline | +| **Tier 4 (Adequate)** | Docs are already clear, complete, and accessible. Simple utility/I/O filters that don't need more. | No action needed | + +### Phase 2: Batched Rewrites + +After triage, work through filters in batches grouped by functional category (e.g., all alignment filters, all orientation statistics filters). Working by category ensures: + +- Consistent explanations across related filters +- Shared domain concepts identified naturally +- Cross-references between related filters + +**Batch workflow:** + +1. Claude rewrites the batch of filter docs +2. Claude generates any needed conceptual figures (following the style guide) +3. User reviews the changes +4. User commits the batch when satisfied +5. Move to next batch + +All batches accumulate on one branch and are submitted as a single PR when complete. + +### Phase 3: Future Work + +- Consolidate shared concept pages into a canonical location within this repo +- Generate real-world pipeline visualizations using DREAM3DNX automation +- Consider RST migration for consistency with Sphinx build + +--- + +## 4. Tracker Document Format + +The tracker (`docs/documentation_review_tracker.md`) uses a two-level structure: + +**Level 1: Summary tables** — One table per priority tier for quick scanning. + +```markdown +## Tier 1: Critical + +| Filter | Plugin | Category | +|--------|--------|----------| +| ComputeAvgOrientations | OrientationAnalysis | Statistics | +| ConvertOrientations | OrientationAnalysis | Conversion | +``` + +**Level 2: Detailed checklists** — Below the summary tables, a checklist with full details for each filter, organized by tier. + +```markdown +### Tier 1 — Detailed Checklist + +- [ ] **ComputeAvgOrientations** (OrientationAnalysis) + - **Clarity:** Assumes deep quaternion knowledge; no intuitive explanation + - **Figures Needed:** Diagram showing orientations being averaged within a grain + - **Real-World Viz:** IPF color map showing average orientation assignment + - **Concept Links:** Quaternions, Symmetry Operators, Feature/Grain + - **Notes:** Only 36 lines; needs significant expansion + +- [ ] **ConvertOrientations** (OrientationAnalysis) + - **Clarity:** Lists 8 types but doesn't explain when to choose each + - **Figures Needed:** Visual comparison of orientation representations + - **Real-World Viz:** None + - **Concept Links:** Euler Angles, Quaternions, Rodrigues Vectors + - **Notes:** 113 lines but very dense; needs "which should I use?" guidance +``` + +Filters are checked off as their rewrites are completed and committed. + +--- + +## 5. Documentation Rewrite Guidelines + +### Structure for Each Filter Doc + +Every filter doc should follow this structure (scaled to the filter's complexity): + +1. **Title** — Filter name +2. **Group (Subgroup)** — Category classification +3. **Description** — What the filter does in plain language. Lead with the "what" and "when would I use this?" before diving into algorithm details. If domain terms are needed, define them on first use or link to a concept page. +4. **Algorithm Details** (if applicable) — How it works, with figures where they help +5. **Parameter Guidance** (if applicable) — What the parameters mean, what values are typical, how they affect results +6. **Figures** — Conceptual diagrams embedded as PNG images +7. **Auto-generated parameter table** — `% Auto generated parameter table will be inserted here` +8. **Example Pipelines** — Links to relevant pipelines +9. **License & Copyright** +10. **DREAM3D-NX Help** — Link to discussions + +### Writing Style + +- **Short sentences.** Prefer active voice. +- **Define domain terms on first use.** Example: "the misorientation (the angular difference between two crystal orientations)" +- **Lead with purpose.** Start with what the filter does and why someone would use it, not how it works internally. +- **Use "you" sparingly.** Prefer "the filter" or "this operation" for international clarity. +- **Avoid idioms and colloquialisms.** Write for translation-friendliness. +- **Be specific about parameters.** Don't just name them — explain what values are typical and how changing them affects results. +- **Always specify units for numeric parameters.** Any parameter that accepts a size, distance, radius, offset, tolerance, or similar numeric value must clearly state whether the value is in **cell/voxel units** (integer cell counts), **physical units** (micrometers, degrees, etc.), or **dimensionless** (e.g., a direction vector). This is critical for users who may not know whether a "radius of 3" means 3 cells or 3 micrometers. + +### Figure Decision Framework + +**Add a figure when:** +- The filter operates on spatial data and the spatial relationship matters (kernels, neighborhoods, alignment) +- The filter has a multi-step algorithm that benefits from a flowchart or step diagram +- The filter transforms data in a way that's easier to show than describe (orientation conversions, geometry operations) +- The filter has parameters whose effect is non-obvious (kernel radius, dilation distance) + +**Skip a figure when:** +- The filter performs a simple mathematical operation (radians to degrees, threshold) +- The filter is a basic I/O operation (read file, write file) +- The filter's behavior is fully captured by its parameter names (delete data, rename data) + +--- + +## 6. Figure Style Guide + +All generated figures follow a consistent visual style. The style guide is saved as `docs/style_palette_final.svg` for reference. + +### Font + +``` +'Segoe UI', 'Helvetica Neue', Arial, sans-serif +``` + +| Element | Size | Weight | Color | +|---------|------|--------|-------| +| Figure title | 17-18px | Bold (700) | #2C3E50 | +| Section heading | 14px | Semibold (600) | #2C3E50 | +| Body text | 13px | Regular (400) | #555555 | +| Captions/notes | 11px | Italic | #888888 | + +### Color Palette + +**Primary (Diagram Elements):** + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Focus | Dark Blue | #2874A6 | Center cell, primary element, section headers | +| Active | Light Blue | #AED6F1 | Kernel neighbors, included elements | +| Inactive | Light Gray | #E8ECF0 | Outside kernel, excluded elements | + +**Semantic Accents:** + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Danger/Warning | Red | #E74C3C | Thread-safety warnings, invalid approaches, common mistakes | +| Good/Correct | Green | #27AE60 | Recommended approaches, valid results, correct measurements | +| Annotation | Purple | #8E44AD | Brackets, dimensions, labels, measurements | +| Tip/Highlight | Amber | #E67E22 | Tips, parameters of interest, optional recommendations | + +**Supporting:** + +| Role | Color | Hex | Usage | +|------|-------|-----|-------| +| Primary text | Dark Slate | #2C3E50 | Headings, primary labels | +| Secondary text | Medium Gray | #5D6D7E | Secondary labels, descriptions | +| Card background | White | #FFFFFF | Figure card background | +| Formula background | Pale Blue | #EBF5FB | Formula/equation highlight boxes | +| Warning background | Pale Red | #FDEDEC | Warning callout box fill | +| Success background | Pale Green | #EAFAF1 | Success callout box fill | +| Annotation background | Pale Purple | #F4ECF7 | Note callout box fill | +| Tip background | Pale Amber | #FEF5E7 | Tip callout box fill | +| Page background | Off-white | #F0F2F5 | Outer page fill (when used) | + +### Callout Box Styles + +Four semantic callout box types are available: + +- **Warning (Red)** — `!` icon, #FDEDEC background, #E74C3C border. For dangers and things to watch out for. +- **Good/Correct (Green)** — checkmark icon, #EAFAF1 background, #27AE60 border. For recommended approaches. +- **Note (Purple)** — `i` icon, #F4ECF7 background, #8E44AD border. For general annotations and clarifications. +- **Tip (Amber)** — star icon, #FEF5E7 background, #E67E22 border. For tips and highlights. + +### Section Headers + +Colored bars with white text, using the semantic color that best fits the section content. Default to blue (#2874A6) for neutral sections. + +### Figure File Format + +- Generate as SVG source files +- Convert to PNG at 2x resolution using `rsvg-convert -z 2` +- Keep both SVG and PNG in `docs/Images/` (or the plugin's `docs/Images/` directory) +- Reference the PNG in documentation markdown +- Naming convention: `FilterName_Description.png` (e.g., `ComputeKernelAvgMisorientations_1D_Radius1.png`) + +--- + +## 7. Concept Link Strategy + +During triage and rewrite, track domain concepts that appear across multiple filters. When a concept appears in 3+ filter docs, it is a candidate for a shared concept page. + +**During this review:** +- Note concept links needed in the tracker document +- Define terms inline in filter docs on first use +- Use placeholder links in the format `[concept name](link-tbd)` where a shared page would be ideal + +**Future task:** +- Create shared concept pages in a canonical location within this repo +- Replace placeholder links with real links +- Consolidate existing concept docs from scattered locations + +**Likely concept pages based on initial survey:** +- Quaternions and Orientation Representations +- Feature IDs and Grains +- Image Geometry (Voxels, Dimensions, Spacing, Origin) +- Cell vs. Feature vs. Ensemble Data +- Misorientation +- Crystallographic Symmetry +- Reference Frames and Conventions + +--- + +## 8. Batch Organization + +Rewrites are organized by functional category. Suggested batch order (highest impact first): + +| Batch | Category | Approx. Count | Rationale | +|-------|----------|---------------|-----------| +| 1 | Orientation / Crystallography Statistics | ~15 | Highest domain complexity, most likely Tier 1 | +| 2 | Alignment Filters | ~8 | Spatial concepts benefit from figures | +| 3 | Segmentation / Feature Identification | ~10 | Core workflow, many users encounter these | +| 4 | Neighbor / Kernel Operations | ~12 | Spatial concepts, parameter guidance needed | +| 5 | Geometry Creation / Manipulation | ~15 | Many options, complex parameter interactions | +| 6 | Data Manipulation (Copy, Create, Delete, Rename) | ~20 | Mostly Tier 3-4, quick to process | +| 7 | I/O Filters (Read/Write) | ~15 | Mostly Tier 3-4 | +| 8 | Image Processing (ITK wrappers) | ~88 | Large batch, many follow a template pattern | +| 9 | Remaining SimplnxCore filters | ~varies | Catch-all for uncategorized | + +Exact batch boundaries will be refined after the triage pass reveals the actual distribution across tiers and categories. + +--- + +## 9. Workflow Summary + +``` +Phase 1: Triage + Claude reviews all ~295 filter docs + → Produces docs/documentation_review_tracker.md + → User reviews tracker, adjusts tiers if needed + → User commits tracker + +Phase 2: Batched Rewrites (repeat per batch) + Claude rewrites batch of related filter docs + Claude generates conceptual figures (SVG → PNG) + → User reviews changes + → User commits batch + → Check off completed filters in tracker + +Phase 3: Final + All batches complete + → Submit single PR to develop + → Future: concept page consolidation, real-world visualizations +``` + +--- + +## 10. Files Created During This Design Phase + +| File | Purpose | +|------|---------| +| `docs/style_palette_final.svg` | Visual style guide for all generated figures | +| `docs/style_palette_options.svg` | Palette options explored during design (can be deleted) | +| `kernel_radius_infographic.svg` | Original combined infographic (repo root, can be deleted) | +| `src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_*.svg` | Individual figure SVG sources | +| `src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_*.png` | Individual figure PNGs for documentation | +| `src/Plugins/OrientationAnalysis/docs/ComputeKernelAvgMisorientationsFilter.md` | Updated filter doc (serves as template for rewrite style) | diff --git a/docs/upstream-filter-sources.md b/docs/upstream-filter-sources.md new file mode 100644 index 0000000000..43ac21f919 --- /dev/null +++ b/docs/upstream-filter-sources.md @@ -0,0 +1,73 @@ +# Upstream Filter Sources + +Lookup table mapping common input arrays to the filter(s) that produce them. Used when writing the **Required Input Sources** section of a filter's documentation (see the `vv-filter-documentation` skill for the convention). + +This file is intended to be grown over time. As more filters are documented or new filters are added, append rows. The longer-term goal is to derive a dependency graph from this data so that pipeline order constraints can be visualized. + +## How To Use + +When documenting a filter that requires array X, look up X in the table below and link to the producing filter from your Required Input Sources section using MyST link syntax: + +```markdown +- **X** -- produced by [Producer Human Name](ProducerFilter.md). +``` + +For arrays produced by EBSD readers (Cell Quaternions, Cell Phases, ensemble Crystal Structures), name the typical readers explicitly rather than picking one: + +```markdown +- **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). +``` + +## Conventions for Growing This Table + +- **One row per array, multiple producers comma-separated** in the Producer column when the array can come from several filters. +- **Plugin column** lists where the *producer* lives, not where the consuming filter lives. This drives the relative-path direction of MyST links. +- **Cross-plugin links** must use `../OtherPlugin/FilterFile.md`. Within-plugin links use `FilterFile.md` only. +- **Filter names match `humanName()`** in the .cpp, not the file name. The link target file is always `Filter.md`. +- **Notes column** (optional) for caveats: ensemble-level vs feature-level vs cell-level, optional inputs, mode dependencies (e.g., "only when *Find Coherence* is enabled"). + +## Lookup Table + +| Input Array | Producer (humanName) | Plugin | Notes | +|---|---|---|---| +| Cell Quaternions | Read H5EBSD / Read CTF Data / Read ANG Data / Convert Orientations | OrientationAnalysis | From EBSD readers, or computed from Euler angles | +| Cell Eulers | Same EBSD readers | OrientationAnalysis | Bunge convention Z-X-Z | +| Cell Phases | Same EBSD readers | OrientationAnalysis | Read alongside quaternions | +| Crystal Structures | Same EBSD readers / Create Ensemble Info | OrientationAnalysis | Ensemble-level array | +| Cell Feature Ids | Segment Features (Misorientation) | OrientationAnalysis | Misorientation-based grain segmentation | +| Cell Feature Ids | Segment Features (C-Axis Misalignment) | OrientationAnalysis | Hexagonal-only | +| Cell Feature Ids | Segment Features (Scalar) | SimplnxCore | Scalar-based segmentation | +| Cell Parent Ids | Merge Twins | OrientationAnalysis | Cell-level grouping into parent grains | +| Feature Parent Ids | Merge Twins | OrientationAnalysis | Feature-level mapping | +| Feature Phases | Compute Feature Phases | SimplnxCore | Feature-level (one phase per feature) | +| Feature Phases (Binary) | Compute Feature Phases (Binary) | SimplnxCore | Two-phase classification | +| Average Quaternions | Compute Average Orientations | OrientationAnalysis | Per-feature average orientation | +| Average Euler Angles | Compute Average Orientations | OrientationAnalysis | Bunge convention Z-X-Z | +| Average C-Axes | Compute Average C-Axis Orientations | OrientationAnalysis | Hexagonal-only | +| Feature Centroids | Compute Feature Centroids | SimplnxCore | Cell-of-mass per feature | +| Feature Equivalent Diameters | Compute Feature Sizes | SimplnxCore | Diameter of equal-volume sphere | +| Feature Num. Cells (NumElements) | Compute Feature Sizes | SimplnxCore | Cell count per feature | +| Feature Volumes | Compute Feature Sizes | SimplnxCore | Physical volume | +| Surface Features | Compute Surface Features | SimplnxCore | Boolean per feature | +| Surface Features | Compute Feature Neighbors | SimplnxCore | Optional output (enable *Store Surface Features Array*) | +| Biased Features | Compute Biased Features (Bounding Box) | SimplnxCore | Boolean per feature | +| Number of Neighbors | Compute Feature Neighbors | SimplnxCore | Count per feature | +| Contiguous Neighbor List | Compute Feature Neighbors | SimplnxCore | NeighborList of contiguous Feature Ids | +| Shared Surface Area List | Compute Feature Neighbors | SimplnxCore | NeighborList in cell-face-count units | +| Boundary Cells | Compute Feature Neighbors | SimplnxCore | Optional output (enable *Store Boundary Cells Array*) | +| Neighborhoods Neighbor List | Compute Feature Neighborhoods | SimplnxCore | Sphere-radius-based neighbor list | +| Mask | Multi-Threshold Objects | SimplnxCore | Boolean per cell | +| Boundary Euclidean Distances | Compute Euclidean Distance Map | SimplnxCore | Cell-level distance to nearest boundary | +| Triangle Geometry | Quick Surface Mesh | SimplnxCore | Surface mesh from Feature Ids | +| Face Labels | Quick Surface Mesh | SimplnxCore | Per-face Feature ID pair (2-component) | +| Face Normals | Compute Triangle Normals | SimplnxCore | 3-component, on triangle face data | +| Face Areas | Compute Triangle Areas | SimplnxCore | Single-component, on triangle face data | +| Node Types | Quick Surface Mesh | SimplnxCore | Per-vertex node classification | +| Cell Shifts Array (alignment) | Align Sections (Feature Centroid) | SimplnxCore | Output of any Align Sections * filter | +| Cell Shifts Array (alignment) | Align Sections (Misorientation) | OrientationAnalysis | | +| Cell Shifts Array (alignment) | Align Sections (Mutual Information) | OrientationAnalysis | | +| Confidence Index / Image Quality | Read H5EBSD / Read CTF Data / Read ANG Data | OrientationAnalysis | Per-cell scalar quality metric | + +## Future: Graph Representation + +The lookup table is naturally a directed dependency graph: each row is an edge from a producer filter to the input-array node. A separate downstream effort may convert this into a graph (DOT, Mermaid, or networked JSON) to support pipeline-order checking, "what would I need to run before X?" queries, and visual dependency maps. Keep that future use in mind when adding rows -- be precise about producer humanName so the data is machine-parseable. diff --git a/src/Plugins/ITKImageProcessing/CMakeLists.txt b/src/Plugins/ITKImageProcessing/CMakeLists.txt index 6e4192516e..2eeea095a7 100644 --- a/src/Plugins/ITKImageProcessing/CMakeLists.txt +++ b/src/Plugins/ITKImageProcessing/CMakeLists.txt @@ -185,7 +185,7 @@ if(NOT ITKIMAGEPROCESSING_LEAN_AND_MEAN) ITKMeanProjectionImageFilter # ITKStandardDeviationProjectionImage # ITKSumProjectionImage - # ITKMorphologicalWatershedFromMarkersImage + # ITKMorphologicalWatershedFromMarkersImage # disabled: incomplete wrapper, no marker-image input. See https://github.com/BlueQuartzSoftware/simplnx/issues/1639 # ITKSmoothingRecursiveGaussianImage # ----------------------------------------------------------------------------- diff --git a/src/Plugins/ITKImageProcessing/docs/ITKAbsImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKAbsImageFilter.md index 2ba968b9d6..92e89e4a00 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKAbsImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKAbsImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -itk::Math::abs() is used to perform the computation. +Computes the absolute value (magnitude) of each pixel. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -16,7 +16,7 @@ itk::Math::abs() is used to perform the computation. ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKAcosImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKAcosImageFilter.md index aad80ef7b6..675527b3ab 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKAcosImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKAcosImageFilter.md @@ -8,16 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -This filter is templated over the pixel type of the input image and the pixel type of the output image. - -The filter walks over all the pixels in the input image, and for each pixel does do the following: - -- cast the pixel value to double , -- apply the std::acos() function to the double value -- cast the double value resulting from std::acos() to the pixel type of the output image -- store the casted value into the output image. - -The filter expects both images to have the same dimension (e.g. both 2D, or both 3D, or both ND). +Computes the arccosine (inverse cosine) of each pixel. Input values should be in the range [-1, 1]; the output is in radians. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -25,7 +16,7 @@ The filter expects both images to have the same dimension (e.g. both 2D, or both ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKAdaptiveHistogramEqualizationImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKAdaptiveHistogramEqualizationImageFilter.md index 3dc4c9560a..2cb36994b0 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKAdaptiveHistogramEqualizationImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKAdaptiveHistogramEqualizationImageFilter.md @@ -1,6 +1,6 @@ # ITK Adaptive Histogram Equalization Image Filter -Power Law Adaptive Histogram Equalization. +Enhances local contrast using a tunable power-law adaptive histogram equalization. ## Group (Subgroup) @@ -8,21 +8,23 @@ ITKImageStatistics (ImageStatistics) ## Description -Histogram equalization modifies the contrast in an image. The AdaptiveHistogramEqualizationImageFilter is a superset of many contrast enhancing filters. By modifying its parameters (alpha, beta, and window), the AdaptiveHistogramEqualizationImageFilter can produce an adaptively equalized histogram or a version of unsharp mask (local mean subtraction). Instead of applying a strict histogram equalization in a window about a pixel, this filter prescribes a mapping function (power law) controlled by the parameters alpha and beta. +Histogram equalization redistributes pixel intensities to improve contrast. This filter is *adaptive*: instead of one global remap, it computes statistics in a local window around each pixel and applies a power-law mapping controlled by *alpha*, *beta*, and the window size. By tuning those parameters it can behave like classical histogram equalization, like an unsharp mask (local mean subtraction), or anything in between. -The parameter alpha controls how much the filter acts like the classical histogram equalization method (alpha=0) to how much the filter acts like an unsharp mask (alpha=1). +### Parameter Guidance -The parameter beta controls how much the filter acts like an unsharp mask (beta=0) to much the filter acts like pass through (beta=1, with alpha=1). +- **Alpha** — blends between classical histogram equalization (*alpha = 0*) and an unsharp mask (*alpha = 1*). Dimensionless, range 0-1. +- **Beta** — blends between an unsharp mask (*beta = 0*) and pass-through / no change (*beta = 1*, with *alpha = 1*). Dimensionless, range 0-1. +- **Radius** — the half-width of the local window per axis, **in pixels**; the window spans `2 × Radius + 1` pixels along each axis (default radius *5*). Larger windows use broader local statistics. -The parameter window controls the size of the region over which local statistics are calculated. The size of the window is controlled by SetRadius the default Radius is 5 in all directions. +### Required Input Sources -By altering alpha, beta and window, a host of equalization and unsharp masking filters is available. +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -The boundary condition ignores the part of the neighborhood outside the image, and over-weights the valid part of the neighborhood. +## Reference -For detail description, reference "Adaptive Image Contrast Enhancement using Generalizations of Histogram Equalization." J.Alex Stark. IEEE Transactions on Image Processing, May 2000. +J. Alex Stark, "Adaptive Image Contrast Enhancement using Generalizations of Histogram Equalization," *IEEE Transactions on Image Processing*, May 2000. -![](Images/ITKAdaptiveImageHistogram.png) +![Adaptive histogram equalization example.](Images/ITKAdaptiveImageHistogram.png) % Auto generated parameter table will be inserted here @@ -30,7 +32,7 @@ For detail description, reference "Adaptive Image Contrast Enhancement using Gen ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKApproximateSignedDistanceMapImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKApproximateSignedDistanceMapImageFilter.md index 612baef9d1..a2b14e6800 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKApproximateSignedDistanceMapImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKApproximateSignedDistanceMapImageFilter.md @@ -1,6 +1,6 @@ # ITK Approximate Signed Distance Map Image Filter -Create a map of the approximate signed distance from the boundaries of a binary image. +Computes a fast, approximate signed distance map from the object boundaries in a binary image. ## Group (Subgroup) @@ -8,33 +8,35 @@ ITKDistanceMap (DistanceMap) ## Description -The ApproximateSignedDistanceMapImageFilter takes as input a binary image and produces a signed distance map. Each pixel value in the output contains the approximate distance from that pixel to the nearest "object" in the binary image. This filter differs from the DanielssonDistanceMapImageFilter in that it calculates the distance to the "object edge" for pixels within the object. +A **distance map** replaces every pixel with its distance to the nearest object boundary. This filter produces a **signed** distance map: pixels inside an object are given **negative** distances, and pixels outside an object are given **positive** distances. The magnitude of each value is the (approximate) distance, in **pixels**, from that pixel to the closest object boundary. -Negative values in the output indicate that the pixel at that position is within an object in the input image. The absolute value of a negative pixel represents the approximate distance to the nearest object boundary pixel. +The distances are **Chamfer distances**, a fast approximation to true Euclidean distance. This filter trades some accuracy for speed. If you need a closer approximation to Euclidean distance, use the [Danielsson](ITKDanielssonDistanceMapImageFilter.md) or [Signed Maurer](ITKSignedMaurerDistanceMapImageFilter.md) distance maps instead. -WARNING: This filter requires that the output type be floating-point. Otherwise internal calculations will not be performed to the appropriate precision, resulting in completely incorrect (read: zero-valued) output. +Use a signed distance map when you need a smooth field that grows away from object boundaries in both directions — for example, as a speed/level-set input, for shape morphing, or to find points a fixed distance from a feature edge. -The distances computed by this filter are Chamfer distances, which are only an approximation to Euclidean distances, and are not as exact approximations as those calculated by the DanielssonDistanceMapImageFilter . On the other hand, this filter is faster. +> Note: distances are computed and stored as floating-point values. Choose a floating-point output array type; an integer output cannot represent fractional or negative distances correctly. -This filter requires that an "inside value" and "outside value" be set as parameters. The "inside value" is the intensity value of the binary image which corresponds to objects, and the "outside value" is the intensity of the background. (A typical binary image often represents objects as black (0) and background as white (usually 255), or vice-versa.) Note that this filter is slightly faster if the inside value is less than the outside value. Otherwise an extra iteration through the image is required. +### Parameter Guidance -This filter uses the FastChamferDistanceImageFilter and the IsoContourDistanceImageFilter internally to perform the distance calculations. +The binary input is interpreted using two intensity values: -## See Also - -- [DanielssonDistanceMapImageFilter](https://itk.org/Doxygen/html/classitk_1_1DanielssonDistanceMapImageFilter.html) +- **Inside Value** — the pixel intensity that marks the **object** (foreground). Default *1*. +- **Outside Value** — the pixel intensity that marks the **background**. Default *0*. -- [SignedDanielssonDistanceMapImageFilter](https://itk.org/Doxygen/html/classitk_1_1SignedDanielssonDistanceMapImageFilter.html) +For example, in a typical mask where objects are labeled *1* and background is *0*, set *Inside Value = 1* and *Outside Value = 0*. If your mask labels objects as *255* on a *0* background, set *Inside Value = 255* and *Outside Value = 0*. -- [SignedMaurerDistanceMapImageFilter](https://itk.org/Doxygen/html/classitk_1_1SignedMaurerDistanceMapImageFilter.html) +The filter runs slightly faster when *Inside Value* is less than *Outside Value*; otherwise an extra pass over the image is required. -- [FastChamferDistanceImageFilter](https://itk.org/Doxygen/html/classitk_1_1FastChamferDistanceImageFilter.html) +### Required Input Sources -- [IsoContourDistanceImageFilter](https://itk.org/Doxygen/html/classitk_1_1IsoContourDistanceImageFilter.html) +Requires a binary (two-value) image where one intensity marks objects and the other marks background. This is typically a segmentation mask produced by a thresholding or segmentation filter upstream. -## Author +## See Also -- Zach Pincus +- [ITK Danielsson Distance Map Image Filter](ITKDanielssonDistanceMapImageFilter.md) +- [ITK Signed Danielsson Distance Map Image Filter](ITKSignedDanielssonDistanceMapImageFilter.md) +- [ITK Signed Maurer Distance Map Image Filter](ITKSignedMaurerDistanceMapImageFilter.md) +- [ITK ApproximateSignedDistanceMapImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1ApproximateSignedDistanceMapImageFilter.html) % Auto generated parameter table will be inserted here @@ -42,8 +44,8 @@ This filter uses the FastChamferDistanceImageFilter and the IsoContourDistanceIm ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKAsinImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKAsinImageFilter.md index 765c027fc5..98cab13d85 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKAsinImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKAsinImageFilter.md @@ -8,16 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -This filter is templated over the pixel type of the input image and the pixel type of the output image. - -The filter walks over all the pixels in the input image, and for each pixel does the following: - -- cast the pixel value to double , -- apply the std::asin() function to the double value, -- cast the double value resulting from std::asin() to the pixel type of the output image, -- store the casted value into the output image. - -The filter expects both images to have the same dimension (e.g. both 2D, or both 3D, or both ND) +Computes the arcsine (inverse sine) of each pixel. Input values should be in the range [-1, 1]; the output is in radians. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -25,7 +16,7 @@ The filter expects both images to have the same dimension (e.g. both 2D, or both ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKAtanImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKAtanImageFilter.md index dedf8ccc50..73cf9a1644 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKAtanImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKAtanImageFilter.md @@ -8,14 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -This filter is templated over the pixel type of the input image and the pixel type of the output image. - -The filter walks over all the pixels in the input image, and for each pixel does the following: - -- cast the pixel value to double , -- apply the std::atan() function to the double value, -- cast the double value resulting from std::atan() to the pixel type of the output image, -- store the cast value into the output image. +Computes the arctangent (inverse tangent) of each pixel. The output is in radians. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -23,7 +16,7 @@ The filter walks over all the pixels in the input image, and for each pixel does ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryContourImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryContourImageFilter.md index ed8e1ad590..5817a138f0 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryContourImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryContourImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Contour Image Filter -Labels the pixels on the border of the objects in a binary image. +Extracts the one-pixel-wide outlines of the foreground objects in a binary image. ## Group (Subgroup) @@ -8,19 +8,21 @@ ITKImageLabel (ImageLabel) ## Description -BinaryContourImageFilter takes a binary image as input, where the pixels in the objects are the pixels with a value equal to ForegroundValue. Only the pixels on the contours of the objects are kept. The pixels not on the border are changed to BackgroundValue. +This filter keeps only the **border** pixels of the foreground objects in a binary image. A foreground pixel (one whose value equals the *Foreground Value*) is retained as a contour pixel if it is adjacent to a background pixel; all interior and background pixels are set to the *Background Value*. The result is the outline of each object. -The connectivity can be changed to minimum or maximum connectivity with SetFullyConnected() . Full connectivity produces thicker contours. +### Parameter Guidance - +- **Foreground Value** — the pixel value that marks objects in the input. Contour pixels keep this value in the output. Default *1*. +- **Background Value** — the value written for non-contour pixels (interior and background). Default *0*. +- **Fully Connected** — controls neighbor connectivity. With it off, only face-sharing neighbors count (thinner contours); with it on, edge- and corner-sharing neighbors also count, producing **thicker contours**. -### Author +### Required Input Sources - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). For outlines of a multi-region label image, see [ITK Label Contour Image Filter](ITKLabelContourImageFilter.md). -### Related Filters +## Reference -- LabelContourImageFilter BinaryErodeImageFilter SimpleContourExtractorImageFilter +Insight Journal: % Auto generated parameter table will be inserted here @@ -28,7 +30,7 @@ The connectivity can be changed to minimum or maximum connectivity with SetFully ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryDilateImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryDilateImageFilter.md index c903331861..dc77007bd1 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryDilateImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryDilateImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Dilate Image Filter -Fast binary dilation of a single intensity value in the image. +Grows (dilates) the foreground objects of a binary or segmented image. ## Group (Subgroup) @@ -8,39 +8,39 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -BinaryDilateImageFilter is a binary dilation morphologic operation on the foreground of an image. Only the value designated by the intensity value "SetForegroundValue()" (alias as SetDilateValue() ) is considered as foreground, and other intensity values are considered background. +**Dilation** is a morphological operation that grows the foreground region of an image: a small probe shape called the **structuring element** is swept over the image, and any background pixel touched by the structuring element when it is centered on a foreground pixel becomes foreground. Dilation fills small gaps, connects nearby objects, and enlarges objects by the radius of the structuring element. (The inverse operation is [ITK Binary Erode Image Filter](ITKBinaryErodeImageFilter.md); combining the two gives [opening](ITKBinaryMorphologicalOpeningImageFilter.md) and [closing](ITKBinaryMorphologicalClosingImageFilter.md).) -Grayscale images can be processed as binary images by selecting a "ForegroundValue" (alias "DilateValue"). Pixel values matching the dilate value are considered the "foreground" and all other pixels are "background". This is useful in processing segmented images where all pixels in segment #1 have value 1 and pixels in segment #2 have value 2, etc. A particular "segment number" can be processed. ForegroundValue defaults to the maximum possible value of the PixelType. +The filter treats one chosen value as foreground. This makes it work directly on segmented images: if segment 1 has value 1, segment 2 has value 2, and so on, set *Foreground Value* to the segment number you want to dilate. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel. A reasonable choice of structuring element is itk::BinaryBallStructuringElement . +### Parameter Guidance -This implementation is based on the papers: +- **Foreground Value** — the pixel value treated as the object/foreground (everything else is background). Default *1*. +- **Background Value** — the value used for background pixels. Default *0*. +- **Boundary To Foreground** — controls whether the region just outside the image border is treated as foreground or background, which affects objects that touch the edge of the volume. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Objects grow by this amount. -L.Vincent "Morphological transformations of binary images with -arbitrary structuring elements", and +#### Kernel Type -N.Nikopoulos et al. "An efficient algorithm for 3d binary -morphological transformations with 3d structuring elements -for arbitrary size and shape". IEEE Transactions on Image Processing. Vol. 9. No. 3. 2000. pp. 283-286.* ImageToImageFilter BinaryErodeImageFilter BinaryMorphologyImageFilter - -![](Images/ITKBinaryDilation.png) - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + +![Binary dilation example.](Images/ITKBinaryDilation.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryErodeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryErodeImageFilter.md index 7a86eb1916..292ea590af 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryErodeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryErodeImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Erode Image Filter -Fast binary erosion of a single intensity value in the image. +Shrinks (erodes) the foreground objects of a binary or segmented image. ## Group (Subgroup) @@ -8,39 +8,39 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -BinaryErodeImageFilter is a binary erosion morphologic operation on the foreground of an image. Only the value designated by the intensity value "SetForegroundValue()" (alias as SetErodeValue() ) is considered as foreground, and other intensity values are considered background. +**Erosion** is a morphological operation that shrinks the foreground region of an image: a small probe shape called the **structuring element** is swept over the image, and a foreground pixel is kept only if the structuring element centered on it fits entirely within the foreground. Erosion removes small specks, separates objects connected by thin bridges, and shrinks objects by the radius of the structuring element. Eroded pixels are set to the *Background Value*. (The inverse operation is [ITK Binary Dilate Image Filter](ITKBinaryDilateImageFilter.md); combining the two gives [opening](ITKBinaryMorphologicalOpeningImageFilter.md) and [closing](ITKBinaryMorphologicalClosingImageFilter.md).) -Grayscale images can be processed as binary images by selecting a "ForegroundValue" (alias "ErodeValue"). Pixel values matching the erode value are considered the "foreground" and all other pixels are "background". This is useful in processing segmented images where all pixels in segment #1 have value 1 and pixels in segment #2 have value 2, etc. A particular "segment number" can be processed. ForegroundValue defaults to the maximum possible value of the PixelType. The eroded pixels will receive the BackgroundValue (defaults to NumericTraits::NonpositiveMin() ). +The filter treats one chosen value as foreground, so it works directly on segmented images: set *Foreground Value* to the segment number you want to erode. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel. A reasonable choice of structuring element is itk::BinaryBallStructuringElement . +### Parameter Guidance -This implementation is based on the papers: +- **Foreground Value** — the pixel value treated as the object/foreground. Default *1*. +- **Background Value** — the value assigned to eroded pixels (and background). Default *0* (i.e. the lowest pixel value). +- **Boundary To Foreground** — controls whether the region just outside the image border is treated as foreground or background, which affects objects that touch the edge of the volume. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Objects shrink by this amount. -L.Vincent "Morphological transformations of binary images with -arbitrary structuring elements", and +#### Kernel Type -N.Nikopoulos et al. "An efficient algorithm for 3d binary -morphological transformations with 3d structuring elements -for arbitrary size and shape". IEEE Transactions on Image Processing. Vol. 9. No. 3. 2000. pp. 283-286.* ImageToImageFilter BinaryDilateImageFilter BinaryMorphologyImageFilter - -![](Images/ITKBinaryErosion.png) - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + +![Binary erosion example.](Images/ITKBinaryErosion.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalClosingImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalClosingImageFilter.md index 4623b6b753..e15f409b5a 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalClosingImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalClosingImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Morphological Closing Image Filter -binary morphological closing of an image. +Fills small holes and thin gaps in the foreground of a binary image (dilation followed by erosion). ## Group (Subgroup) @@ -8,30 +8,32 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -This filter removes small (i.e., smaller than the structuring element) holes and tube like structures in the interior or at the boundaries of the image. The morphological closing of an image "f" is defined as: Closing(f) = Erosion(Dilation(f)). +**Closing** is a morphological operation that fills small holes and thin gaps inside and along the borders of foreground objects, without much changing their overall size. It is a **dilation followed by an erosion** using the same structuring element: `Closing(f) = Erosion(Dilation(f))`. The dilation fills features smaller than the **structuring element** (the probe shape swept over the image), and the following erosion shrinks the objects back to roughly their original size. Use it to close up pinholes and cracks in segmented regions. The inverse pairing is [ITK Binary Morphological Opening Image Filter](ITKBinaryMorphologicalOpeningImageFilter.md), which removes small specks instead. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel. +### Parameter Guidance -This code was contributed in the Insight Journal paper: "Binary morphological closing and opening image filters" by Lehmann G. +- **Foreground Value** — the pixel value treated as the object/foreground. Default *1*. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Holes/gaps smaller than this are filled. +- **Safe Border** — when on (default), a temporary border is added around the image during processing to avoid edge artifacts and removed afterward. -### Author +#### Kernel Type - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +The *Kernel Type* parameter selects the structuring element shape: -### Related Filters +- **Annulus [0]**: A ring-shaped structuring element. +- **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. +- **Box [2]**: A rectangular/cuboid structuring element. +- **Cross [3]**: A cross-shaped structuring element. -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleErodeImageFilter +### Required Input Sources -![](Images/ITKBinaryClosing.png) +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). -### Kernel Type +![Binary closing example.](Images/ITKBinaryClosing.png) -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +## Reference -- **Annulus [0]**: A ring-shaped structuring element. -- **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. -- **Box [2]**: A rectangular/cuboid structuring element. -- **Cross [3]**: A cross-shaped structuring element. +G. Lehmann, "Binary morphological closing and opening image filters," Insight Journal, . % Auto generated parameter table will be inserted here @@ -39,7 +41,7 @@ The *Kernel Type* parameter selects the structuring element used for the morphol ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalOpeningImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalOpeningImageFilter.md index 59f5c04986..fad610ed5c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalOpeningImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryMorphologicalOpeningImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Morphological Opening Image Filter -binary morphological opening of an image. +Removes small foreground specks and thin protrusions from a binary image (erosion followed by dilation). ## Group (Subgroup) @@ -8,30 +8,32 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -This filter removes small (i.e., smaller than the structuring element) structures in the interior or at the boundaries of the image. The morphological opening of an image "f" is defined as: Opening(f) = Dilatation(Erosion(f)). +**Opening** is a morphological operation that removes small foreground features — isolated specks, thin protrusions, and narrow bridges — that are smaller than the **structuring element** (the probe shape swept over the image), while leaving larger objects close to their original size. It is an **erosion followed by a dilation** using the same structuring element: `Opening(f) = Dilation(Erosion(f))`. The erosion deletes the small features and the following dilation restores the surviving objects to roughly their original size. The inverse pairing is [ITK Binary Morphological Closing Image Filter](ITKBinaryMorphologicalClosingImageFilter.md), which fills small holes instead. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel. +### Parameter Guidance -This code was contributed in the Insight Journal paper: "Binary morphological closing and opening image filters" by Lehmann G. +- **Foreground Value** — the pixel value treated as the object/foreground. Default *1*. +- **Background Value** — the value used for removed/background pixels. Default *0*. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Features smaller than this are removed. -### Author +#### Kernel Type - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +The *Kernel Type* parameter selects the structuring element shape: -### Related Filters +- **Annulus [0]**: A ring-shaped structuring element. +- **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. +- **Box [2]**: A rectangular/cuboid structuring element. +- **Cross [3]**: A cross-shaped structuring element. -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleErodeImageFilter +### Required Input Sources -![](Images/ITKBinaryOpening.png) +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). -### Kernel Type +![Binary opening example.](Images/ITKBinaryOpening.png) -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +## Reference -- **Annulus [0]**: A ring-shaped structuring element. -- **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. -- **Box [2]**: A rectangular/cuboid structuring element. -- **Cross [3]**: A cross-shaped structuring element. +G. Lehmann, "Binary morphological closing and opening image filters," Insight Journal, . % Auto generated parameter table will be inserted here @@ -39,7 +41,7 @@ The *Kernel Type* parameter selects the structuring element used for the morphol ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryOpeningByReconstructionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryOpeningByReconstructionImageFilter.md index 2cb606eb1c..666324b2c0 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryOpeningByReconstructionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryOpeningByReconstructionImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Opening By Reconstruction Image Filter -Binary morphological opening by reconstruction of an image. +Removes small foreground objects from a binary image while preserving the exact shape of the objects that remain. ## Group (Subgroup) @@ -8,36 +8,45 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -This filter removes small (i.e., smaller than the structuring element) objects in the image. It is defined as: Opening(f) = ReconstructionByDilatation(Erosion(f)). +Like a standard morphological **opening**, this filter removes foreground objects that are smaller than the **structuring element** (the small probe shape — a ball, box, etc. — that is swept over the image). Unlike a plain opening, it then uses **morphological reconstruction** to restore the surviving objects to their original shape. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel. +A plain opening erodes (shrinks) the image and then dilates (regrows) it. The erosion deletes small objects, but it also rounds off and shrinks the corners of the larger objects that survive. Opening *by reconstruction* avoids that side effect: after the erosion deletes the small objects, the reconstruction step regrows each surviving object back to exactly its original boundary instead of the rounded, dilated approximation. The net effect is "delete the small objects, leave the rest untouched." -### Author - - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +The result is defined as `Opening(f) = ReconstructionByDilation(Erosion(f))`. -### Related Filters +![Binary opening by reconstruction.](Images/ITKOpeningByReconstruction.png) -This implementation was taken from the Insight Journal paper: * MorphologyImageFilter , OpeningByReconstructionImageFilter , BinaryClosingByReconstructionImageFilter +### Parameter Guidance -![](Images/ITKOpeningByReconstruction.png) +- **Foreground Value** — the pixel value that counts as object/foreground (everything else is background). For a segmented or thresholded image, this is the label of the region to process. +- **Background Value** — the value written where foreground is removed. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Objects smaller than this are removed. +- **Fully Connected** — controls neighbor connectivity during reconstruction (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on a binary/segmented image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). Compare with the standard [ITK Binary Morphological Opening Image Filter](ITKBinaryMorphologicalOpeningImageFilter.md), which does not preserve object shape. + +### Author + +Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. (Insight Journal: ) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryProjectionImageFilter.md index 28ab3ff615..a784393403 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryProjectionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryProjectionImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Projection Image Filter -Binary projection. +Collapses a 3D volume to a 2D image using a logical-OR projection: a pixel is foreground if any voxel along the axis is foreground. ## Group (Subgroup) @@ -8,30 +8,24 @@ ITKImageStatistics (ImageStatistics) ## Description -Image projection is a very common task in image analysis to reduce the dimension of an image. A base -filter is provided with some specialized filters which implement different projection methods. +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses a **binary (logical-OR) rule**: for each line of voxels parallel to the selected axis, the output pixel is set to the *Foreground Value* if **any** voxel along that line equals the *Foreground Value*; otherwise it is set to the *Background Value*. The result has one fewer dimension than the input. -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at +Use binary projection to answer "is this feature present anywhere along this axis?" — for example, to flatten a segmented 3D mask into a 2D footprint showing where labeled material exists at any depth. -## IMPORTANT NOTE +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` -This filter will change the dimensionality of the Image Geometry that the data is tied to. This has the side effect of also -changing **every** Data Array that is store in the same AttributeMatrix as the input and output data array. +### Parameter Guidance -### Author +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. +- *Foreground Value* — the voxel value treated as "foreground." An output pixel is set to this value if any voxel along the collapsed line matches it. Defaults to *1*. +- *Background Value* — the value written to output pixels where no foreground voxel was found along the line. Defaults to *0*. +- *Perform In-Place* — when enabled, the projection replaces the input geometry rather than creating a new one. - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +### Required Input Sources -### Related Filters - -- ProjectionImageFilter -- MedianProjectionImageFilter -- MeanProjectionImageFilter -- MeanProjectionImageFilter -- MaximumProjectionImageFilter -- MinimumProjectionImageFilter -- StandardDeviationProjectionImageFilter -- SumProjectionImageFilter +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -39,7 +33,7 @@ changing **every** Data Array that is store in the same AttributeMatrix as the i ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryThinningImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryThinningImageFilter.md index 555b11cbdd..02cecd4aa5 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryThinningImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryThinningImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Thinning Image Filter -This filter computes one-pixel-wide edges of the input image. +Reduces the foreground objects of a binary image to a one-pixel-wide skeleton. ## Group (Subgroup) @@ -8,17 +8,19 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -This class is parameterized over the type of the input image and the type of the output image. +This filter computes the **skeleton** (medial axis) of the foreground objects in a binary image: it repeatedly removes boundary pixels until each object is reduced to a connected, one-pixel-wide line that still captures the object's overall shape and connectivity. Skeletons are useful for analyzing the topology of elongated structures — measuring branch lengths, counting junctions, or tracing networks of fibers, cracks, or vessels. -The input is assumed to be a binary image. If the foreground pixels of the input image do not have a value of 1, they are rescaled to 1 internally to simplify the computation. +The input is treated as a binary image; if the foreground pixels are not already valued 1 they are rescaled to 1 internally. In the output, background pixels are 0 and the skeleton pixels are 1. -The filter will produce a skeleton of the object. The output background values are 0, and the foreground values are 1. +**Caveat:** this is a sequential 2D thinning algorithm (the classic Gonzalez & Woods method). On a 3D volume it operates slice by slice rather than producing a true 3D skeleton, and its run time grows with image size. -This filter is a sequential thinning algorithm and known to be computational time dependable on the image size. The algorithm corresponds with the 2D implementation described in: +### Required Input Sources -Rafael C. Gonzales and Richard E. Woods. Digital Image Processing. Addison Wesley, 491-494, (1993). +Operates on a binary image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). -To do: Make this filter ND.* MorphologyImageFilter +## Reference + +Rafael C. Gonzalez and Richard E. Woods. *Digital Image Processing*. Addison Wesley, 491-494 (1993). % Auto generated parameter table will be inserted here @@ -26,7 +28,7 @@ To do: Make this filter ND.* MorphologyImageFilter ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBinaryThresholdImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBinaryThresholdImageFilter.md index 6bb4a0232f..2ff3d6d5ad 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBinaryThresholdImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBinaryThresholdImageFilter.md @@ -1,6 +1,6 @@ # ITK Binary Threshold Image Filter -Binarize an input image by thresholding. +Produces a two-value (binary) image by marking pixels whose intensity falls inside a chosen range. ## Group (Subgroup) @@ -8,19 +8,23 @@ ITKThresholding (Thresholding) ## Description -This filter produces an output image whose pixels are either one of two values ( OutsideValue or InsideValue ), depending on whether the corresponding input image pixels lie between the two thresholds ( LowerThreshold and UpperThreshold ). Values equal to either threshold is considered to be between the thresholds. +This filter binarizes an image. Every pixel whose value lies **between the Lower Threshold and Upper Threshold (inclusive)** is set to the *Inside Value*; every other pixel is set to the *Outside Value*: -More precisely \f[ Output(x_i) = \begin{cases} InsideValue & \text{if \f$LowerThreshold \leq x_i \leq UpperThreshold\f$} \\ OutsideValue & \text{otherwise} \end{cases} \f] +$$ +\text{output}(x) = \begin{cases} \text{InsideValue} & \text{if } \text{LowerThreshold} \le x \le \text{UpperThreshold} \\ \text{OutsideValue} & \text{otherwise} \end{cases} +$$ -This filter is templated over the input image type and the output image type. +### Parameter Guidance -The filter expect both images to have the same number of dimensions. +- **Lower Threshold** / **Upper Threshold** — the bounds of the "inside" range, in the **input image's intensity units**. By default the lower bound is the smallest possible pixel value and the upper bound is the largest, so the range spans everything; in practice you usually set only one of the two — a lower bound to keep everything *above* a value, or an upper bound to keep everything *below* a value. +- **Inside Value** — the output value written for pixels inside the range (a `uint8` label, default *1*). +- **Outside Value** — the output value written for pixels outside the range (a `uint8` label, default *0*). -The default values for LowerThreshold and UpperThreshold are: LowerThreshold = NumericTraits::NonpositiveMin() ; UpperThreshold = NumericTraits::max() ; Therefore, generally only one of these needs to be set, depending on whether the user wants to threshold above or below the desired threshold. +![Binary threshold result.](Images/ITKBinaryThreshold.png) -Set the thresholds. The default lower threshold is NumericTraits::NonpositiveMin() . The default upper threshold is NumericTraits::max . An exception is thrown if the lower threshold is greater than the upper threshold. +### Required Input Sources -![](Images/ITKBinaryThreshold.png) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -28,7 +32,7 @@ Set the thresholds. The default lower threshold is NumericTraits ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBlackTopHatImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKBlackTopHatImageFilter.md index 73458c3797..aaa5726353 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBlackTopHatImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKBlackTopHatImageFilter.md @@ -1,6 +1,6 @@ # ITK Black Top Hat Image Filter -Black top hat extracts local minima that are smaller than the structuring element. +Extracts small dark features by subtracting the original image from its grayscale closing. ## Group (Subgroup) @@ -8,35 +8,40 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Black top hat extracts local minima that are smaller than the structuring element. It subtracts the background from the input image. The output of the filter transforms the black valleys into white peaks. +The **black top-hat** isolates small **dark** features — dark spots and narrow dark valleys smaller than the **structuring element** (the probe shape swept over the image). It is computed as the grayscale **closing** of the image minus the original image, which turns the dark valleys into bright peaks on a flat (near-zero) background. A common use is correcting uneven dark background or extracting small dark details for measurement. The bright-feature counterpart is [ITK White Top Hat Image Filter](ITKWhiteTopHatImageFilter.md). -Top-hats are described in Chapter 4.5 of Pierre Soille's book "Morphological Image Analysis: Principles and Applications", Second Edition, Springer, 2003. +### Parameter Guidance -### Author +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). It sets the size scale: features smaller than the structuring element are extracted, larger structures are removed. +- **Safe Border** — when on (default), a temporary border is added during processing to avoid edge artifacts and removed afterward. - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +#### Kernel Type -### Related Filters - -![](Images/ITKBlackTopHat_1.png) -![](Images/ITKBlackTopHat_2.png) - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Black top-hat example.](Images/ITKBlackTopHat_1.png) +![Black top-hat example.](Images/ITKBlackTopHat_2.png) + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 4.5). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKClosingByReconstructionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKClosingByReconstructionImageFilter.md index 87bd6f5303..2dab7bb50e 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKClosingByReconstructionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKClosingByReconstructionImageFilter.md @@ -1,6 +1,6 @@ # ITK Closing By Reconstruction Image Filter -Closing by reconstruction of an image. +Fills small dark gaps in a grayscale image while preserving the shape of the structures that remain. ## Group (Subgroup) @@ -8,39 +8,40 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -This filter is similar to the morphological closing, but contrary to the morphological closing, the closing by reconstruction preserves the shape of the components. The closing by reconstruction of an image "f" is defined as: +A standard morphological **closing** (dilation followed by erosion) fills in small dark holes and gaps that are smaller than the **structuring element**, but it also distorts the shapes of the larger features it touches. **Closing by reconstruction** achieves the same hole-filling effect while preserving the exact shape of the structures, by replacing the final erosion with a morphological reconstruction step. -ClosingByReconstruction(f) = ErosionByReconstruction(f, Dilation(f)). +It is defined as `ClosingByReconstruction(f) = ErosionByReconstruction(Dilation(f))`. In addition to filling small dark gaps, the operation tends to raise the contrast of the darkest regions. -Closing by reconstruction not only preserves structures preserved by the dilation, but also levels raises the contrast of the darkest regions. If PreserveIntensities is on, a subsequent reconstruction by dilation using a marker image that is the original image for all unaffected pixels. +### Parameter Guidance -Closing by reconstruction is described in Chapter 6.3.9 of Pierre Soille's book "Morphological Image Analysis: Principles and -Applications", Second Edition, Springer, 2003. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Dark gaps smaller than this are filled. +- **Fully Connected** — controls neighbor connectivity during reconstruction (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. +- **Preserve Intensities** — when on, pixels that the operation did not need to change are restored to their exact original gray values (rather than the slightly altered values produced internally), so only the filled regions differ from the input. -### Author +#### Kernel Type - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. - -### Related Filters - -- GrayscaleMorphologicalClosingImageFilter - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. Compare with the standard [ITK Grayscale Morphological Closing Image Filter](ITKGrayscaleMorphologicalClosingImageFilter.md). + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 6.3.9). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKConnectedComponentImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKConnectedComponentImageFilter.md index 74ffc6b812..55b187bc41 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKConnectedComponentImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKConnectedComponentImageFilter.md @@ -1,6 +1,6 @@ # ITK Connected Component Image Filter -Label the objects in a binary image. +Labels each connected object in a binary image with a unique integer. ## Group (Subgroup) @@ -8,13 +8,19 @@ ITKConnectedComponents (ConnectedComponents) ## Description -ConnectedComponentImageFilter labels the objects in a binary image (non-zero pixels are considered to be objects, zero-valued pixels are considered to be background). Each distinct object is assigned a unique label. The filter experiments with some improvements to the existing implementation, and is based on run length encoding along raster lines. If the output background value is set to zero (the default), the final object labels start with 1 and are consecutive. If the output background is set to a non-zero value (by calling the SetBackgroundValue() routine of the filter), the final labels start at 0, and remain consecutive except for skipping the background value as needed. Objects that are reached earlier by a raster order scan have a lower label. This is different to the behaviour of the original connected component image filter which did not produce consecutive labels or impose any particular ordering. +This filter performs **connected components** labeling: it labels each group of touching non-zero pixels with a unique consecutive integer (0 = background). Non-zero pixels are treated as object material and zero-valued pixels as background. Every distinct touching cluster of object pixels receives its own integer label, so the output is a **label image** (one where each region has a unique integer value). -After the filter is executed, ObjectCount holds the number of connected components. +Labels are assigned consecutively starting at 1, with no gaps. The label numbers follow the raster scan order in which objects are first encountered, so the assigned numbers carry no meaning beyond identity. To order the labels by object size instead, pass the output to the [ITK Relabel Component Image Filter](ITKRelabelComponentImageFilter.md), which renumbers them so that label 1 is the largest object. -## See Also +Use this filter when you have a thresholded (binary) image and need to identify and count the individual objects within it. -- [ImageToImageFilter](https://itk.org/Doxygen/html/classitk_1_1ImageToImageFilter.html) +### Parameter Guidance + +- **Fully Connected** — controls connectivity. *Off* uses face-only connectivity (pixels touch only across shared faces). *On* uses face+edge+corner connectivity, so objects that touch only diagonally are merged into one. Turn this *On* for objects that are 1 pixel wide or that connect along diagonals. + +### Required Input Sources + +A binary image (cell data on an **Image Geometry**) where object pixels are non-zero and background pixels are zero, typically produced by a thresholding filter. % Auto generated parameter table will be inserted here @@ -22,8 +28,8 @@ After the filter is executed, ObjectCount holds the number of connected componen ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKCosImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKCosImageFilter.md index ba82c3a179..8c3fd00079 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKCosImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKCosImageFilter.md @@ -8,16 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -This filter is templated over the pixel type of the input image and the pixel type of the output image. - -The filter walks over all of the pixels in the input image, and for each pixel does the following: - -- cast the pixel value to double , -- apply the std::cos() function to the double value, -- cast the double value resulting from std::cos() to the pixel type of the output image, -- store the cast value into the output image. - -The filter expects both images to have the same dimension (e.g. both 2D, or both 3D, or both ND) +Computes the cosine of each pixel. Pixel values are interpreted as radians; the output is in the range [-1, 1]. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -25,7 +16,7 @@ The filter expects both images to have the same dimension (e.g. both 2D, or both ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKCurvatureAnisotropicDiffusionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKCurvatureAnisotropicDiffusionImageFilter.md index 311bfcc6d3..769368248b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKCurvatureAnisotropicDiffusionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKCurvatureAnisotropicDiffusionImageFilter.md @@ -1,6 +1,6 @@ # ITK Curvature Anisotropic Diffusion Image Filter -This filter performs anisotropic diffusion on a scalar itk::Image using the modified curvature diffusion equation (MCDE). +Edge-preserving smoothing that blurs within regions but not across edges, using the modified curvature diffusion equation (MCDE). ## Group (Subgroup) @@ -8,31 +8,27 @@ ITKAnisotropicSmoothing (AnisotropicSmoothing) ## Description -For detailed information on anisotropic diffusion and the MCDE see itkAnisotropicDiffusionFunction and itkCurvatureNDAnisotropicDiffusionFunction. +**Anisotropic diffusion** is an edge-preserving smoothing technique. Ordinary (Gaussian) blurring smooths everywhere equally and washes out edges. Anisotropic diffusion instead smooths strongly inside uniform regions but weakly across boundaries, so noise is reduced while real edges stay sharp. The image is evolved over a number of small time steps, as if heat were diffusing through it but slowed down wherever the image changes rapidly. -## Parameter Information +This filter uses the **modified curvature diffusion equation (MCDE)**, a variant that tends to preserve fine, high-curvature detail better than the plain gradient-based formulation (see [ITK Gradient Anisotropic Diffusion Image Filter](ITKGradientAnisotropicDiffusionImageFilter.md) for the classic Perona-Malik version). -The input and output to this filter must be a scalar itk::Image with numerical pixel types (float or double). A user defined type which correctly defines arithmetic operations with floating point accuracy should also give correct results. +The input and output must be a scalar image with a floating-point pixel type (float or double). -Please first read all the documentation found in [AnisotropicDiffusionImageFilter](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) and [AnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionFunction.html). Also see CurvatureNDAnisotropicDiffusionFunction. +### Parameter Guidance -- Set/GetNumberOfIterations specifies the number of iterations (time-step updates) that the solver will perform to produce a solution image. The appropriate number of iterations is dependent on the application and the image being processed. As a general rule, the more iterations performed, the more diffused the image will become. +- **Number Of Iterations** — how many diffusion time steps to apply. More iterations produce a more strongly smoothed result. The right number depends on the image and the amount of noise; start small and increase as needed. +- **Time Step** — the size of each diffusion step (dimensionless). It must stay below a stability limit that depends on image dimensionality: for unit pixel spacing, stable values are below **0.125** for 2D and below **0.0625** for 3D images. The filter clamps an unstable value and issues a run-time warning. The default (0.0625) is the maximum theoretically stable value for 3D. +- **Conductance Parameter** — controls how strongly edges are preserved. **Lower values preserve features more strongly** (less diffusion across high-gradient regions); higher values let the filter smooth across features more readily. Typical values range from **0.5 to 2.0**; the best value depends on the data and the iteration count. +- **Conductance Scaling Update Interval** — how often (in iterations) the internal conductance term is recomputed. The default of *1* updates it every iteration; larger values update less frequently and run slightly faster at some cost in accuracy. -- Set/GetTimeStep: In the anisotropic diffusion filter hierarchy, the time step is set explicitly by the user. The time step referred to here corresponds exactly to Δ𝑡 in the finite difference update equation described in FiniteDifferenceImageFilter (see itkFiniteDifferenceImageFilter for more information). Appropriate time steps for solving this type of p.d.e. depend on the dimensionality of the image and the order of the equation. Stable values for most 2D and 3D functions are 0.125 and 0.0625, respectively, when the pixel spacing is unity or is turned off. In general, you should keep the time step below (PixelSpacing)/2𝑁+1, where 𝑁 is the number of image dimensions. A filter will automatically attempt to constrain its time step to a stable value and generate a run-time warning if the time step is set too high. +### Required Input Sources -- Set/GetConductanceParameter: The conductance parameter controls the sensitivity of the conductance term in the basic anisotropic diffusion equation. It affects the conductance term in different ways depending on the particular variation on the basic equation. As a general rule, the lower the value, the more strongly the diffusion equation preserves image features (such as high gradients or curvature). A high value for conductance will cause the filter to diffuse image features more readily. Typical values range from 0.5 to 2.0 for data like the Visible Human color data, but the correct value for your application is wholly dependent on the results you want from a specific data set and the number or iterations you perform. - -[More information about AnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionFunction.html) - -## Default Value Caveats - -The default time step for this filter is set to the maximum theoretically stable value: 0.5 / 2^N, where N is the dimensionality of the image. For a 2D image, this means valid time steps are below 0.1250. For a 3D image, valid time steps are below 0.0625. +Operates on any scalar (floating-point) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. ## See Also -- [AnisotropicDiffusionImageFilter](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) -- [AnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionFunction.html) -- [CurvatureNDAnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1CurvatureNDAnisotropicDiffusionFunction.html) +- [ITK AnisotropicDiffusionImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) +- [ITK CurvatureNDAnisotropicDiffusionFunction (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1CurvatureNDAnisotropicDiffusionFunction.html) % Auto generated parameter table will be inserted here @@ -40,8 +36,8 @@ The default time step for this filter is set to the maximum theoretically stable ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKCurvatureFlowImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKCurvatureFlowImageFilter.md index 70f91fcaf2..d4dd4e0930 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKCurvatureFlowImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKCurvatureFlowImageFilter.md @@ -1,6 +1,6 @@ # ITK Curvature Flow Image Filter -Denoise an image using curvature driven flow. +Edge-preserving denoising that smooths an image by moving its intensity contours according to their curvature. ## Group (Subgroup) @@ -8,25 +8,20 @@ ITKCurvatureFlow (CurvatureFlow) ## Description -CurvatureFlowImageFilter implements a curvature driven image denoising algorithm. Iso-brightness contours in the grayscale input image are viewed as a level set. The level set is then evolved using a curvature-based speed function: +**Curvature flow** is an edge-preserving smoothing method. The grayscale image is treated as a stack of iso-intensity contours (lines of constant brightness, like the contour lines on a topographic map). Each contour is then moved at a speed proportional to its local curvature: tightly curved, wiggly parts of a contour (typically noise) move quickly and flatten out, while straight, low-curvature parts (typically real boundaries) barely move. The result is that small noise is smoothed away while sharp edges are preserved. - \f[ I_t = \kappa |\nabla I| \f] where \f$ \kappa \f$ is the curvature. +The evolution is applied over a number of small time steps. Note that applying too many iterations eventually shrinks every contour to nothing and erases all detail, so the iteration count should be tuned to the image. -The advantage of this approach is that sharp boundaries are preserved with smoothing occurring only within a region. However, it should be noted that continuous application of this scheme will result in the eventual removal of all information as each contour shrinks to zero and disappear. +A faster, scale-selective variant is available in [ITK Min Max Curvature Flow Image Filter](ITKMinMaxCurvatureFlowImageFilter.md). The output pixels are of a floating-point type. -Note that unlike level set segmentation algorithms, the image to be denoised is already the level set and can be set directly as the input using the SetInput() method. +### Parameter Guidance -This filter has two parameters: the number of update iterations to be performed and the timestep between each update. +- **Number Of Iterations** — how many time steps to apply. More iterations smooth more strongly; too many erase real features. +- **Time Step** — the size of each step (dimensionless). It must be small enough for numerical stability (each contour should move less than one grid cell per step). As a practical starting point use values around **0.125 for 2D** and **0.0625 for 3D** images and reduce if the result looks unstable. (Default 0.05.) -The timestep should be "small enough" to ensure numerical stability. Stability is guarantee when the timestep meets the CFL (Courant-Friedrichs-Levy) condition. Broadly speaking, this condition ensures that each contour does not move more than one grid position at each timestep. In the literature, the timestep is typically user specified and have to manually tuned to the application. +### Required Input Sources -This filter make use of the multi-threaded finite difference solver hierarchy. Updates are computed using a CurvatureFlowFunction object. A zero flux Neumann boundary condition when computing derivatives near the data boundary. - -This filter may be streamed. To support streaming this filter produces a padded output which takes into account edge effects. The size of the padding is m_NumberOfIterations on each edge. Users of this filter should only make use of the center valid central region. - -## Warning - -This filter assumes that the input and output types have the same dimensions. This filter also requires that the output image pixels are of a floating point type. This filter works for any dimensional images. +Operates on any scalar (floating-point) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. ## Reference @@ -34,14 +29,8 @@ This filter assumes that the input and output types have the same dimensions. Th ## See Also -- [DenseFiniteDifferenceImageFilter](https://itk.org/Doxygen/html/classitk_1_1DenseFiniteDifferenceImageFilter.html) - -- [CurvatureFlowFunction](https://itk.org/Doxygen/html/classitk_1_1CurvatureFlowFunction.html) - -- [MinMaxCurvatureFlowImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinMaxCurvatureFlowImageFilter.html) - -- [BinaryMinMaxCurvatureFlowImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryMinMaxCurvatureFlowImageFilter.html) - +- [ITK CurvatureFlowImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1CurvatureFlowImageFilter.html) +- [ITK Min Max Curvature Flow Image Filter](ITKMinMaxCurvatureFlowImageFilter.md) % Auto generated parameter table will be inserted here @@ -49,8 +38,8 @@ This filter assumes that the input and output types have the same dimensions. Th ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKDanielssonDistanceMapImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKDanielssonDistanceMapImageFilter.md index 8cce37c467..9eba4f3cde 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKDanielssonDistanceMapImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKDanielssonDistanceMapImageFilter.md @@ -1,6 +1,6 @@ # ITK Danielsson Distance Map Image Filter -This filter computes the distance map of the input image as an approximation with pixel accuracy to the Euclidean distance. +Computes a near-Euclidean distance map of an image, with optional Voronoi partition and nearest-object offset map. ## Group (Subgroup) @@ -8,15 +8,32 @@ ITKDistanceMap (DistanceMap) ## Description -The input is assumed to contain numeric codes defining objects. The filter will produce as output the following images: +A **distance map** replaces every pixel with its distance to the nearest object. This filter computes a close approximation to the true Euclidean distance using the Danielsson algorithm, which is fast and accurate to about one pixel. -- A Voronoi partition using the same numeric codes as the input. -- A distance map with the approximation to the euclidean distance. from a particular pixel to the nearest object to this pixel in the input image. -- A vector map containing the component of the vector relating the current pixel with the closest point of the closest object to this pixel. Given that the components of the distance are computed in "pixels", the vector is represented by an itk::Offset. That is, physical coordinates are not used. +The input is treated as a set of labeled objects (any nonzero pixel belongs to an object). The filter can produce three related results: -This filter is N-dimensional and known to be efficient in computational time. The algorithm is the N-dimensional version of the 4SED algorithm given for two dimensions in: +- **Distance map** — each pixel holds the (approximate Euclidean) distance to the nearest object pixel. This is the primary output. +- **Voronoi partition** — a labeling in which every background pixel is assigned the label of the closest object, dividing the image into regions of nearest influence (like territory maps around each object). +- **Offset / vector map** — for each pixel, the displacement (in pixels along each axis) that points from the pixel to its closest object point. This records the direction to the nearest object, not just the distance. -Danielsson, Per-Erik. Euclidean Distance Mapping. Computer Graphics and Image Processing 14, 227-248 (1980). +Use a distance map when you need to know how far each location is from a feature — for example, to find region centers (local distance maxima), to seed a watershed, or to grow regions outward from objects. + +### Parameter Guidance + +- **Input Is Binary** — when enabled, each nonzero input pixel is given a unique code so the Voronoi partition can separate individual objects. Leave it off if your input already carries distinct object labels, or if you do not need per-object Voronoi regions. +- **Squared Distance** — when enabled, the output holds the distance **squared** instead of the distance itself. Squaring avoids a square-root step and keeps integer arithmetic exact, but the output is no longer in linear distance units. Leave off for true distances. +- **Use Image Spacing** — when enabled, distances are measured in the image's **physical units** (using the pixel spacing of the geometry). When disabled, distances are measured in **pixels**. + +### Required Input Sources + +Requires an image whose pixels encode objects (any nonzero value is part of an object; zero is background). This is commonly a segmentation mask or label image produced upstream. + +## See Also + +- [ITK Signed Danielsson Distance Map Image Filter](ITKSignedDanielssonDistanceMapImageFilter.md) +- [ITK Danielsson Distance Map Image Filter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1DanielssonDistanceMapImageFilter.html) + +Reference: Danielsson, Per-Erik. *Euclidean Distance Mapping.* Computer Graphics and Image Processing 14, 227-248 (1980). % Auto generated parameter table will be inserted here @@ -24,8 +41,8 @@ Danielsson, Per-Erik. Euclidean Distance Mapping. Computer Graphics and Image Pr ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKDilateObjectMorphologyImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKDilateObjectMorphologyImageFilter.md index ce7a353371..a67dbab5d9 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKDilateObjectMorphologyImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKDilateObjectMorphologyImageFilter.md @@ -1,6 +1,6 @@ # ITK Dilate Object Morphology Image Filter -dilation of an object in an image +Grows (dilates) a single labeled object in a mask image — a fast single-object variant of binary dilation. ## Group (Subgroup) @@ -8,28 +8,33 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -Dilate an image using binary morphology. Pixel values matching the object value are considered the "foreground" and all other pixels are "background". This is useful in processing mask images containing only one object. +This filter **dilates one object** in a mask image. Pixels whose value equals the *Object Value* are treated as the object (foreground); all other pixels are background. Wherever an object pixel is adjacent to a background pixel, the **structuring element** (the probe shape swept over the image) is centered on the object pixel and the background pixels it covers are set to the object value, growing the object outward. It is intended for masks that contain a single object; to dilate any of several segment values in a general segmented image, use [ITK Binary Dilate Image Filter](ITKBinaryDilateImageFilter.md). -If a pixel's value is equal to the object value and the pixel is adjacent to a non-object valued pixel, then the kernel is centered on the object-value pixel and neighboring pixels covered by the kernel are assigned the object value. The structuring element is assumed to be composed of binary values (zero or one).* ObjectMorphologyImageFilter , ErodeObjectMorphologyImageFilter +### Parameter Guidance -- BinaryDilateImageFilter +- **Object Value** — the pixel value of the object to dilate. Default *1*. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). The object grows by this amount. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on a binary/single-object mask image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKDiscreteGaussianImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKDiscreteGaussianImageFilter.md index 7e7521185e..2eea3b7884 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKDiscreteGaussianImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKDiscreteGaussianImageFilter.md @@ -1,6 +1,6 @@ # ITK Discrete Gaussian Image Filter -Blurs an image by separable convolution with discrete gaussian kernels. This filter performs Gaussian blurring by separable convolution of an image and a discrete Gaussian operator (kernel). +Blurs an image with a Gaussian kernel — the standard linear smoothing/denoising operation. ## Group (Subgroup) @@ -8,18 +8,26 @@ ITKSmoothing (Smoothing) ## Description -The Gaussian operator used here was described by Tony Lindeberg (Discrete Scale-Space Theory and the Scale-Space Primal Sketch. Dissertation. Royal Institute of Technology, Stockholm, Sweden. May 1991.) The Gaussian kernel used here was designed so that smoothing and derivative operations commute after discretization. +This filter applies **Gaussian blurring**: each pixel is replaced by a weighted average of its neighborhood, with the weights following a bell-shaped (Gaussian) curve so nearby pixels count more than distant ones. It is the most common general-purpose smoothing/denoising filter. The blur is performed efficiently as a separable convolution and can be set independently per axis. -The variance or standard deviation (sigma) will be evaluated as pixel units if SetUseImageSpacing is off (false) or as physical units if SetUseImageSpacing is on (true, default). The variance can be set independently in each dimension. +A faster alternative for large blur widths is a recursive-Gaussian (IIR) smoother, whose run time does not grow with the blur size. -When the Gaussian kernel is small, this filter tends to run faster than itk::RecursiveGaussianImageFilter .* GaussianOperator +### Parameter Guidance -- Image -- Neighborhood -- NeighborhoodOperator -- RecursiveGaussianImageFilter +- **Variance** — the blur strength per axis. Note this is the **variance (sigma squared)**, *not* sigma itself — a common point of confusion. Larger values blur more. Units are **pixels²** when *Use Image Spacing* is off, or **physical units²** when it is on. Typical values are around 1.0-4.0 px². +- **Use Image Spacing** — when on (default), the variance is interpreted in the geometry's physical units; when off, in pixels. +- **Maximum Kernel Width** — the largest kernel size, in **pixels**, the filter is allowed to build. It caps memory/time for very large variances. +- **Maximum Error** — the maximum allowed approximation error of the discrete Gaussian (per axis), a small dimensionless tolerance. -![](Images/ITKDiscreteGaussianImageFilter.png) +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +## Reference + +T. Lindeberg, *Discrete Scale-Space Theory and the Scale-Space Primal Sketch*, Dissertation, Royal Institute of Technology, Stockholm, May 1991. + +![Discrete Gaussian blur example.](Images/ITKDiscreteGaussianImageFilter.png) % Auto generated parameter table will be inserted here @@ -27,7 +35,7 @@ When the Gaussian kernel is small, this filter tends to run faster than itk::Rec ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKDoubleThresholdImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKDoubleThresholdImageFilter.md index c67397ddde..524dddda67 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKDoubleThresholdImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKDoubleThresholdImageFilter.md @@ -1,6 +1,6 @@ # ITK Double Threshold Image Filter -Binarize an input image using double thresholding. +Binarizes an image using a hysteresis-style double threshold that keeps the objects of interest without picking up extraneous ones. ## Group (Subgroup) @@ -8,13 +8,20 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Double threshold addresses the difficulty in selecting a threshold that will select the objects of interest without selecting extraneous objects. Double threshold considers two threshold ranges: a narrow range and a wide range (where the wide range encompasses the narrow range). If the wide range was used for a traditional threshold (where values inside the range map to the foreground and values outside the range map to the background), many extraneous pixels may survive the threshold operation. If the narrow range was used for a traditional threshold, then too few pixels may survive the threshold. +Choosing a single threshold is often a compromise: a wide range catches the whole object but also lets in noise and extraneous pixels, while a narrow range rejects the noise but also clips the object. **Double threshold** resolves this with two nested ranges — a **narrow** range that reliably marks only true object pixels, and a **wide** range that captures the full extent of the objects (and some extras). -Double threshold uses the narrow threshold image as a marker image and the wide threshold image as a mask image in the geodesic dilation. Essentially, the marker image (narrow threshold) is dilated but constrained to lie within the mask image (wide threshold). Thus, only the objects of interest (those pixels that survived the narrow threshold) are extracted but the those objects appear in the final image as they would have if the wide threshold was used. -- [GrayscaleGeodesicDilateImageFilter](https://itk.org/Doxygen/html/classitk_1_1GrayscaleGeodesicDilateImageFilter.html) +The filter keeps every object that contains at least one pixel passing the narrow range, and grows it out to its full extent within the wide range (a geodesic dilation of the narrow-range result, constrained to the wide-range mask). The result is that only genuine objects survive, but each appears at the full size it would have had under the wide threshold. -- [MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter ,](https://itk.org/Doxygen/html/classitk_1_1MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter ,.html)BinaryDilateImageFilter +### Parameter Guidance +- **Threshold1, Threshold2, Threshold3, Threshold4** — four bounds, in the **input image's intensity units**, that must be ordered `Threshold1 ≤ Threshold2 ≤ Threshold3 ≤ Threshold4`. They define the **wide** range as `[Threshold1, Threshold4]` and the **narrow** range as `[Threshold2, Threshold3]` inside it. +- **Inside Value** — the output value for pixels that pass (a `uint8` label, default *1*). +- **Outside Value** — the output value for all other pixels (a `uint8` label, default *0*). +- **Fully Connected** — controls neighbor connectivity for the grow step (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -22,8 +29,8 @@ Double threshold uses the narrow threshold image as a marker image and the wide ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKErodeObjectMorphologyImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKErodeObjectMorphologyImageFilter.md index bdf43f1a81..b15d0d0405 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKErodeObjectMorphologyImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKErodeObjectMorphologyImageFilter.md @@ -1,6 +1,6 @@ # ITK Erode Object Morphology Image Filter -Erosion of an object in an image. +Shrinks (erodes) a single labeled object in a mask image — a fast single-object variant of binary erosion. ## Group (Subgroup) @@ -8,28 +8,34 @@ ITKBinaryMathematicalMorphology (BinaryMathematicalMorphology) ## Description -Erosion of an image using binary morphology. Pixel values matching the object value are considered the "object" and all other pixels are "background". This is useful in processing mask images containing only one object. +This filter **erodes one object** in a mask image. Pixels whose value equals the *Object Value* are treated as the object; all other pixels are background. Wherever an object pixel sits at the boundary with background, the **structuring element** (the probe shape swept over the image) is centered on it and the covered neighboring pixels are set to the *Background Value*, shrinking the object inward. It is intended for masks that contain a single object; to erode any of several segment values in a general segmented image, use [ITK Binary Erode Image Filter](ITKBinaryErodeImageFilter.md). -If the pixel covered by the center of the kernel has the pixel value ObjectValue and the pixel is adjacent to a non-object valued pixel, then the kernel is centered on the object-value pixel and neighboring pixels covered by the kernel are assigned the background value. The structuring element is assumed to be composed of binary values (zero or one).* ObjectMorphologyImageFilter , BinaryFunctionErodeImageFilter +### Parameter Guidance -- BinaryErodeImageFilter +- **Object Value** — the pixel value of the object to erode. Default *1*. +- **Background Value** — the value assigned to eroded pixels. Default *0*. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). The object shrinks by this amount. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on a binary/single-object mask image — typically the output of a thresholding filter such as [ITK Binary Threshold Image Filter](ITKBinaryThresholdImageFilter.md) or [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKExpImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKExpImageFilter.md index 144eab40b7..837995148d 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKExpImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKExpImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The computation is performed using std::exp(x). +Computes the natural exponential (e raised to the pixel value) of each pixel. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -16,7 +16,7 @@ The computation is performed using std::exp(x). ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKExpNegativeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKExpNegativeImageFilter.md index d92fe28cca..76bb243fda 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKExpNegativeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKExpNegativeImageFilter.md @@ -1,6 +1,6 @@ # ITK Exp Negative Image Filter -Computes the function exp(-K.x) for each input pixel. +Computes exp(-x) for each input pixel. ## Group (Subgroup) @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -Every output pixel is equal to std::exp(-K.x ). where x is the intensity of the homologous input pixel, and K is a user-provided constant. +Computes the negative natural exponential exp(-x) of each pixel, where x is the input pixel value. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -16,7 +16,7 @@ Every output pixel is equal to std::exp(-K.x ). where x is the intensity of the ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGradientAnisotropicDiffusionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGradientAnisotropicDiffusionImageFilter.md index 7384ed2dbb..1252260976 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGradientAnisotropicDiffusionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGradientAnisotropicDiffusionImageFilter.md @@ -1,6 +1,6 @@ # ITK Gradient Anisotropic Diffusion Image Filter -This filter performs anisotropic diffusion on a scalar itk::Image using the classic Perona-Malik, gradient magnitude based equation. +Edge-preserving smoothing that blurs within regions but not across edges, using the classic Perona-Malik gradient-magnitude equation. ## Group (Subgroup) @@ -8,22 +8,27 @@ ITKAnisotropicSmoothing (AnisotropicSmoothing) ## Description -For detailed information on anisotropic diffusion, see itkAnisotropicDiffusionFunction and itkGradientNDAnisotropicDiffusionFunction. +**Anisotropic diffusion** is an edge-preserving smoothing technique. Ordinary (Gaussian) blurring smooths everywhere equally and washes out edges. Anisotropic diffusion instead smooths strongly inside uniform regions but weakly across boundaries, so noise is reduced while real edges stay sharp. The image is evolved over a number of small time steps, as if heat were diffusing through it but slowed down wherever the image changes rapidly. -## Parameter Information +This filter uses the classic **Perona-Malik** formulation, in which the diffusion at each pixel is throttled by the local **gradient magnitude**: where the gradient is high (an edge), diffusion is suppressed; where the image is flat, diffusion proceeds freely. The closely related [ITK Curvature Anisotropic Diffusion Image Filter](ITKCurvatureAnisotropicDiffusionImageFilter.md) preserves fine detail somewhat better. -The input and output to this filter must be a scalar itk::Image with numerical pixel types (float or double). A user defined type which correctly defines arithmetic operations with floating point accuracy should also give correct results. +The input and output must be a scalar image with a floating-point pixel type (float or double). -Please first read all the documentation found in [AnisotropicDiffusionImageFilter](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) and [AnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionFunction.html). Also see CurvatureNDAnisotropicDiffusionFunction. +### Parameter Guidance -- Set/GetNumberOfIterations specifies the number of iterations (time-step updates) that the solver will perform to produce a solution image. The appropriate number of iterations is dependent on the application and the image being processed. As a general rule, the more iterations performed, the more diffused the image will become. +- **Number Of Iterations** — how many diffusion time steps to apply. More iterations produce a more strongly smoothed result. The right number depends on the image and the amount of noise. +- **Time Step** — the size of each diffusion step (dimensionless). It must stay below a stability limit: for unit pixel spacing, stable values are below **0.125** for 2D and below **0.0625** for 3D images. The filter clamps an unstable value and issues a run-time warning. (Default 0.125.) +- **Conductance Parameter** — controls how strongly edges are preserved. **Lower values preserve features more strongly**; higher values smooth across features more readily. Typical values range from **0.5 to 2.0**; the best value depends on the data and the iteration count. +- **Conductance Scaling Update Interval** — how often (in iterations) the internal conductance term is recomputed. The default of *1* updates it every iteration; larger values update less frequently and run slightly faster at some cost in accuracy. -- Set/GetTimeStep: In the anisotropic diffusion filter hierarchy, the time step is set explicitly by the user. The time step referred to here corresponds exactly to Δ𝑡 in the finite difference update equation described in FiniteDifferenceImageFilter (see itkFiniteDifferenceImageFilter for more information). Appropriate time steps for solving this type of p.d.e. depend on the dimensionality of the image and the order of the equation. Stable values for most 2D and 3D functions are 0.125 and 0.0625, respectively, when the pixel spacing is unity or is turned off. In general, you should keep the time step below (PixelSpacing)/2𝑁+1, where 𝑁 is the number of image dimensions. A filter will automatically attempt to constrain its time step to a stable value and generate a run-time warning if the time step is set too high. +### Required Input Sources -- Set/GetConductanceParameter: The conductance parameter controls the sensitivity of the conductance term in the basic anisotropic diffusion equation. It affects the conductance term in different ways depending on the particular variation on the basic equation. As a general rule, the lower the value, the more strongly the diffusion equation preserves image features (such as high gradients or curvature). A high value for conductance will cause the filter to diffuse image features more readily. Typical values range from 0.5 to 2.0 for data like the Visible Human color data, but the correct value for your application is wholly dependent on the results you want from a specific data set and the number or iterations you perform. +Operates on any scalar (floating-point) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -[AnisotropicDiffusionImageFilter](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) -[AnisotropicDiffusionFunction](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionFunction.html) +## See Also + +- [ITK AnisotropicDiffusionImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1AnisotropicDiffusionImageFilter.html) +- [ITK GradientNDAnisotropicDiffusionFunction (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1GradientNDAnisotropicDiffusionFunction.html) % Auto generated parameter table will be inserted here @@ -31,8 +36,8 @@ Please first read all the documentation found in [AnisotropicDiffusionImageFilte ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeImageFilter.md index f6f5732d3f..5773528f78 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeImageFilter.md @@ -1,6 +1,6 @@ # ITK Gradient Magnitude Image Filter -Computes the gradient magnitude of an image region at each pixel. +Computes the gradient magnitude (edge strength) of an image at each pixel. ## Group (Subgroup) @@ -8,14 +8,15 @@ ITKImageGradient (ImageGradient) ## Description -Computes the gradient magnitude of an image region at each pixel. +The gradient magnitude is the length of the local intensity gradient vector — large where the image changes rapidly (edges) and near zero in smooth regions. This filter estimates it directly from simple finite differences between neighboring pixels, which makes it fast but sensitive to noise; for noisy data prefer the smoothed variant [ITK Gradient Magnitude Recursive Gaussian Image Filter](ITKGradientMagnitudeRecursiveGaussianImageFilter.md), which blurs with a Gaussian before differentiating. -### Related Filters +### Parameter Guidance -- Image -- Neighborhood -- NeighborhoodOperator -- NeighborhoodIterator +- **Use Image Spacing**: When on (default), derivatives are computed in physical space using the image spacing, giving results in intensity units per physical length unit. When off, spacing is ignored and the gradient is computed in isotropic voxel space. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -23,7 +24,7 @@ Computes the gradient magnitude of an image region at each pixel. ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeRecursiveGaussianImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeRecursiveGaussianImageFilter.md index 9a0b2c2d07..6e586deee7 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeRecursiveGaussianImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGradientMagnitudeRecursiveGaussianImageFilter.md @@ -1,6 +1,6 @@ # ITK Gradient Magnitude Recursive Gaussian Image Filter -Computes the Magnitude of the Gradient of an image by convolution with the first derivative of a Gaussian. +Computes the gradient magnitude (edge strength) of an image after Gaussian smoothing. ## Group (Subgroup) @@ -8,38 +8,29 @@ ITKImageGradient (ImageGradient) ## Description -This filter is implemented using the recursive gaussian filters +The **gradient magnitude** measures how fast intensity changes at each pixel — it is high along edges and near zero in flat regions, so the output is an edge-strength image. This filter first smooths the image with a Gaussian and then takes the gradient, combining the two steps so that the smoothing scale is controlled directly. Smoothing suppresses noise, so edges are detected more reliably than with a raw (un-smoothed) gradient. -## Parameters +The amount of smoothing is set by *Sigma*: a small *Sigma* responds to fine, sharp edges; a large *Sigma* blurs away fine detail and responds only to broad, large-scale edges. -| Name | Type | Description | -|------|------|-------------| -| Sigma | float64 | Set/Get Sigma value. Sigma is measured in the units of image spacing. | -| NormalizeAcrossScale | bool | Set/Get the normalization factor that will be used for the Gaussian. \sa RecursiveGaussianImageFilter::SetNormalizeAcrossScale | +Use this filter to produce an edge-strength map for edge detection, segmentation seeding (for example, as a speed image for level sets), or feature extraction. -## Required Geometry +### Parameter Guidance -Image Geometry +- **Sigma** — the standard deviation (width) of the Gaussian smoothing kernel, measured in **image-spacing (physical) units**, not pixels. For example, with a pixel spacing of 0.5 µm, a *Sigma* of *1.0* corresponds to 2 pixels. Larger values smooth more and detect broader edges. +- **Normalize Across Scale** — controls how the response is scaled when *Sigma* changes. Leave this off for ordinary edge detection. Enable it only when you compare gradient magnitudes computed at several different *Sigma* values (multi-scale analysis), so that the strongest response is not simply the smallest *Sigma*. -## Required Objects +### Required Input Sources -| Name |Type | Description | -|-----|------|-------------| -| Input Image Geometry | DataPath | DataPath to the Input Image Geometry | -| Input Image Data Array | DataPath | Path to input image with pixel type matching BasicPixelIDTypeList | +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -## Created Objects - -| Name |Type | Description | -|-----|------|-------------| -| Output Image Data Array | DataPath | Path to output image with pixel type matching BasicPixelIDTypeList | +% Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleDilateImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleDilateImageFilter.md index e61434623f..e59788185a 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleDilateImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleDilateImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Dilate Image Filter -Grayscale dilation of an image. +Replaces each pixel with the maximum value in its neighborhood — a grayscale dilation that brightens the image and grows bright regions. ## Group (Subgroup) @@ -8,28 +8,34 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Dilate an image using grayscale morphology. Dilation takes the maximum of all the pixels identified by the structuring element. +Grayscale **dilation** replaces each pixel with the **maximum** value found within the neighborhood defined by the **structuring element** (the probe shape — ball, box, etc. — swept over the image). The effect is to brighten the image, grow bright regions, and shrink dark ones. It is the grayscale counterpart of binary dilation and the building block of grayscale opening, closing, and top-hat filters. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel.* MorphologyImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +### Parameter Guidance -![](Images/ITKGrayscaleDilation.png) +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Larger radii grow bright regions more. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Grayscale dilation example.](Images/ITKGrayscaleDilation.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleErodeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleErodeImageFilter.md index 31878bc9ab..afe22e6dc0 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleErodeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleErodeImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Erode Image Filter -Grayscale erosion of an image. +Replaces each pixel with the minimum value in its neighborhood — a grayscale erosion that darkens the image and grows dark regions. ## Group (Subgroup) @@ -8,28 +8,34 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Erode an image using grayscale morphology. Erosion takes the maximum of all the pixels identified by the structuring element. +Grayscale **erosion** replaces each pixel with the **minimum** value found within the neighborhood defined by the **structuring element** (the probe shape — ball, box, etc. — swept over the image). The effect is to darken the image, grow dark regions, and shrink bright ones. It is the grayscale counterpart of binary erosion and the dual of [ITK Grayscale Dilate Image Filter](ITKGrayscaleDilateImageFilter.md). -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel.* MorphologyImageFilter , GrayscaleFunctionErodeImageFilter , BinaryErodeImageFilter +### Parameter Guidance -![](Images/ITKGrayscaleErosion.png) +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Larger radii grow dark regions more. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Grayscale erosion example.](Images/ITKGrayscaleErosion.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleFillholeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleFillholeImageFilter.md index 0e63ff7d3f..2bfe372366 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleFillholeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleFillholeImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Fillhole Image Filter -Remove local minima not connected to the boundary of the image. +Fills dark "holes" in a grayscale image — enclosed dark spots that are not connected to the image border. ## Group (Subgroup) @@ -8,18 +8,23 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -GrayscaleFillholeImageFilter fills holes in a grayscale image. Holes are local minima in the grayscale topography that are not connected to boundaries of the image. Gray level values adjacent to a hole are extrapolated across the hole. +This filter fills **holes** in a grayscale image. A hole is a local minimum (a dark spot) that is fully enclosed by brighter pixels and not connected to the image border. The filter raises each hole up to the gray level of the surrounding pixels, smoothing over dark spots while leaving bright features (local maxima) untouched. -This filter is used to smooth over local minima without affecting the values of local maxima. If you take the difference between the output of this filter and the original image (and perhaps threshold the difference above a small value), you'll obtain a map of the local minima. +A useful trick: subtract the original image from this filter's output (and optionally threshold the difference) to obtain a map of the dark spots that were filled. The dual operation, which removes bright peaks instead, is [ITK Grayscale Grind Peak Image Filter](ITKGrayscaleGrindPeakImageFilter.md). -This filter uses the ReconstructionByErosionImageFilter . It provides its own input as the "mask" input to the geodesic erosion. The "marker" image for the geodesic erosion is constructed such that boundary pixels match the boundary pixels of the input image and the interior pixels are set to the maximum pixel value in the input image. +### Parameter Guidance -Geodesic morphology and the Fillhole algorithm is described in Chapter 6 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003.* ReconstructionByErosionImageFilter +- **Fully Connected** — controls neighbor connectivity when deciding whether a region is "enclosed" (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide structures. -- MorphologyImageFilter , GrayscaleErodeImageFilter , GrayscaleFunctionErodeImageFilter , BinaryErodeImageFilter +### Required Input Sources -![](Images/ITKGrayscaleFillHole.png) +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Grayscale fill-hole example.](Images/ITKGrayscaleFillHole.png) + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 6). % Auto generated parameter table will be inserted here @@ -27,7 +32,7 @@ Principles and Applications", Second Edition, Springer, 2003.* ReconstructionByE ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleGrindPeakImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleGrindPeakImageFilter.md index da79a72695..810d64fd9c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleGrindPeakImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleGrindPeakImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Grind Peak Image Filter -Remove local maxima not connected to the boundary of the image. +Removes bright "peaks" from a grayscale image — enclosed bright spots that are not connected to the image border. ## Group (Subgroup) @@ -8,20 +8,23 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -GrayscaleGrindPeakImageFilter removes peaks in a grayscale image. Peaks are local maxima in the grayscale topography that are not connected to boundaries of the image. Gray level values adjacent to a peak are extrapolated through the peak. +This filter removes **peaks** in a grayscale image. A peak is a local maximum (a bright spot) that is fully enclosed by darker pixels and not connected to the image border. The filter lowers each peak down to the gray level of the surrounding pixels, smoothing over bright spots while leaving dark features (local minima) untouched. It is the exact dual of [ITK Grayscale Fillhole Image Filter](ITKGrayscaleFillholeImageFilter.md). -This filter is used to smooth over local maxima without affecting the values of local minima. If you take the difference between the output of this filter and the original image (and perhaps threshold the difference above a small value), you'll obtain a map of the local maxima. +A useful trick: subtract this filter's output from the original image (and optionally threshold the difference) to obtain a map of the bright spots that were removed. -This filter uses the GrayscaleGeodesicDilateImageFilter . It provides its own input as the "mask" input to the geodesic erosion. The "marker" image for the geodesic erosion is constructed such that boundary pixels match the boundary pixels of the input image and the interior pixels are set to the minimum pixel value in the input image. +### Parameter Guidance -This filter is the dual to the GrayscaleFillholeImageFilter which implements the Fillhole algorithm. Since it is a dual, it is somewhat superfluous but is provided as a convenience. +- **Fully Connected** — controls neighbor connectivity when deciding whether a region is "enclosed" (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide structures. -Geodesic morphology and the Fillhole algorithm is described in Chapter 6 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesicDilateImageFilter +### Required Input Sources -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -![](Images/ITKGrayscaleGrindPeak.png) +![Grayscale grind-peak example.](Images/ITKGrayscaleGrindPeak.png) + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 6). % Auto generated parameter table will be inserted here @@ -29,7 +32,7 @@ Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesic ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalClosingImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalClosingImageFilter.md index c63276080c..232476e48e 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalClosingImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalClosingImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Morphological Closing Image Filter -Grayscale closing of an image. +Fills small dark features in a grayscale image (a grayscale dilation followed by an erosion). ## Group (Subgroup) @@ -8,28 +8,35 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Close an image using grayscale morphology. +Grayscale **closing** is a **dilation followed by an erosion** using the same structuring element. It removes small **dark** features — narrow dark gaps, thin dark lines, and small dark spots smaller than the **structuring element** (the probe shape swept over the image) — while leaving the overall brightness and larger structures essentially unchanged. The dual operation, [ITK Grayscale Morphological Opening Image Filter](ITKGrayscaleMorphologicalOpeningImageFilter.md), removes small bright features instead. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel.* MorphologyImageFilter , GrayscaleFunctionErodeImageFilter , BinaryErodeImageFilter +### Parameter Guidance -![](Images/ITKGrayscaleClosing.png) +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Dark features smaller than this are removed. +- **Safe Border** — when on (default), a temporary border is added during processing to avoid edge artifacts and removed afterward. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Grayscale closing example.](Images/ITKGrayscaleClosing.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalOpeningImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalOpeningImageFilter.md index 606e5dcf77..7a39757672 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalOpeningImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKGrayscaleMorphologicalOpeningImageFilter.md @@ -1,6 +1,6 @@ # ITK Grayscale Morphological Opening Image Filter -Grayscale opening of an image. +Removes small bright features from a grayscale image (a grayscale erosion followed by a dilation). ## Group (Subgroup) @@ -8,28 +8,35 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Open an image using grayscale morphology. +Grayscale **opening** is an **erosion followed by a dilation** using the same structuring element. It removes small **bright** features — small bright spots, thin bright lines, and narrow bright protrusions smaller than the **structuring element** (the probe shape swept over the image) — while leaving the overall brightness and larger structures essentially unchanged. The dual operation, [ITK Grayscale Morphological Closing Image Filter](ITKGrayscaleMorphologicalClosingImageFilter.md), removes small dark features instead. -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel.* MorphologyImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +### Parameter Guidance -![](Images/ITKGrayscaleOpening.png) +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Bright features smaller than this are removed. +- **Safe Border** — when on (default), a temporary border is added during processing to avoid edge artifacts and removed afterward. -### Kernel Type +#### Kernel Type -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Grayscale opening example.](Images/ITKGrayscaleOpening.png) + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKHConvexImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKHConvexImageFilter.md index 2dcc59457f..2e52ff1ae5 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKHConvexImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKHConvexImageFilter.md @@ -1,6 +1,6 @@ # ITK H Convex Image Filter -Identify local maxima whose height above the baseline is greater than h. +Extracts bright peaks (local maxima) that rise more than a height *h* above their surroundings. ## Group (Subgroup) @@ -8,14 +8,18 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -HConvexImageFilter extract local maxima that are more than h intensity units above the (local) background. This has the effect of extracting objects that are brighter than background by at least h intensity units. +The **H-Convex** transform isolates the prominent peaks in a grayscale image. It keeps only those local maxima whose **prominence — their height above the local background — is greater than *h***, and reports each peak's prominence (up to *h*) while flattening everything else toward zero. In other words, it extracts objects that are brighter than their surroundings by at least *h* intensity units. -This filter uses the HMaximaImageFilter . +Use this filter to detect or enhance bright blobs, spots, or particles on an uneven background. Because it measures prominence rather than absolute brightness, it finds peaks consistently even when the background level drifts across the image. -Geodesic morphology and the H-Convex algorithm is described in Chapter 6 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesicDilateImageFilter , HMinimaImageFilter +### Parameter Guidance -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +- **Height** — the height *h*, in the **input image's intensity units**. It sets the minimum peak prominence: only maxima that rise more than *h* above their local background are extracted; shallower bumps are suppressed. Larger values keep only the most prominent peaks. Default *2.0*. +- **Fully Connected** — controls pixel connectivity. When off (default), neighbors share a face; when on, neighbors also include edge- and corner-touching pixels. Turn it on for thin, one-pixel-wide features. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -23,7 +27,7 @@ Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesic ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKHMaximaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKHMaximaImageFilter.md index 8a6fa48766..aa5afea06c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKHMaximaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKHMaximaImageFilter.md @@ -1,6 +1,6 @@ # ITK H Maxima Image Filter -Suppress local maxima whose height above the baseline is less than h. +Flattens shallow bright peaks by suppressing local maxima whose height is less than *h*. ## Group (Subgroup) @@ -8,18 +8,17 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -HMaximaImageFilter suppresses local maxima that are less than h intensity units above the (local) background. This has the effect of smoothing over the "high" parts of the noise in the image without smoothing over large changes in intensity (region boundaries). See the HMinimaImageFilter to suppress the local minima whose depth is less than h intensity units below the (local) background. +The **H-Maxima** transform removes insignificant bright peaks from a grayscale image. Any local maximum that rises **less than *h* above its local background** is suppressed — flattened down to an estimate of that background — while larger, genuine peaks are preserved. This smooths over the "high" parts of the noise without blurring real region boundaries or large intensity changes. -If the output of HMaximaImageFilter is subtracted from the original image, the significant "peaks" in the image can be identified. This is what the HConvexImageFilter provides. +Use this filter to clean up speckle and spurious bright spots before segmentation, or as a preconditioning step for peak/maxima detection. Subtracting this filter's output from the original image yields the prominent peaks themselves (the operation performed by the [H Convex](ITKHConvexImageFilter.md) filter); the complementary operation for dark features is the [H Minima](ITKHMinimaImageFilter.md) filter. -This filter uses the ReconstructionByDilationImageFilter . It provides its own input as the "mask" input to the geodesic dilation. The "marker" image for the geodesic dilation is the input image minus the height parameter h. +### Parameter Guidance -Geodesic morphology and the H-Maxima algorithm is described in Chapter 6 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003. +- **Height** — the height *h*, in the **input image's intensity units**. Maxima that rise less than *h* above their local background are suppressed; peaks taller than *h* survive. Larger values flatten more peaks. Default *2.0*. -The height parameter is set using SetHeight.* ReconstructionByDilationImageFilter , HMinimaImageFilter , HConvexImageFilter +### Required Input Sources -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -27,7 +26,7 @@ The height parameter is set using SetHeight.* ReconstructionByDilationImageFilte ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKHMinimaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKHMinimaImageFilter.md index 5486e8a7df..3078492d08 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKHMinimaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKHMinimaImageFilter.md @@ -1,6 +1,6 @@ # ITK H Minima Image Filter -Suppress local minima whose depth below the baseline is less than h. +Fills shallow dark valleys by suppressing local minima whose depth is less than *h*. ## Group (Subgroup) @@ -8,16 +8,18 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -HMinimaImageFilter suppresses local minima that are less than h intensity units below the (local) background. This has the effect of smoothing over the "low" parts of the noise in the image without smoothing over large changes in intensity (region boundaries). See the HMaximaImageFilter to suppress the local maxima whose height is less than h intensity units above the (local) background. +The **H-Minima** transform removes insignificant dark dips from a grayscale image. Any local minimum that lies **less than *h* below its local background** is filled in — raised to an estimate of that background — while deeper, genuine valleys are preserved. This smooths over the "low" parts of the noise without blurring real region boundaries or large intensity changes. -If original image is subtracted from the output of HMinimaImageFilter , the significant "valleys" in the image can be identified. This is what the HConcaveImageFilter provides. +Use this filter to clean up dark speckle and spurious low spots before segmentation, or as a preconditioning step for minima detection (for example to control over-segmentation in a watershed). It is the dark-feature counterpart of the [H Maxima](ITKHMaximaImageFilter.md) filter; the matching operation that *extracts* prominent bright peaks is the [H Convex](ITKHConvexImageFilter.md) filter. -This filter uses the GrayscaleGeodesicErodeImageFilter . It provides its own input as the "mask" input to the geodesic dilation. The "marker" image for the geodesic dilation is the input image plus the height parameter h. +### Parameter Guidance -Geodesic morphology and the H-Minima algorithm is described in Chapter 6 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesicDilateImageFilter , HMinimaImageFilter , HConvexImageFilter +- **Height** — the depth *h*, in the **input image's intensity units**. Minima that lie less than *h* below their local background are filled; valleys deeper than *h* survive. Larger values fill more dips. Default *2.0*. +- **Fully Connected** — controls pixel connectivity. When off (default), neighbors share a face; when on, neighbors also include edge- and corner-touching pixels. Turn it on for thin, one-pixel-wide features. -- MorphologyImageFilter , GrayscaleDilateImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -25,7 +27,7 @@ Principles and Applications", Second Edition, Springer, 2003.* GrayscaleGeodesic ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKImageReaderFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKImageReaderFilter.md index 14a0f1010c..1f49d64a71 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKImageReaderFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKImageReaderFilter.md @@ -1,6 +1,6 @@ # Read Image (ITK) -This filter directly wraps an ITK filter of the same name. +Reads a single image file into a new Image Geometry using the ITK software library. ## Group (Subgroup) @@ -10,6 +10,8 @@ ITKImageProcessing (ITKImageProcessing) Reads images through the ITK software library [https://www.itk.org](https://www.itk.org) +This filter shares its human name with the SimplnxCore [Read Image](../SimplnxCore/ReadImageFilter.md) filter. This ITK-based variant supports additional file formats (such as NRRD and MHA) and provides ITK-driven decoding; if you only need common 2D formats, the SimplnxCore filter may be sufficient. + The following image types are supported: - PNG diff --git a/src/Plugins/ITKImageProcessing/docs/ITKImportFijiMontageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKImportFijiMontageFilter.md index c994ebc873..f84eb042bd 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKImportFijiMontageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKImportFijiMontageFilter.md @@ -1,16 +1,31 @@ # Read Fiji Montage (ITK) +Imports a set of overlapping tile images described by a Fiji/ImageJ TileConfiguration file, placing each tile in its own data group for later montage assembly. + ## Group (Subgroup) IO (Input) ## Description -Imports multiple images for the purpose of montage assembly. Each image is stored in it's own *DataContaner/AttributeMatrix/AttributeArray* where the name of the *DataContainer* is based off the row & column index of the montage. The filter assumes that the Configuration File is in the same folder as the images. The created *AttributeMatrix* and *AttributeArray* will have the same name. The image files **MUST** be located in the same directory as the Fiji Configuration File. +This filter reads a Fiji/ImageJ *TileConfiguration* file and imports the overlapping tile images it references so they can later be assembled into a single montage. The configuration file lists each tile image along with the coordinate at which it belongs in the mosaic. The image files **must** be located in the same directory as the configuration file. + +Each tile is imported into its own **Image Geometry**, named using the *Image Geometry Prefix* followed by the tile's file name. Inside each Image Geometry, the pixel data is stored in a **Cell Attribute Matrix** group, which holds the image **Data Array**. If *Parent Imported Images Under a DataGroup* is enabled, all of these per-tile Image Geometries are placed under a single parent **DataGroup** so they are grouped together in the DataStructure. + +Use this filter as the first step in a montage-stitching workflow when your tiles are described by a Fiji TileConfiguration file. + +### Parameter Guidance -Utilizes the *itkReadImage* and *ColorToGrayScale* filters +- **Change Origin** / **Origin** — when enabled, overrides the origin of the assembled mosaic with the user-supplied value (in the chosen length unit). +- **Convert To GrayScale** / **Color Weighting** — when enabled, converts color tiles to grayscale using a weighted (luminosity) average of the red, green, and blue channels. The default weights are the BT.709 values *Red 0.2125, Green 0.7154, Blue 0.0721*, which approximate human brightness perception (the eye is most sensitive to green). The weights can be changed to any values. The incoming color array must be 8-bit unsigned (uint8); otherwise that image is skipped. +- **Set Image Data Type** / **Output Data Type** — when enabled, stores the imported pixel data using the chosen numeric type (uint8, uint16, or uint32). +- **Length Unit** — the physical length unit applied to the created Image Geometries. -## Example Registration File +### Required Input Sources + +A Fiji/ImageJ TileConfiguration text file, with all referenced tile images in the same directory. + +## Example Configuration File # Define the number of dimensions we are working on dim = 2 <===== THIS LINE IS REQUIRED @@ -23,56 +38,6 @@ Utilizes the *itkReadImage* and *ColorToGrayScale* filters SampleMosaic_p4.bmp; ; (0.23675, 1839.55) SampleMosaic_p5.bmp; ; (1227.31, 1839.55) -### Color To Gray Scale Notes - -**For this option to work the read in color array must be a *UInt8Array* otherwise the image will be skipped over when loading** - -The luminosity method is a more sophisticated version of the average method. It also averages the values, but it forms a weighted average to account for human perception. We re more sensitive to green than other colors, so green is weighted most heavily. The default formula for luminosity is BT709 Gray scale: - - Red: 0.2125 Green: 0.7154 Blue: 0.0721. - -The user can set the weightings to what ever values they would like. - -### Lenght Unit - - Yoctometer = 0 - Zeptometer = 1 - Attometer = 2 - Femtometer = 3 - Picometer = 4 - Nanometer = 5 - Micrometer = 6 - Millimeter = 7 - Centimeter = 8 - Decimeter = 9 - Meter = 10 - Decameter = 11 - Hectometer = 12 - Kilometer = 13 - Megameter = 14 - Gigameter = 15 - Terameter = 16 - Petameter = 17 - Exameter = 18 - Zettameter = 19 - Yottameter = 20 - Angstrom = 21 - Mil = 22 - Inch = 23 - Foot = 24 - Mile = 25 - Fathom = 26 - Unspecified = 100U - Unknown = 101U - -### Output Data Type - -The *Output Data Type* parameter controls the numeric type used to store the imported image data: - -- **uint8 [0]**: Read image data as unsigned 8-bit integers (0–255). -- **uint16 [1]**: Read image data as unsigned 16-bit integers (0–65535). -- **uint32 [2]**: Read image data as unsigned 32-bit integers (0–4294967295). - % Auto generated parameter table will be inserted here ## Example Pipelines @@ -81,9 +46,8 @@ Prebuilt Pipelines / Examples / ITKImageProcessing / Fiji Import ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help -If you need more help with a filter, please consider asking your question on the DREAM3D Users mailing list: - +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKImportImageStackFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKImportImageStackFilter.md index e7c5fccb69..15ba2d275b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKImportImageStackFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKImportImageStackFilter.md @@ -1,6 +1,6 @@ # Read Images [3D Stack] (ITK) -This filter directly wraps an ITK filter of the same name. +Reads a stack of 2D images and assembles them into a 3D Image Geometry using the ITK library. ## Group (Subgroup) @@ -10,6 +10,8 @@ ITKImageProcessing (ITKImageProcessing) Read in a stack of 2D images and stack the images into a 3D Volume using the ITK library. Supports most common scalar pixel types and the many file formats supported by ITK. +This filter shares its human name with the SimplnxCore [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md) filter. This ITK-based variant supports the broader range of file formats handled by ITK along with additional cropping, resampling, and data-type conversion options. + ### Processing Order Image operations are applied in the following order: diff --git a/src/Plugins/ITKImageProcessing/docs/ITKIntensityWindowingImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKIntensityWindowingImageFilter.md index 77ab3f1f03..97d7159e31 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKIntensityWindowingImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKIntensityWindowingImageFilter.md @@ -1,6 +1,6 @@ # ITK Intensity Windowing Image Filter -Applies a linear transformation to the intensity levels of the input Image that are inside a user-defined interval. Values below this interval are mapped to a constant. Values over the interval are mapped to another constant. +Linearly stretches a chosen input intensity window into a target output range, clamping everything outside the window. ## Group (Subgroup) @@ -8,12 +8,21 @@ ITKImageIntensity (ImageIntensity) ## Description -IntensityWindowingImageFilter applies pixel-wise a linear transformation to the intensity values of input image pixels. The linear transformation is defined by the user in terms of the minimum and maximum values that the output image should have and the lower and upper limits of the intensity window of the input image. This operation is very common in visualization, and can also be applied as a convenient preprocessing operation for image segmentation. +This filter remaps pixel intensities with a linear "window/level" transform, the operation behind most medical-image and CT contrast controls. Input values inside the window — between *Window Minimum* and *Window Maximum* — are stretched linearly to fill the output range *Output Minimum* to *Output Maximum*. Input values below the window are clamped to *Output Minimum*, and values above it are clamped to *Output Maximum*. It is commonly used for visualization and as a preprocessing step before segmentation. -All computations are performed in the precision of the input pixel's RealType. Before assigning the computed value to the output pixel.* RescaleIntensityImageFilter +To map the *full* input range automatically instead of a chosen window, use [ITK Rescale Intensity Image Filter](ITKRescaleIntensityImageFilter.md). -![](Images/ITKIntensityWindowingImageFilter.png) -![](Images/ITKIntensityWindowingImageFilter_2.png) +### Parameter Guidance + +- **Window Minimum** / **Window Maximum** — the lower and upper bounds of the input intensity window of interest, in **input intensity units**. This window is what gets stretched. +- **Output Minimum** / **Output Maximum** — the target output range, in **output intensity units** (defaults *0* and *255*). + +![Intensity windowing example.](Images/ITKIntensityWindowingImageFilter.png) +![Intensity windowing example.](Images/ITKIntensityWindowingImageFilter_2.png) + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -21,7 +30,7 @@ All computations are performed in the precision of the input pixel's RealType. B ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKInvertIntensityImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKInvertIntensityImageFilter.md index 58eef662e2..b9f50cc19c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKInvertIntensityImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKInvertIntensityImageFilter.md @@ -8,15 +8,11 @@ ITKImageIntensity (ImageIntensity) ## Description -InvertIntensityImageFilter inverts intensity of pixels by subtracting pixel value to a maximum value. The maximum value can be set with SetMaximum and defaults the maximum of input pixel type. This filter can be used to invert, for example, a binary image, a distance map, etc. +Inverts the intensity of each pixel by computing `Maximum - pixel`. This filter can be used to invert, for example, a binary image, a distance map, etc. -### Author +### Parameter Guidance - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. - -### Related Filters - -- IntensityWindowingImageFilter ShiftScaleImageFilter +- **Maximum**: The largest intensity value used as the reference for the inversion, in image intensity units. Set this to the largest intensity present in the data (for example, 255 for an 8-bit image). ![](Images/ITKInvertIntensityImageFilter.png) diff --git a/src/Plugins/ITKImageProcessing/docs/ITKIsoContourDistanceImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKIsoContourDistanceImageFilter.md index 1d8baa6876..093a2309db 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKIsoContourDistanceImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKIsoContourDistanceImageFilter.md @@ -1,6 +1,6 @@ # ITK Iso Contour Distance Image Filter -Compute an approximate distance from an interpolated isocontour to the close grid points. +For a level-set (signed) image, estimates how far each grid pixel near the zero contour is from that contour. ## Group (Subgroup) @@ -8,40 +8,33 @@ ITKDistanceMap (DistanceMap) ## Description -For standard level set algorithms, it is useful to periodically reinitialize the evolving image to prevent numerical accuracy problems in computing derivatives. This reinitialization is done by computing a signed distance map to the current level set. This class provides the first step in this reinitialization by computing an estimate of the distance from the interpolated isocontour to the pixels (or voxels) that are close to it, i.e. for which the isocontour crosses a segment between them and one of their direct neighbors. This class supports narrowbanding. If the input narrowband is provided, the algorithm will only locate the level set within the input narrowband. +This is a specialized filter used in **level-set** methods. A level-set image is a signed image whose zero crossing (the **iso-contour** at value 0) implicitly represents a curve or surface — pixels inside the shape are negative and pixels outside are positive. As a level-set evolves, the values drift away from a true distance and must periodically be "reinitialized" back to a clean signed-distance field. -Implementation of this class is based on Fast and Accurate Redistancing for Level Set Methods Krissian K. and Westin C.F., EUROCAST NeuroImaging Workshop Las Palmas Spain, Ninth International Conference on Computer Aided Systems Theory , pages 48-51, Feb 2003. +This filter performs the first step of that reinitialization: for the grid pixels lying immediately next to the iso-contour (those for which the contour crosses a segment to a direct neighbor), it computes an accurate estimate of the distance from the pixel to the interpolated contour. Pixels farther from the contour are left at a saturated "far" value. If a narrowband is supplied, only pixels within that band are processed. -## Parameters +This filter is for users implementing level-set / fast-marching workflows; for a general-purpose distance transform of a binary mask use one of the distance-map filters such as [ITK Signed Maurer Distance Map Image Filter](ITKSignedMaurerDistanceMapImageFilter.md). -| Name | Type | Description | -|------|------|-------------| -| LevelSetValue | float64 | Set/Get the value of the level set to be located. The default value is 0. | -| FarValue | float64 | Set/Get the value of the level set to be located. The default value is 0. | +### Parameter Guidance -## Required Geometry +- **Level Set Value** — the iso-value whose contour is located, in the **input image's intensity units** (default *0*, the usual zero level set). +- **Far Value** — the saturation distance assigned to pixels that are not adjacent to the contour. Pixels beyond the immediate neighborhood of the contour are clamped to this value (default *10*), so it should be set larger than the band width you care about. (Units are the same length units as the computed distances.) -Image Geometry +### Required Input Sources -## Required Objects +Operates on a signed scalar (level-set) image — typically the output of a prior level-set or distance-map filter. -| Name |Type | Description | -|-----|------|-------------| -| Input Image Geometry | DataPath | DataPath to the Input Image Geometry | -| Input Image Data Array | DataPath | Path to input image with pixel type matching BasicPixelIDTypeList | +## Reference -## Created Objects +K. Krissian and C.-F. Westin, "Fast and Accurate Redistancing for Level Set Methods," EUROCAST NeuroImaging Workshop, Ninth International Conference on Computer Aided Systems Theory, pp. 48-51, Feb 2003. -| Name |Type | Description | -|-----|------|-------------| -| Output Image Data Array | DataPath | Path to output image with pixel type matching BasicPixelIDTypeList | +% Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKLabelContourImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKLabelContourImageFilter.md index 85a64b01c2..e510b7264c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKLabelContourImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKLabelContourImageFilter.md @@ -1,6 +1,6 @@ # ITK Label Contour Image Filter -Labels the pixels on the border of the objects in a labeled image. +From a label image, keeps only the boundary pixels of each labeled region. ## Group (Subgroup) @@ -8,27 +8,30 @@ ITKImageLabel (ImageLabel) ## Description -LabelContourImageFilter takes a labeled image as input, where the pixels in the objects are the pixels with a value different of the BackgroundValue. Only the pixels on the contours of the objects are kept. The pixels not on the border are changed to BackgroundValue. The labels of the object are the same in the input and in the output image. +This filter takes a **label image** (one where each region has a unique integer value) and keeps only the pixels that lie on the contour (outer boundary) of each labeled region. Object pixels are those whose value differs from the *Background Value*. Pixels that sit on a region's border keep their original label, while all interior pixels are set to the *Background Value*. The result is an outline of every region, with each outline retaining the label of the region it bounds. -The connectivity can be changed to minimum or maximum connectivity with SetFullyConnected() . Full connectivity produces thicker contours. +Use this filter when you need the edges of segmented regions — for example to overlay region boundaries on an image or to measure perimeters — rather than the filled regions themselves. - +### Parameter Guidance -### Author +- **Background Value** — the pixel value treated as background. Any pixel equal to this value is ignored, and interior (non-boundary) object pixels are reset to it. The default is 0. +- **Fully Connected** — controls connectivity. *Off* uses face-only connectivity. *On* uses face+edge+corner connectivity, which produces thicker contours. Turn this *On* for objects that are 1 pixel wide or that connect along diagonals. - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +### Required Input Sources -### Related Filters - -- BinaryContourImageFilter +A label image (cell data on an **Image Geometry**), such as the output of the [ITK Connected Component Image Filter](ITKConnectedComponentImageFilter.md) or a segmentation filter. % Auto generated parameter table will be inserted here +## See Also + +- [Insight Journal: Label object representation and manipulation with ITK](https://www.insight-journal.org/browse/publication/217) — Gaetan Lehmann, INRA de Jouy-en-Josas, France. + ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKLaplacianRecursiveGaussianImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKLaplacianRecursiveGaussianImageFilter.md index 15801bcdb0..d9daecbf88 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKLaplacianRecursiveGaussianImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKLaplacianRecursiveGaussianImageFilter.md @@ -8,8 +8,16 @@ ITKImageFeature (ImageFeature) ## Description -Computes the Laplacian of Gaussian (LoG) of an image by convolution with the second derivative of a Gaussian. This filter is implemented using the recursive gaussian filters. +The Laplacian of Gaussian (LoG) first smooths the image with a Gaussian of a chosen width and then takes its second spatial derivative (the Laplacian). It is a classic blob and edge detector: it responds strongly to features whose size matches the Gaussian width, and the zero crossings of its output mark edge locations. A common workflow is to run this filter and then locate those edges with [ITK Zero Crossing Image Filter](ITKZeroCrossingImageFilter.md). This implementation uses ITK's recursive Gaussian filters, so the cost does not grow with the smoothing width. +### Parameter Guidance + +- **Sigma**: Standard deviation of the Gaussian, measured in the units of the image spacing (e.g. micrometers, not pixels). Larger Sigma smooths more and tunes the filter to larger blobs/coarser edges. +- **Normalize Across Scale**: Selects the normalization factor applied to the Gaussian. Leave off (default) for standard LoG output; turn on when comparing responses computed at different Sigma values (scale-space analysis) so that magnitudes remain comparable across scales. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -17,8 +25,8 @@ Computes the Laplacian of Gaussian (LoG) of an image by convolution with the sec ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKLog10ImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKLog10ImageFilter.md index f849b25866..c1f2fb20e9 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKLog10ImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKLog10ImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The computation is performed using std::log10(x). +Computes the base-10 logarithm of each pixel. Input values must be greater than zero. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -16,7 +16,7 @@ The computation is performed using std::log10(x). ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKLogImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKLogImageFilter.md index c8cfe132db..86e857573b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKLogImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKLogImageFilter.md @@ -8,6 +8,8 @@ ITKImageIntensity (ImageIntensity) ## Description +Computes the natural logarithm of each pixel. Input values must be greater than zero. Operates on any scalar image. + ![](Images/ITKLogImageFilter.png) % Auto generated parameter table will be inserted here @@ -16,7 +18,7 @@ ITKImageIntensity (ImageIntensity) ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMaskImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMaskImageFilter.md index 85af231bb1..7e3cbb651e 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMaskImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMaskImageFilter.md @@ -1,6 +1,6 @@ # ITK Mask Image Filter -This filter directly wraps an ITK filter of the same name. +Masks an image using a second mask image. ## Group (Subgroup) @@ -8,27 +8,13 @@ ITKImageIntensity (ImageIntensity) ## Description -Mask an image with a mask. +This filter combines an input image with a mask image of the same size. For each pixel, if the corresponding mask pixel is non-zero (foreground), the input pixel value is copied to the output. If the mask pixel is zero (background), the *Outside Value* is written to the output instead. -This class is templated over the types of the input image type, the mask image type and the type of the output image. Numeric conversions (castings) are done by the C++ defaults. +The input image and the mask image must have the same dimensions. -The pixel type of the input 2 image must have a valid definition of the operator != with zero. This condition is required because internally this filter will perform the operation +### Parameter Guidance -``` -- if pixel_from_mask_image != masking_value -- pixel_output_image = pixel_input_image -- else -- pixel_output_image = outside_value -* -``` - -The pixel from the input 1 is cast to the pixel type of the output image. - -Note that the input and the mask images must be of the same size. - -*WARNING* Any pixel value other than masking value (0 by default) will not be masked out.* MaskNegatedImageFilter - - Wiki Examples:*All Examples* Apply a mask to an image +**Outside Value** is the value written to the output wherever the mask pixel equals 0. It defaults to 0. This value is interpreted in the intensity units of the image data. ![](Images/ITKMaskImageFilter.png) @@ -44,9 +30,8 @@ Note that the input and the mask images must be of the same size. ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. -## DREAM3D Mailing Lists +## DREAM3D-NX Help -If you need more help with a filter, please consider asking your question on the DREAM3D Users mailing list: - +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMaximumProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMaximumProjectionImageFilter.md index 1469192344..43097c843d 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMaximumProjectionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMaximumProjectionImageFilter.md @@ -1,6 +1,6 @@ # ITK Maximum Projection Image Filter -Maximum projection. +Collapses a 3D volume to a 2D image by taking the maximum voxel value along one axis. ## Group (Subgroup) @@ -8,27 +8,22 @@ ITKImageStatistics (ImageStatistics) ## Description -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **maximum**: for each line of voxels parallel to the selected axis, the output voxel is the largest value found along that line. The result has one fewer dimension than the input. -## Author +Maximum projection is the basis of the familiar *maximum intensity projection* (MIP) used to flatten bright features — vessels, particles, or other high-intensity structures — onto a single image regardless of their depth in the stack. Use it when you want to ensure the brightest object along each line of sight is preserved in the 2D summary. -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` -## See Also +### Parameter Guidance -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. +- *Perform In-Place* — when enabled, the projection replaces the input geometry rather than creating a new one. -- [MedianProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MedianProjectionImageFilter.html) +### Required Input Sources -- [MinimumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinimumProjectionImageFilter.html) - -- [StandardDeviationProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1StandardDeviationProjectionImageFilter.html) - -- [SumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1SumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -36,7 +31,7 @@ This class was contributed to the Insight Journal by Gaetan Lehmann. The origina ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMeanProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMeanProjectionImageFilter.md index b079821f1c..f0dc7028ee 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMeanProjectionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMeanProjectionImageFilter.md @@ -1,6 +1,6 @@ -# ITK Mean Projection Image Filter (ITKMeanProjectionImage) +# ITK Mean Projection Image Filter -Mean projection. +Collapses a 3D volume to a 2D image by taking the mean (average) voxel value along one axis. ## Group (Subgroup) @@ -8,27 +8,22 @@ ITKImageStatistics (ImageStatistics) ## Description -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **mean**: for each line of voxels parallel to the selected axis, the output voxel is the arithmetic average of all values along that line. The result has one fewer dimension than the input. -## Author +Mean projection produces a smooth, noise-suppressed summary of the volume because averaging reduces random fluctuations. Use it when you want a representative average view rather than emphasizing the brightest or darkest voxels. Note that the mean is sensitive to outliers; if a few extreme voxels would skew the result, consider [ITK Median Projection Image Filter](ITKMedianProjectionImageFilter.md) instead. -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` -## See Also +### Parameter Guidance -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. +- *Perform In-Place* — when enabled, the projection replaces the input geometry rather than creating a new one. -- [MedianProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MedianProjectionImageFilter.html) +### Required Input Sources -- [MinimumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinimumProjectionImageFilter.html) - -- [StandardDeviationProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1StandardDeviationProjectionImageFilter.html) - -- [SumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1SumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -- [MaximumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MaximumProjectionImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -36,7 +31,7 @@ This class was contributed to the Insight Journal by Gaetan Lehmann. The origina ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMedianImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMedianImageFilter.md index d42a643d6e..725f5533b1 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMedianImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMedianImageFilter.md @@ -1,6 +1,6 @@ # ITK Median Image Filter -Applies a median filter to an image. +Replaces each pixel with the median of its neighborhood — removes speckle/salt-and-pepper noise while keeping edges sharp. ## Group (Subgroup) @@ -8,15 +8,15 @@ ITKSmoothing (Smoothing) ## Description -Computes an image where a given pixel is the median value of the the pixels in a neighborhood about the corresponding input pixel. +This filter replaces each pixel with the **median** value of the pixels in a neighborhood around it. The median is a nonlinear statistic that is not pulled toward extreme values, so a median filter removes isolated noise spikes (salt-and-pepper / shot noise) much more cleanly than a mean/Gaussian blur, and it preserves sharp edges better because it does not average across them. -A median filter is one of the family of nonlinear filters. It is used to smooth an image without being biased by outliers or shot noise. +### Parameter Guidance -This filter requires that the input pixel type provides an operator<() (LessThan Comparable).* Image +- **Radius** — the neighborhood half-width per axis, **in pixels**. The neighborhood spans `2 × Radius + 1` pixels along each axis (so a radius of *1* gives a 3×3×3 window). Larger radii remove more noise but blur fine detail; typical values are 1-2. -- Neighborhood -- NeighborhoodOperator -- NeighborhoodIterator +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -24,7 +24,7 @@ This filter requires that the input pixel type provides an operator<() (LessThan ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMedianProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMedianProjectionImageFilter.md index 9edf342eca..0f11cfa507 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMedianProjectionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMedianProjectionImageFilter.md @@ -1,6 +1,6 @@ -# ITK Median Projection Image Filter (ITKMedianProjectionImage) +# ITK Median Projection Image Filter -Median projection. +Collapses a 3D volume to a 2D image by taking the median voxel value along one axis. ## Group (Subgroup) @@ -8,27 +8,22 @@ ITKImageStatistics (ImageStatistics) ## Description -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **median**: for each line of voxels parallel to the selected axis, the output voxel is the middle value once that line's voxels are sorted. The result has one fewer dimension than the input. -## Author +The median is **robust to outliers** — unlike the mean, a few extreme bright or dark voxels do not pull the result away from the typical value. Use median projection when the volume contains spikes, hot pixels, or sparse noise that you do not want reflected in the 2D summary. -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` -## See Also +### Parameter Guidance -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. +- *Perform In-Place* — when enabled, the projection replaces the input geometry rather than creating a new one. -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) +### Required Input Sources -- [MinimumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinimumProjectionImageFilter.html) - -- [StandardDeviationProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1StandardDeviationProjectionImageFilter.html) - -- [SumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1SumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -- [MaximumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MaximumProjectionImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -36,7 +31,7 @@ This class was contributed to the Insight Journal by Gaetan Lehmann. The origina ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMhaFileReaderFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMhaFileReaderFilter.md index a3027badbb..840a5363c4 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMhaFileReaderFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMhaFileReaderFilter.md @@ -14,21 +14,18 @@ Reads MHA images and the transformation matrix using ITK. Some select headers fr - Number of Dimensions - Center of Rotation (0,0,0 is the default) -- Offset (used at the origin for the created Image Geometr: 0,0,0 is the default) +- Offset (used as the origin for the created Image Geometry; 0,0,0 is the default) - Transformation Matrix +This is a variant of the [Read Image (ITK)](ITKImageReaderFilter.md) filter that also handles the transformation matrix embedded in the MHA file. + ### Use of the Transformation Matrix Notes There is an option to use the transpose of the Transformation Matrix. This can be useful if the stored transformation matrix is not the correct active transformation. If the determinant of the transformation matrix is NOT 1.0 (or really close) AND the user has selected to transpose the matrix a preflight error will be thrown. Using the *transpose* of the transformation matrix **only** works if the transformation matrix purely represents a rotation: Other affine transforms are **NOT** allowed such as shear, scale and translation. #### Technical Discussion -A 4x4 transformation matrix that involves only rotation (and no translation, scaling, or other transformations), the transpose of the matrix is equivalent to its inverse. This property is specific to orthogonal matrices, which are matrices where the rows and columns form a set of orthonormal vectors. In the context of 3D graphics and transformations, a rotation matrix is a type of orthogonal matrix. - -The key properties that make the transpose of a rotation matrix equivalent to its inverse are: - -- **Preservation of Dot Product**: The rotation does not change the dot product between vectors, preserving angles and lengths. -- **Orthonormal Rows and Columns**: The rows (and columns) of a rotation matrix are orthonormal, meaning they have unit length and are perpendicular to each other. This property ensures that multiplying the matrix by its transpose results in the identity matrix, indicating that the transpose is indeed the inverse. +For a pure rotation matrix (no translation, scaling, or shear) the transpose is equal to the inverse, because rotation matrices are orthogonal (their rows and columns are orthonormal). This is why transposing is only valid when the transformation represents a pure rotation. ### Interpolation Type diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMinMaxCurvatureFlowImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMinMaxCurvatureFlowImageFilter.md index 951554f204..d8c2d557f4 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMinMaxCurvatureFlowImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMinMaxCurvatureFlowImageFilter.md @@ -1,6 +1,6 @@ # ITK Min Max Curvature Flow Image Filter -Denoise an image using min/max curvature flow. +Edge-preserving denoising like Curvature Flow, but with a switch that targets a chosen noise scale and better preserves real features. ## Group (Subgroup) @@ -8,31 +8,30 @@ ITKCurvatureFlow (CurvatureFlow) ## Description -MinMaxCurvatureFlowImageFilter implements a curvature driven image denoising algorithm. Iso-brightness contours in the grayscale input image are viewed as a level set. The level set is then evolved using a curvature-based speed function: +This filter is a variant of [ITK Curvature Flow Image Filter](ITKCurvatureFlowImageFilter.md). Plain curvature flow smooths every intensity contour according to its curvature; the **min/max** variant adds a switch that turns smoothing on or off at each point depending on the local image content, so that smoothing is applied where it removes noise but suppressed where it would erode a genuine feature. - \f[ I_t = F_{\mbox{minmax}} |\nabla I| \f] +The switch is keyed to the **stencil radius**: the filter looks at the average intensity in a neighborhood of that radius around each point and uses it to decide whether the point sits on noise (smooth it) or on a real structure (leave it). Choosing the stencil radius therefore selects the *scale* of the noise to remove — a small radius targets fine, single-pixel noise; a larger radius targets coarser texture. -where \f$ F_{\mbox{minmax}} = \max(\kappa,0) \f$ if \f$ \mbox{Avg}_{\mbox{stencil}}(x) \f$ is less than or equal to \f$ T_{threshold} \f$ and \f$ \min(\kappa,0) \f$ , otherwise. \f$ \kappa \f$ is the mean curvature of the iso-brightness contour at point \f$ x \f$ . +The output pixels are of a floating-point type. -In min/max curvature flow, movement is turned on or off depending on the scale of the noise one wants to remove. Switching depends on the average image value of a region of radius \f$ R \f$ around each point. The choice of \f$ R \f$ , the stencil radius, governs the scale of the noise to be removed. +### Parameter Guidance -The threshold value \f$ T_{threshold} \f$ is the average intensity obtained in the direction perpendicular to the gradient at point \f$ x \f$ at the extrema of the local neighborhood. +- **Number Of Iterations** — how many time steps to apply. More iterations smooth more strongly. +- **Time Step** — the size of each step (dimensionless). Keep it small for numerical stability (around **0.125 for 2D** and **0.0625 for 3D**; default 0.05) and reduce if the result looks unstable. +- **Stencil Radius** — the neighborhood radius, **in pixels**, used by the min/max switch; it sets the scale of noise that is removed. Small values (the default is *2*) target fine noise; larger values target coarser features. (Stored as a signed integer, but only non-negative values are meaningful.) -This filter make use of the multi-threaded finite difference solver hierarchy. Updates are computed using a MinMaxCurvatureFlowFunction object. A zero flux Neumann boundary condition is used when computing derivatives near the data boundary. +### Required Input Sources -## Warning +Operates on any scalar (floating-point) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -This filter assumes that the input and output types have the same dimensions. This filter also requires that the output image pixels are of a real type. This filter works for any dimensional images, however for dimensions greater than 3D, an expensive brute-force search is used to compute the local threshold. +## Reference -Reference: "Level Set Methods and Fast Marching Methods", J.A. Sethian, Cambridge Press, Chapter 16, Second edition, 1999. +"Level Set Methods and Fast Marching Methods", J.A. Sethian, Cambridge Press, Chapter 16, Second edition, 1999. ## See Also -- [MinMaxCurvatureFlowFunction](https://itk.org/Doxygen/html/classitk_1_1MinMaxCurvatureFlowFunction.html) - -- [CurvatureFlowImageFilter](https://itk.org/Doxygen/html/classitk_1_1CurvatureFlowImageFilter.html) - -- [BinaryMinMaxCurvatureFlowImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryMinMaxCurvatureFlowImageFilter.html) +- [ITK MinMaxCurvatureFlowImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1MinMaxCurvatureFlowImageFilter.html) +- [ITK Curvature Flow Image Filter](ITKCurvatureFlowImageFilter.md) % Auto generated parameter table will be inserted here @@ -40,8 +39,8 @@ Reference: "Level Set Methods and Fast Marching Methods", J.A. Sethian, Cambridg ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMinimumProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMinimumProjectionImageFilter.md index b4ac3d85e8..8207259a3b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMinimumProjectionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMinimumProjectionImageFilter.md @@ -1,6 +1,6 @@ -# ITK Minimum Projection Image Filter (ITKMinimumProjectionImage) +# ITK Minimum Projection Image Filter -Minimum projection. +Collapses a 3D volume to a 2D image by taking the minimum voxel value along one axis. ## Group (Subgroup) @@ -8,27 +8,22 @@ ITKImageStatistics (ImageStatistics) ## Description -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **minimum**: for each line of voxels parallel to the selected axis, the output voxel is the smallest value found along that line. The result has one fewer dimension than the input. -## Author +Minimum projection is the dark-feature counterpart of maximum projection: it preserves the darkest object along each line of sight, which is useful for emphasizing low-intensity structures such as voids, pores, or absorbing features against a bright background. -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` -## See Also +### Parameter Guidance -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. +- *Perform In-Place* — when enabled, the projection replaces the input geometry rather than creating a new one. -- [MedianProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MedianProjectionImageFilter.html) +### Required Input Sources -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) - -- [StandardDeviationProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1StandardDeviationProjectionImageFilter.html) - -- [SumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1SumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -- [MaximumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MaximumProjectionImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -36,7 +31,7 @@ This class was contributed to the Insight Journal by Gaetan Lehmann. The origina ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalGradientImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalGradientImageFilter.md index 92a237919e..6cef3c8f01 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalGradientImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalGradientImageFilter.md @@ -1,6 +1,6 @@ # ITK Morphological Gradient Image Filter -Compute the gradient of a grayscale image. +Highlights edges in a grayscale image by subtracting a local minimum-filtered image from a local maximum-filtered image. ## Group (Subgroup) @@ -8,24 +8,36 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -The structuring element is assumed to be composed of binary values (zero or one). Only elements of the structuring element having values > 0 are candidates for affecting the center pixel.* MorphologyImageFilter , GrayscaleFunctionDilateImageFilter , BinaryDilateImageFilter +The **morphological gradient** is an edge detector. At each pixel it computes the difference between a grayscale **dilation** (the maximum value in the neighborhood defined by the structuring element) and a grayscale **erosion** (the minimum value in that same neighborhood): -### Kernel Type +`morphological gradient = dilation − erosion` -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +Where the image is flat, the local maximum and minimum are nearly equal and the result is near zero (dark). Where intensity changes sharply — an edge — the maximum and minimum differ greatly and the result is large (bright). The output is therefore bright along object boundaries and dark in uniform regions. The width of the detected edges grows with the size of the structuring element. + +### Parameter Guidance + +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Larger radii detect broader edges. + +#### Kernel Type + +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedFromMarkersImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedFromMarkersImageFilter.md deleted file mode 100644 index 7acdd191fa..0000000000 --- a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedFromMarkersImageFilter.md +++ /dev/null @@ -1,44 +0,0 @@ -# ITK Morphological Watershed From Markers Image Filter (ITKMorphologicalWatershedFromMarkersImage) - -Morphological watershed transform from markers. - -## Group (Subgroup) - -ITKWatersheds (Watersheds) - -## Description - -The watershed transform is a tool for image segmentation that is fast and flexible and potentially fairly parameter free. It was originally derived from a geophysical model of rain falling on a terrain and a variety of more formal definitions have been devised to allow development of practical algorithms. If an image is considered as a terrain and divided into catchment basins then the hope is that each catchment basin would contain an object of interest. - -The output is a label image. A label image, sometimes referred to as a categorical image, has unique values for each region. For example, if a watershed produces 2 regions, all pixels belonging to one region would have value A, and all belonging to the other might have value B. Unassigned pixels, such as watershed lines, might have the background value (0 by convention). - -The simplest way of using the watershed is to preprocess the image we want to segment so that the boundaries of our objects are bright (e.g apply an edge detector) and compute the watershed transform of the edge image. Watershed lines will correspond to the boundaries and our problem will be solved. This is rarely useful in practice because there are always more regional minima than there are objects, either due to noise or natural variations in the object surfaces. Therefore, while many watershed lines do lie on significant boundaries, there are many that don't. Various methods can be used to reduce the number of minima in the image, like thresholding the smallest values, filtering the minima and/or smoothing the image. - -This filter use another approach to avoid the problem of over segmentation: it let the user provide a marker image which mark the minima in the input image and give them a label. The minima are imposed in the input image by the markers. The labels of the output image are the label of the marker image. - -The morphological watershed transform algorithm is described in Chapter 9.2 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003. - -This code was contributed in the Insight Journal paper: "The watershed transform in ITK - discussion and new developments" by Beare R., Lehmann G. https://www.insight-journal.org/browse/publication/92 - -## Author - -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. -- Richard Beare. Department of Medicine, Monash University, Melbourne, Australia. - - -## See Also - -- [WatershedImageFilter ,](https://itk.org/Doxygen/html/classitk_1_1WatershedImageFilter ,.html)MorphologicalWatershedImageFilter - -% Auto generated parameter table will be inserted here - -## Example Pipelines - -## License & Copyright - -Please see the description file distributed with this plugin. - -## DREAM3D Mailing Lists - -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedImageFilter.md index 61e7d9ae49..ac4140e69b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKMorphologicalWatershedImageFilter.md @@ -1,6 +1,6 @@ # ITK Morphological Watershed Image Filter -Watershed segmentation implementation with morphological operators. +Segments an image into labeled regions using the watershed transform — flooding the image as if it were a terrain. ## Group (Subgroup) @@ -8,20 +8,27 @@ ITKWatersheds (Watersheds) ## Description -Watershed pixel are labeled 0. TOutputImage should be an integer type. Labels of output image are in no particular order. You can reorder the labels such that object labels are consecutive and sorted based on object size by passing the output of this filter to a RelabelComponentImageFilter . +The **watershed transform** treats a grayscale image as a topographic surface: bright pixels are high ground and dark pixels are low ground. Imagine rain falling on this terrain and water collecting in the low spots. Each local low point seeds a **catchment basin**, and the rising water floods outward until basins meet. The lines where neighboring basins meet are the **watershed lines** (the ridge tops between valleys). Each basin becomes one labeled output region. -The morphological watershed transform algorithm is described in Chapter 9.2 of Pierre Soille's book "Morphological Image Analysis: -Principles and Applications", Second Edition, Springer, 2003. +This filter is most commonly run on a gradient/edge image (for example the output of [ITK Morphological Gradient Image Filter](ITKMorphologicalGradientImageFilter.md)), so that bright ridges fall on object boundaries and the basins fall on the objects. -This code was contributed in the Insight Journal paper: "The watershed transform in ITK - discussion and new developments" by Beare R., Lehmann G. +The output is a **label image**: every region has a unique integer value, and the watershed lines (if marked) are 0. A raw watershed almost always produces **far more regions than there are real objects** (over-segmentation) because every small dip becomes its own basin; the *Level* parameter and a marker-controlled variant exist to control this. -### Author +### Parameter Guidance - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +- **Level** — a depth/contrast threshold, in the **input image's intensity units**, that merges shallow neighboring basins. A higher Level merges more aggressively and yields fewer, larger regions; *0* (the default) performs no merging and tends to over-segment. Raising Level is the primary way to reduce over-segmentation. +- **Mark Watershed Line** — when on, the boundary pixels between regions are written as 0; when off, no separating line is drawn. +- **Fully Connected** — controls neighbor connectivity (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. -### Related Filters +The output labels are in no particular order. To renumber them consecutively and sort by region size, follow this filter with [ITK Relabel Component Image Filter](ITKRelabelComponentImageFilter.md). A marker-controlled variant (one region per user-supplied seed, avoiding over-segmentation) exists in ITK but is not currently built into DREAM3D-NX (see [issue #1639](https://github.com/BlueQuartzSoftware/simplnx/issues/1639)). -- WatershedImageFilter , MorphologicalWatershedFromMarkersImageFilter +### Required Input Sources + +Operates on any scalar (typically gradient/edge) image — for example the output of [ITK Morphological Gradient Image Filter](ITKMorphologicalGradientImageFilter.md) or another ITK image filter. + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 9.2). Beare R., Lehmann G., "The watershed transform in ITK — discussion and new developments," Insight Journal, . % Auto generated parameter table will be inserted here @@ -29,7 +36,7 @@ This code was contributed in the Insight Journal paper: "The watershed transform ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKNormalizeImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKNormalizeImageFilter.md index 77dc096dec..2500e9c618 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKNormalizeImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKNormalizeImageFilter.md @@ -8,9 +8,9 @@ ITKImageIntensity (ImageIntensity) ## Description -NormalizeImageFilter shifts and scales an image so that the pixels in the image have a zero mean and unit variance. This filter uses StatisticsImageFilter to compute the mean and variance of the input and then applies ShiftScaleImageFilter to shift and scale the pixels. +Shifts and scales an image so that the pixels in the image have a zero mean and unit variance. The filter first computes the mean and variance of the input and then shifts and scales the pixels accordingly. Output values are in dimensionless normalized units. -NB: since this filter normalizes the data such that the mean is at 0, and \f$-\sigma\f$ to \f$+\sigma\f$ is mapped to -1.0 to 1.0, output image integral types will produce an image that DOES NOT HAVE a unit variance due to 68% of the intensity values being mapped to the real number range of -1.0 to 1.0 and then cast to the output integral value.* NormalizeToConstantImageFilter +NB: since this filter normalizes the data such that the mean is at 0, and $-\sigma$ to $+\sigma$ is mapped to -1.0 to 1.0, output image integral types will produce an image that DOES NOT HAVE a unit variance due to 68% of the intensity values being mapped to the real number range of -1.0 to 1.0 and then cast to the output integral value. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/ITKImageProcessing/docs/ITKNotImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKNotImageFilter.md index 7e0d2b11a7..6708bdbc83 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKNotImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKNotImageFilter.md @@ -8,26 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -This class is templated over the type of an input image and the type of the output image. Numeric conversions (castings) are done by the C++ defaults. - -Since the logical NOT operation operates only on boolean types, the input type must be implicitly convertible to bool, which is only defined in C++ for integer types, the images passed to this filter must comply with the requirement of using integer pixel type. - -The total operation over one pixel will be - -``` -if( !A ) - - { - - return this->m_ForegroundValue; - - } - -return this->m_BackgroundValue; - -``` - -Where "!" is the unary Logical NOT operator in C++. +Applies the logical NOT operator to each pixel of an integer image. The input must be an integer-valued image. For each pixel, a value equal to 0 is replaced with the Foreground Value, and any non-zero value is replaced with the Background Value. This is commonly used to invert a binary (mask) image. ![](Images/ITKNotImageFilter.png) diff --git a/src/Plugins/ITKImageProcessing/docs/ITKOpeningByReconstructionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKOpeningByReconstructionImageFilter.md index 7c0168d458..c7ea69d971 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKOpeningByReconstructionImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKOpeningByReconstructionImageFilter.md @@ -1,6 +1,6 @@ # ITK Opening By Reconstruction Image Filter -Opening by reconstruction of an image. +Removes small bright features from a grayscale image while preserving the shape of the structures that remain. ## Group (Subgroup) @@ -8,39 +8,40 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -This filter preserves regions, in the foreground, that can completely contain the structuring element. At the same time, this filter eliminates all other regions of foreground pixels. Contrary to the morphological opening, the opening by reconstruction preserves the shape of the components that are not removed by erosion. The opening by reconstruction of an image "f" is defined as: +A standard morphological **opening** (erosion followed by dilation) removes small bright features that are smaller than the **structuring element**, but it also distorts the shapes of the larger features it touches. **Opening by reconstruction** achieves the same effect while preserving the exact shape of the structures, by replacing the final dilation with a morphological reconstruction step. -OpeningByReconstruction(f) = DilationByReconstruction(f, Erosion(f)). +It keeps the foreground regions that can fully contain the structuring element and removes the rest; the surviving regions are restored to their original shape rather than the eroded approximation. It is defined as `OpeningByReconstruction(f) = DilationByReconstruction(Erosion(f))`. In addition to removing small bright features, the operation tends to lower the contrast of the brightest regions. -Opening by reconstruction not only removes structures destroyed by the erosion, but also levels down the contrast of the brightest regions. If PreserveIntensities is on, a subsequent reconstruction by dilation using a marker image that is the original image for all unaffected pixels. +### Parameter Guidance -Opening by reconstruction is described in Chapter 6.3.9 of Pierre Soille's book "Morphological Image Analysis: Principles and -Applications", Second Edition, Springer, 2003. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). Bright features smaller than this are removed. +- **Fully Connected** — controls neighbor connectivity during reconstruction (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. +- **Preserve Intensities** — when on, pixels that the operation did not need to change are restored to their exact original gray values, so only the affected regions differ from the input. -### Author +#### Kernel Type - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. - -### Related Filters - -- GrayscaleMorphologicalOpeningImageFilter - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. Compare with the standard [ITK Grayscale Morphological Opening Image Filter](ITKGrayscaleMorphologicalOpeningImageFilter.md). + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 6.3.9). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKOtsuMultipleThresholdsImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKOtsuMultipleThresholdsImageFilter.md index 8dc7739086..dabb4c60f7 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKOtsuMultipleThresholdsImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKOtsuMultipleThresholdsImageFilter.md @@ -1,6 +1,6 @@ # ITK Otsu Multiple Thresholds Image Filter -Threshold an image using multiple Otsu Thresholds. +Automatically separates an image into several intensity classes using Otsu's method and writes a label map. ## Group (Subgroup) @@ -8,14 +8,25 @@ ITKThresholding (Thresholding) ## Description -This filter creates a labeled image that separates the input image into various classes. The filter computes the thresholds using the OtsuMultipleThresholdsCalculator and applies those thresholds to the input image using the ThresholdLabelerImageFilter . The NumberOfHistogramBins and NumberOfThresholds can be set for the Calculator. The LabelOffset can be set for the ThresholdLabelerImageFilter . +**Otsu thresholding** automatically chooses threshold values from the image's intensity histogram — it picks the thresholds that best separate the pixels into distinct classes by maximizing the variance *between* classes (equivalently, minimizing the variance *within* each class). No threshold intensities are entered by hand; the filter computes them for you. -This filter also includes an option to use the valley emphasis algorithm from H.F. Ng, "Automatic thresholding for defect detection", Pattern Recognition Letters, (27): 1644-1649, 2006. The valley emphasis algorithm is particularly effective when the object to be thresholded is small. See the following tests for examples: itkOtsuMultipleThresholdsImageFilterTest3 and itkOtsuMultipleThresholdsImageFilterTest4 To use this algorithm, simple call the setter: SetValleyEmphasis(true) It is turned off by default.* ScalarImageToHistogramGenerator +This filter is the multi-level version: instead of one threshold (two classes), it finds **N** thresholds that partition the image into **N + 1** classes. The output is a **label map** in which each pixel is assigned an integer class index (0, 1, 2, …) according to which intensity band it falls into. -- OtsuMultipleThresholdsCalculator -- ThresholdLabelerImageFilter +Use this filter when an image contains several distinguishable intensity populations (for example background, matrix, and one or more phases) and you want them segmented into labels without manually tuning cutoffs. -![](Images/ITKOtsuThreshold.png) +### Parameter Guidance + +- **Number Of Thresholds** — how many thresholds to compute. The output contains one more class than this number (N thresholds → N + 1 labels). Default *1* (two classes). +- **Number Of Histogram Bins** — the number of bins used to build the intensity histogram the thresholds are computed from. More bins give finer threshold resolution at the cost of speed; default *128*. +- **Label Offset** — an integer added to every output label so the classes start from a value other than 0 (useful for keeping labels distinct from other label maps). Default *0*. +- **Valley Emphasis** — when on, biases the threshold selection toward the valleys (low-population dips) of the histogram. This helps when the object of interest is small and would otherwise be lost against a large background population. Default *off*. +- **ReturnBinMidpoint** — when on, each computed threshold is reported as the midpoint of its histogram bin; when off (default), the bin's maximum value is used. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![Otsu multiple-threshold label map.](Images/ITKOtsuThreshold.png) % Auto generated parameter table will be inserted here @@ -23,7 +34,7 @@ This filter also includes an option to use the valley emphasis algorithm from H. ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKRegionalMaximaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKRegionalMaximaImageFilter.md index 5f0e5879bf..2aa10e6935 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKRegionalMaximaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKRegionalMaximaImageFilter.md @@ -1,6 +1,6 @@ # ITK Regional Maxima Image Filter -Produce a binary image where foreground is the regional maxima of the input image. +Produces a binary image marking the regional maxima of the input image. ## Group (Subgroup) @@ -8,21 +8,19 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Regional maxima are flat zones surrounded by pixels of lower value. +A regional maximum is a connected flat zone of pixels that all share the same value and whose every neighboring pixel has a strictly lower value (a local "plateau" that is brighter than everything immediately surrounding it). This filter labels those pixels in the output and labels everything else as background, producing a binary image. Use it to detect peaks, bright spots, or seed points for later segmentation. -If the input image is constant, the entire image can be considered as a maxima or not. The desired behavior can be selected with the SetFlatIsMaxima() method. +If the input image is constant (completely flat), the entire image can be treated either as a single regional maximum or as background; the **Flat Is Maxima** option selects which behavior to use. -## Author +### Parameter Guidance -This class was contributed to the Insight Journal by author Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. The paper can be found at https://www.insight-journal.org/browse/publication/65 +- **Flat Is Maxima**: When on (default), a completely flat input image is reported as a regional maximum; when off, a flat image produces an all-background result. +- **Fully Connected**: Controls pixel connectivity. When off (default, "face connected"), only face-adjacent neighbors are considered (connectivity 4 in 2D, 6 in 3D); when on, diagonal neighbors are also included (connectivity 8 in 2D, 26 in 3D). Turning it on tends to merge nearby maxima into a single connected region. +- **Background Value** / **Foreground Value**: These are the output binary labels written for non-maxima and maxima pixels respectively. They are not intensity thresholds applied to the input. -## See Also +### Required Input Sources -- [ValuedRegionalMaximaImageFilter](https://itk.org/Doxygen/html/classitk_1_1ValuedRegionalMaximaImageFilter.html) - -- [HConvexImageFilter](https://itk.org/Doxygen/html/classitk_1_1HConvexImageFilter.html) - -- [RegionalMinimaImageFilter](https://itk.org/Doxygen/html/classitk_1_1RegionalMinimaImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -30,8 +28,8 @@ This class was contributed to the Insight Journal by author Gaetan Lehmann. Biol ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKRegionalMinimaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKRegionalMinimaImageFilter.md index b57c06aa75..a4bf65065b 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKRegionalMinimaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKRegionalMinimaImageFilter.md @@ -1,6 +1,6 @@ # ITK Regional Minima Image Filter -Produce a binary image where foreground is the regional minima of the input image. +Produces a binary image marking the regional minima of the input image. ## Group (Subgroup) @@ -8,23 +8,19 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Regional minima are flat zones surrounded by pixels of greater value. +A regional minimum is a connected flat zone of pixels that all share the same value and whose every neighboring pixel has a strictly higher value (a local "valley" that is darker than everything immediately surrounding it). This filter labels those pixels in the output and labels everything else as background, producing a binary image. Use it to detect dark spots, basins, or seed points for later segmentation. -If the input image is constant, the entire image can be considered as a minima or not. The SetFlatIsMinima() method let the user choose which behavior to use. +If the input image is constant (completely flat), the entire image can be treated either as a single regional minimum or as background; the **Flat Is Minima** option selects which behavior to use. -## Author +### Parameter Guidance -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +- **Flat Is Minima**: When on (default), a completely flat input image is reported as a regional minimum; when off, a flat image produces an all-background result. +- **Fully Connected**: Controls pixel connectivity. When off (default, "face connected"), only face-adjacent neighbors are considered (connectivity 4 in 2D, 6 in 3D); when on, diagonal neighbors are also included (connectivity 8 in 2D, 26 in 3D). Turning it on tends to merge nearby minima into a single connected region. +- **Background Value** / **Foreground Value**: These are the output binary labels written for non-minima and minima pixels respectively. They are not intensity thresholds applied to the input. -This class was contributed to the Insight Journal by author Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. https://www.insight-journal.org/browse/publication/65 +### Required Input Sources -## See Also - -- [RegionalMaximaImageFilter](https://itk.org/Doxygen/html/classitk_1_1RegionalMaximaImageFilter.html) - -- [ValuedRegionalMinimaImageFilter](https://itk.org/Doxygen/html/classitk_1_1ValuedRegionalMinimaImageFilter.html) - -- [HConcaveImageFilter](https://itk.org/Doxygen/html/classitk_1_1HConcaveImageFilter.html) +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -32,8 +28,8 @@ This class was contributed to the Insight Journal by author Gaetan Lehmann. Biol ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKRelabelComponentImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKRelabelComponentImageFilter.md index aba93d0b15..7e0b662497 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKRelabelComponentImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKRelabelComponentImageFilter.md @@ -1,6 +1,6 @@ # ITK Relabel Component Image Filter -Relabel the components in an image such that consecutive labels are used. +Renumbers the labels in a label image consecutively, sorted so that label 1 is the largest object. ## Group (Subgroup) @@ -8,17 +8,22 @@ ITKConnectedComponents (ConnectedComponents) ## Description -RelabelComponentImageFilter remaps the labels associated with the objects in an image (as from the output of ConnectedComponentImageFilter ) such that the label numbers are consecutive with no gaps between the label numbers used. By default, the relabeling will also sort the labels based on the size of the object: the largest object will have label #1, the second largest will have label #2, etc. If two labels have the same size their initial order is kept. The sorting by size can be disabled using SetSortByObjectSize. +This filter takes a **label image** (one where each region has a unique integer value) and remaps the labels so they are consecutive with no gaps. By default it also sorts the labels by object size: the largest object becomes label 1, the second largest becomes label 2, and so on. If two objects have the same size their original relative order is kept. Sorting can be turned off, in which case the original ordering of the labels is preserved while still removing any gaps. -Label #0 is assumed to be the background and is left unaltered by the relabeling. +Label 0 is assumed to be the background and is left unchanged. -RelabelComponentImageFilter is typically used on the output of the ConnectedComponentImageFilter for those applications that want to extract the largest object or the "k" largest objects. Any particular object can be extracted from the relabeled output using a BinaryThresholdImageFilter . A group of objects can be extracted from the relabeled output using a ThresholdImageFilter . +Optionally, objects smaller than a minimum size can be discarded. This is useful for cleaning up small spurious regions after a connected-components step. Because the labels are sorted by size, you can then easily extract the largest object (label 1) or the *k* largest objects. -Once all the objects are relabeled, the application can query the number of objects and the size of each object. Object sizes are returned in a vector. The size of the background is not calculated. So the size of object #1 is GetSizeOfObjectsInPixels() [0], the size of object #2 is GetSizeOfObjectsInPixels() [1], etc. +Use this filter on the output of a labeling step, such as the [ITK Connected Component Image Filter](ITKConnectedComponentImageFilter.md) or a watershed segmentation, when you want labels ordered by size or want to drop small objects. -If user sets a minimum object size, all objects with fewer pixels than the minimum will be discarded, so that the number of objects reported will be only those remaining. The GetOriginalNumberOfObjects method can be called to find out how many objects were present before the small ones were discarded. +### Parameter Guidance -RelabelComponentImageFilter can be run as an "in place" filter, where it will overwrite its output. The default is run out of place (or generate a separate output). "In place" operation can be controlled via methods in the superclass, InPlaceImageFilter::InPlaceOn() and InPlaceImageFilter::InPlaceOff().* ConnectedComponentImageFilter , BinaryThresholdImageFilter , ThresholdImageFilter +- **Minimum Object Size** — the smallest object to keep, measured as a **voxel/pixel count** (number of pixels in the object). Any object with fewer pixels than this value is discarded and does not appear in the output. A value of 0 keeps every object. +- **SortByObjectSize** — when *On* (the default), labels are renumbered in order of decreasing object size (label 1 = largest). When *Off*, the original label order is preserved and only the gaps are removed. + +### Required Input Sources + +A label image (cell data on an **Image Geometry**), such as the output of the [ITK Connected Component Image Filter](ITKConnectedComponentImageFilter.md) or a watershed/segmentation filter. % Auto generated parameter table will be inserted here @@ -26,7 +31,7 @@ RelabelComponentImageFilter can be run as an "in place" filter, where it will ov ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKRescaleIntensityImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKRescaleIntensityImageFilter.md index 66b30c922d..bcfa1a72e5 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKRescaleIntensityImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKRescaleIntensityImageFilter.md @@ -1,6 +1,6 @@ # ITK Rescale Intensity Image Filter -Applies a linear transformation to the intensity levels of the input Image . +Linearly rescales the full intensity range of an image into a chosen output range. ## Group (Subgroup) @@ -8,15 +8,21 @@ ITKImageIntensity (ImageIntensity) ## Description -RescaleIntensityImageFilter applies pixel-wise a linear transformation to the intensity values of input image pixels. The linear transformation is defined by the user in terms of the minimum and maximum values that the output image should have. +This filter applies a linear transform that maps the **full** intensity range of the input image onto a user-specified output range. The smallest input value maps to *Output Minimum*, the largest input value maps to *Output Maximum*, and everything in between scales proportionally. It is the standard way to normalize an image to a fixed range (for example 0-255 for display, or 0-1 for downstream processing). -The following equation gives the mapping of the intensity values +$$ +\text{output} = (\text{input} - \text{inputMin}) \cdot \frac{\text{OutputMax} - \text{OutputMin}}{\text{inputMax} - \text{inputMin}} + \text{OutputMin} +$$ - \f[ outputPixel = ( inputPixel - inputMin) \cdot \frac{(outputMax - outputMin )}{(inputMax - inputMin)} + outputMin \f] +The input minimum and maximum are detected automatically, so only the output range is set by the user. To stretch a *chosen* input window rather than the full range (clamping outside it), use [ITK Intensity Windowing Image Filter](ITKIntensityWindowingImageFilter.md). -All computations are performed in the precision of the input pixel's RealType. Before assigning the computed value to the output pixel. +### Parameter Guidance -NOTE: In this filter the minimum and maximum values of the input image are computed internally using the MinimumMaximumImageCalculator . Users are not supposed to set those values in this filter. If you need a filter where you can set the minimum and maximum values of the input, please use the IntensityWindowingImageFilter . If you want a filter that can use a user-defined linear transformation for the intensity, then please use the ShiftScaleImageFilter .* IntensityWindowingImageFilter +- **Output Minimum** / **Output Maximum** — the target output range, in **output intensity units** (defaults *0* and *255*). + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -24,7 +30,7 @@ NOTE: In this filter the minimum and maximum values of the input image are compu ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSigmoidImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSigmoidImageFilter.md index 85e3a43020..86857a34dd 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSigmoidImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSigmoidImageFilter.md @@ -1,6 +1,6 @@ # ITK Sigmoid Image Filter -Computes the sigmoid function pixel-wise. +Remaps pixel intensities through an S-shaped (sigmoid) curve, useful for smoothly boosting contrast within a chosen intensity band. ## Group (Subgroup) @@ -8,11 +8,25 @@ ITKImageIntensity (ImageIntensity) ## Description -A linear transformation is applied first on the argument of the sigmoid function. The resulting total transform is given by +This filter passes every pixel value through a **sigmoid** function — a smooth S-shaped curve. Input values near a chosen center are stretched (increasing contrast there), while values far above or below the center are gently compressed toward the output maximum or minimum. It is a common way to enhance contrast in a region of interest without the hard clipping of a threshold. -![Images/ITKSigmoidImage_Equation.png](Images/ITKSigmoidImage_Equation.png) +Each output pixel is computed as: -Every output pixel is equal to f(x). Where x is the intensity of the homologous input pixel, and alpha and beta are user-provided constants. +$$ +\text{output} = (\text{OutputMax} - \text{OutputMin}) \cdot \frac{1}{1 + e^{-(x - \beta)/\alpha}} + \text{OutputMin} +$$ + +where $x$ is the input pixel value. + +### Parameter Guidance + +- **Alpha** — the width of the transition region, in input intensity units. Larger values give a gentler, more gradual slope; smaller values give a sharper, more threshold-like transition. A negative value inverts the curve. +- **Beta** — the center (inflection point) of the curve, in input intensity units. Input values near *Beta* land in the steep part of the S and are spread out the most. +- **Output Minimum** / **Output Maximum** — the range the output is mapped into (defaults *0* and *255*). + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. % Auto generated parameter table will be inserted here @@ -20,7 +34,7 @@ Every output pixel is equal to f(x). Where x is the intensity of the homologous ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSignedDanielssonDistanceMapImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSignedDanielssonDistanceMapImageFilter.md index cee3ef6952..78272f337f 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSignedDanielssonDistanceMapImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSignedDanielssonDistanceMapImageFilter.md @@ -1,6 +1,6 @@ # ITK Signed Danielsson Distance Map Image Filter -This filter computes the signed distance map of the input image as an approximation with pixel accuracy to the Euclidean distance. +Computes a near-Euclidean signed distance map of a binary image, with inside distances negative. ## Group (Subgroup) @@ -8,29 +8,31 @@ ITKDistanceMap (DistanceMap) ## Description -This class is parameterized over the type of the input image and the type of the output image. +A **distance map** replaces every pixel with its distance to the nearest object boundary. This is the **signed** variant of the Danielsson distance map: pixels **inside** an object are given **negative** distances and pixels **outside** are given **positive** distances. The distance is measured from the boundary of the object (the ON pixels). By default, inside is negative; enable *Inside Is Positive* to flip the convention. -For purposes of evaluating the signed distance map, the input is assumed to be binary composed of pixels with value 0 and non-zero. +The input is treated as binary: pixels with value 0 are background and all nonzero pixels are object. Distances are a close approximation to true Euclidean distance. -The inside is considered as having negative distances. Outside is treated as having positive distances. To change the convention, use the InsideIsPositive(bool) function. +Like the unsigned Danielsson filter, it can also report: -As a convention, the distance is evaluated from the boundary of the ON pixels. +- **Voronoi partition** — each background pixel labeled with the closest object, dividing the image into nearest-influence regions. +- **Offset / vector map** — for each pixel, the per-axis displacement (in pixels) pointing to its closest object point. -The filter returns +Use a signed distance map when you need a smooth field that changes sign at object boundaries — for example as a level-set or shape-morphing input. -\li A signed distance map with the approximation to the euclidean distance. +### Parameter Guidance -\li A voronoi partition. (See itkDanielssonDistanceMapImageFilter) +- **Inside Is Positive** — by default, pixels inside an object are negative and pixels outside are positive. Enable this to reverse that convention (inside positive, outside negative). +- **Squared Distance** — when enabled, the output holds the distance **squared** instead of the distance. This avoids a square-root step but the values are no longer in linear distance units. Leave off for true distances. +- **Use Image Spacing** — when enabled, distances are measured in the image's **physical units** (using pixel spacing). When disabled, distances are measured in **pixels**. -\li A vector map containing the component of the vector relating the current pixel with the closest point of the closest object to this pixel. Given that the components of the distance are computed in "pixels", the vector is represented by an itk::Offset . That is, physical coordinates are not used. (See itkDanielssonDistanceMapImageFilter) +### Required Input Sources -## Warning - -This filter internally uses the DanielssonDistanceMap filter. This filter is N-dimensional. +Requires a binary image: zero marks background and any nonzero value marks object. This is typically a segmentation mask produced upstream. ## See Also -- [itkDanielssonDistanceMapImageFilter](https://itk.org/Doxygen/html/classitk_1_1itkDanielssonDistanceMapImageFilter.html) +- [ITK Danielsson Distance Map Image Filter](ITKDanielssonDistanceMapImageFilter.md) +- [ITK Signed Danielsson Distance Map Image Filter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1SignedDanielssonDistanceMapImageFilter.html) % Auto generated parameter table will be inserted here @@ -38,8 +40,8 @@ This filter internally uses the DanielssonDistanceMap filter. This filter is N-d ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSignedMaurerDistanceMapImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSignedMaurerDistanceMapImageFilter.md index 299a79a4c1..c6cdafb80d 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSignedMaurerDistanceMapImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSignedMaurerDistanceMapImageFilter.md @@ -1,6 +1,6 @@ # ITK Signed Maurer Distance Map Image Filter -This filter calculates the Euclidean distance transform of a binary image in linear time for arbitrary dimensions. +Computes an exact Euclidean signed distance map of a binary image in linear time. ## Group (Subgroup) @@ -8,17 +8,33 @@ ITKDistanceMap (DistanceMap) ## Description - Inputs and Outputs -This is an image-to-image filter. The dimensionality is arbitrary. The only dimensionality constraint is that the input and output images be of the same dimensions and size. To maintain integer arithmetic within the filter, the default output is the signed squared distance. This implies that the input image should be of type "unsigned int" or "int" whereas the output image is of type "int". Obviously, if the user wishes to utilize the image spacing or to have a filter with the Euclidean distance (as opposed to the squared distance), output image types of float or double should be used. +A **distance map** replaces every pixel with its distance to the nearest object boundary. This filter computes the **exact** Euclidean distance (not an approximation) using the Maurer algorithm, which runs in linear time for images of any dimension. -The inside is considered as having negative distances. Outside is treated as having positive distances. To change the convention, use the InsideIsPositive(bool) function. +It produces a **signed** distance map: pixels **inside** an object are given **negative** distances and pixels **outside** are given **positive** distances. By default inside is negative; enable *Inside Is Positive* to flip the convention. Unlike the Danielsson filters, this filter does not produce a Voronoi map. - Parameters -Set/GetBackgroundValue specifies the background of the value of the input binary image. Normally this is zero and, as such, zero is the default value. Other than that, the usage is completely analogous to the itk::DanielssonDistanceImageFilter class except it does not return the Voronoi map. +Use this when you need an accurate signed Euclidean distance field — for example as a level-set input or for precise distance-from-boundary measurements. -Reference: C. R. Maurer, Jr., R. Qi, and V. Raghavan, "A Linear Time Algorithm - for Computing Exact Euclidean Distance Transforms of Binary Images in - Arbitrary Dimensions", IEEE - Transactions on Pattern Analysis and Machine Intelligence, 25(2): 265-270, 2003. +> Important — the default output is the **squared** distance, not the distance itself. *Squared Distance* is enabled by default so the filter can stay in fast integer arithmetic. To get true (un-squared) Euclidean distance, turn *Squared Distance* off. + +> Note: for true Euclidean distances, or when *Use Image Spacing* is enabled, choose a floating-point output array type. An integer output can only represent the squared, pixel-unit distances correctly. + +### Parameter Guidance + +- **Inside Is Positive** — by default, pixels inside an object are negative and pixels outside are positive. Enable this to reverse the convention. +- **Squared Distance** — when enabled (the default), the output holds the distance **squared**. Disable it to get the actual (linear) distance. +- **Use Image Spacing** — when enabled, distances are measured in the image's **physical units** (using pixel spacing). When disabled, distances are measured in **pixels**. +- **Background Value** — the input intensity that marks the background. Object pixels are everything else. Normally *0* (the default). + +### Required Input Sources + +Requires a binary image where the *Background Value* marks background and all other pixels mark object. This is typically a segmentation mask produced upstream. + +## See Also + +- [ITK Danielsson Distance Map Image Filter](ITKDanielssonDistanceMapImageFilter.md) +- [ITK Signed Maurer Distance Map Image Filter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1SignedMaurerDistanceMapImageFilter.html) + +Reference: C. R. Maurer, Jr., R. Qi, and V. Raghavan, "A Linear Time Algorithm for Computing Exact Euclidean Distance Transforms of Binary Images in Arbitrary Dimensions," IEEE Transactions on Pattern Analysis and Machine Intelligence, 25(2): 265-270, 2003. % Auto generated parameter table will be inserted here @@ -26,7 +42,7 @@ Reference: C. R. Maurer, Jr., R. Qi, and V. Raghavan, "A Linear Time Algorithm ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSinImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSinImageFilter.md index 083e962ee5..ea25f9afee 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSinImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSinImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The computations are performed using std::sin(x). +Computes the sine of each pixel. Pixel values are interpreted as radians; the output is in the range [-1, 1]. Operates on any scalar image. ![](Images/ITKSinImageFilter.png) @@ -18,7 +18,7 @@ The computations are performed using std::sin(x). ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSmoothingRecursiveGaussianImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSmoothingRecursiveGaussianImageFilter.md deleted file mode 100644 index ff678f8f0e..0000000000 --- a/src/Plugins/ITKImageProcessing/docs/ITKSmoothingRecursiveGaussianImageFilter.md +++ /dev/null @@ -1,29 +0,0 @@ -# ITK Smoothing Recursive Gaussian Image Filter - -Computes the smoothing of an image by convolution with the Gaussian kernels implemented as IIR filters. - -## Group (Subgroup) - -ITKSmoothing (Smoothing) - -## Description - -This filter is implemented using the recursive gaussian filters. For multi-component images, the filter works on each component independently. - -For this filter to be able to run in-place the input and output image types need to be the same and/or the same type as the RealImageType. - -## See Also - -- [RecursiveGaussianImageFilter::SetNormalizeAcrossScale](https://itk.org/Doxygen/html/classitk_1_1RecursiveGaussianImageFilter::SetNormalizeAcrossScale.html)| - -% Auto generated parameter table will be inserted here - -## Example Pipelines - -## License & Copyright - -Please see the description file distributed with this plugin. - -## DREAM3D Mailing Lists - -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSqrtImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSqrtImageFilter.md index de49cc6cc6..59391479a7 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSqrtImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSqrtImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The computations are performed using std::sqrt(x). +Replaces each pixel value with its square root. The input image should contain only non-negative values, since the square root of a negative number is undefined. Pixel values are in image intensity units. ![](Images/ITKSqrtImageFilter.png) diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSquareImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSquareImageFilter.md index 9a1d2f4153..1f2c7c6631 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKSquareImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKSquareImageFilter.md @@ -8,6 +8,8 @@ ITKImageIntensity (ImageIntensity) ## Description +Replaces each pixel with the square of its value. + ![](Images/ITKSquareImageFilter.png) % Auto generated parameter table will be inserted here diff --git a/src/Plugins/ITKImageProcessing/docs/ITKStandardDeviationProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKStandardDeviationProjectionImageFilter.md deleted file mode 100644 index a1f47077c2..0000000000 --- a/src/Plugins/ITKImageProcessing/docs/ITKStandardDeviationProjectionImageFilter.md +++ /dev/null @@ -1,45 +0,0 @@ -# ITK Standard Deviation Projection Image Filter - -Standard deviation projection. - -## Group (Subgroup) - -ITKImageStatistics (ImageStatistics) - -## Description - -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 - -## Author - -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. - -## See Also - -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) - -- [MedianProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MedianProjectionImageFilter.html) - -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) - -- [SumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1SumProjectionImageFilter.html) - -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) - -- [MaximumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MaximumProjectionImageFilter.html) - -- [MinimumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinimumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -% Auto generated parameter table will be inserted here - -## Example Pipelines - -## License & Copyright - -Please see the description file distributed with this plugin. - -## DREAM3D Mailing Lists - -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKSumProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKSumProjectionImageFilter.md deleted file mode 100644 index 6077ef71a4..0000000000 --- a/src/Plugins/ITKImageProcessing/docs/ITKSumProjectionImageFilter.md +++ /dev/null @@ -1,45 +0,0 @@ -# ITK Sum Projection Image Filter - -Sum projection. - -## Group (Subgroup) - -ITKImageStatistics (ImageStatistics) - -## Description - -This class was contributed to the Insight Journal by Gaetan Lehmann. The original paper can be found at https://www.insight-journal.org/browse/publication/71 - -## Author - -- Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. - -## See Also - -- [ProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1ProjectionImageFilter.html) - -- [MedianProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MedianProjectionImageFilter.html) - -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) - -- [MeanProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MeanProjectionImageFilter.html) - -- [MaximumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MaximumProjectionImageFilter.html) - -- [MinimumProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1MinimumProjectionImageFilter.html) - -- [BinaryProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1BinaryProjectionImageFilter.html) - -- [StandardDeviationProjectionImageFilter](https://itk.org/Doxygen/html/classitk_1_1StandardDeviationProjectionImageFilter.html) - -% Auto generated parameter table will be inserted here - -## Example Pipelines - -## License & Copyright - -Please see the description file distributed with this plugin. - -## DREAM3D Mailing Lists - -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKTanImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKTanImageFilter.md index 5ea89f31fe..2247935f1c 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKTanImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKTanImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The computations are performed using std::tan(x). +Computes the tangent of each pixel. Pixel values are interpreted as radians. Operates on any scalar image. % Auto generated parameter table will be inserted here @@ -16,7 +16,7 @@ The computations are performed using std::tan(x). ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKThresholdImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKThresholdImageFilter.md index ade9f26f03..ad42572d51 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKThresholdImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKThresholdImageFilter.md @@ -1,6 +1,6 @@ # ITK Threshold Image Filter -Set image values to a user-specified value if they are below, above, or between simple threshold values. +Replaces pixels that fall outside a chosen intensity range with a single "outside" value while leaving in-range pixels unchanged. ## Group (Subgroup) @@ -8,21 +8,24 @@ ITKThresholding (Thresholding) ## Description -ThresholdImageFilter sets image values to a user-specified "outside" value (by default, "black") if the image values are below, above, or between simple threshold values. +This filter clips an image by intensity. Every pixel whose value lies **within the range [Lower, Upper]** keeps its original value; every pixel **outside** that range is replaced with the *Outside Value*: -The available methods are: +$$ +\text{output}(x) = \begin{cases} x & \text{if } \text{Lower} \le x \le \text{Upper} \\ \text{OutsideValue} & \text{otherwise} \end{cases} +$$ -ThresholdAbove() : The values greater than the threshold value are set to OutsideValue +Use this filter when you want to mask away intensities that are too low or too high while preserving the actual pixel values inside the band of interest. This is different from the [Binary Threshold](ITKBinaryThresholdImageFilter.md) filter, which replaces *every* pixel with one of two labels (it binarizes); here the in-range pixels retain their measured intensity. -ThresholdBelow() : The values less than the threshold value are set to OutsideValue +### Parameter Guidance -ThresholdOutside() : The values outside the threshold range (less than lower or greater than upper) are set to OutsideValue +- **Lower** / **Upper** — the bounds of the range to keep, in the **input image's intensity units**. Pixels below *Lower* or above *Upper* are set to the *Outside Value*. To keep everything above a value, set *Lower* and leave *Upper* at its maximum; to keep everything below a value, set *Upper* and leave *Lower* at its minimum. +- **Outside Value** — the intensity written for every out-of-range pixel (in the image's intensity units, default *0*). -Note that these definitions indicate that pixels equal to the threshold value are not set to OutsideValue in any of these methods +### Required Input Sources -The pixels must support the operators >= and <=. +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -![](Images/ITKThresholdImageFilter.png) +![Threshold result.](Images/ITKThresholdImageFilter.png) % Auto generated parameter table will be inserted here @@ -30,7 +33,7 @@ The pixels must support the operators >= and <=. ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKThresholdMaximumConnectedComponentsImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKThresholdMaximumConnectedComponentsImageFilter.md index fe257ea8ca..5bb750564d 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKThresholdMaximumConnectedComponentsImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKThresholdMaximumConnectedComponentsImageFilter.md @@ -1,6 +1,6 @@ # ITK Threshold Maximum Connected Components Image Filter -Finds the threshold value of an image based on maximizing the number of objects in the image that are larger than a given minimal size. +Automatically picks the threshold that yields the most distinct objects above a minimum size, then produces a binary image. ## Group (Subgroup) @@ -8,34 +8,34 @@ ITKConnectedComponents (ConnectedComponents) ## Description -This method is based on Topological Stable State Thresholding to calculate the threshold set point. This method is particularly effective when there are a large number of objects in a microscopy image. Compiling in Debug mode and enable the debug flag for this filter to print debug information to see how the filter focuses in on a threshold value. Please see the Insight Journal's MICCAI 2005 workshop for a complete description. References are below. +This filter automatically selects a threshold rather than asking you for an intensity cutoff. It searches for the threshold value that **maximizes the number of connected objects** larger than a given minimum size, then binarizes the image at that threshold. Because the chosen threshold separates as many real objects as possible while merging or dropping noise-sized blobs, the filter is well suited to **counting many small objects** — for example cells or particles in a microscopy image. -### Parameters +The lower threshold boundary is computed by the filter; you supply the upper boundary of the search and the minimum object size. Pixels that pass the selected threshold are written with the *Inside Value* and all others with the *Outside Value*. -The MinimumObjectSizeInPixels parameter is controlled through the class Get/SetMinimumObjectSizeInPixels() method. Similar to the standard itk::BinaryThresholdImageFilter the Get/SetInside and Get/SetOutside values of the threshold can be set. The GetNumberOfObjects() and GetThresholdValue() methods return the number of objects above the minimum pixel size and the calculated threshold value. +### Parameter Guidance -### Automatic Thresholding in ITK +- **Minimum Object Size In Pixels** — the smallest connected region (in **pixels**) that counts as an object. Regions smaller than this are treated as noise and ignored when the filter optimizes the threshold. Default *0* (count everything). +- **Upper Boundary** — the upper limit of the threshold search, in the **input image's intensity units**. The filter computes the lower boundary automatically. Default is the maximum intensity of the pixel type. +- **Inside Value** — the output value written for pixels that pass the selected threshold (a `uint8` label, default *1*). +- **Outside Value** — the output value written for all other pixels (a `uint8` label, default *0*). -There are multiple methods to automatically calculate the threshold intensity value of an image. As of version 4.0, ITK has a Thresholding ( ITKThresholding ) module which contains numerous automatic thresholding methods.implements two of these. Topological Stable State Thresholding works well on images with a large number of objects to be counted. +### Required Input Sources -## References - -1) Urish KL, August J, Huard J. "Unsupervised segmentation for myofiber counting in immunofluorescent microscopy images". Insight Journal. ISC/NA-MIC/MICCAI Workshop on Open-Source Software (2005) https://insight-journal.org/browse/publication/40 -2) Pikaz A, Averbuch, A. "Digital image thresholding based on topological -stable-state". Pattern Recognition, 29(5): 829-843, 1996. +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. -## Questions +% Auto generated parameter table will be inserted here -email Ken Urish at ken.urish(at)gmail.com Please cc the itk list serve for archival purposes. +## References -% Auto generated parameter table will be inserted here +1. Urish KL, August J, Huard J. "Unsupervised segmentation for myofiber counting in immunofluorescent microscopy images." Insight Journal, ISC/NA-MIC/MICCAI Workshop on Open-Source Software (2005). +2. Pikaz A, Averbuch A. "Digital image thresholding based on topological stable-state." Pattern Recognition, 29(5): 829-843, 1996. ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMaximaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMaximaImageFilter.md index 7640064986..7fb9c28800 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMaximaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMaximaImageFilter.md @@ -1,14 +1,6 @@ # ITK Valued Regional Maxima Image Filter -Transforms the image so that any pixel that is not a regional maxima is set to the minimum value for the pixel type. Pixels that are regional maxima retain their value. - -The pixel neighborhood is controlled by the FullyConnected attribute. All adjacent pixels are included in -the neighborhood when FullyConnected=True and the diagonally adjacent pixels are not included when -FullyConnected=False. Different terminology is often used to describe neighborhoods – one common ex- -ample is the “connectivity” notation, which refers to the number of pixels in the neighborhood. FullyCon- -nected=False corresponds to a connectivty of 4 in 2D and 6 in 3D, while FullyConnected=True corresponds -to a connectivity of 8 in 2D and 26 in 3D. FullyConnected=False is also commonly referred to as “face -connected”. +Marks regional maxima while preserving their original pixel intensities; all other pixels are set to the pixel-type minimum. ## Group (Subgroup) @@ -16,19 +8,21 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Regional maxima are flat zones surrounded by pixels of lower value. A completely flat image will be marked as a regional maxima by this filter. +A regional maximum is a connected flat zone of pixels that all share the same value and whose every neighboring pixel has a strictly lower value. Unlike the binary [ITK Regional Maxima Image Filter](ITKRegionalMaximaImageFilter.md), this filter keeps each regional-maximum pixel at its original intensity and sets every other pixel to the minimum value for the pixel type, so the relative brightness of the detected peaks is retained. A completely flat image is marked entirely as a regional maximum. + +The pixel neighborhood is controlled by the **Fully Connected** attribute. When it is off ("face connected"), only face-adjacent pixels are considered neighbors, corresponding to a connectivity of 4 in 2D and 6 in 3D. When it is on, diagonally adjacent pixels are also included, corresponding to a connectivity of 8 in 2D and 26 in 3D; this tends to merge nearby maxima into a single connected region. + +### Parameter Guidance -This code was contributed in the Insight Journal paper: "Finding regional extrema - methods and performance" by Beare R., Lehmann G. +- **Fully Connected Components**: See the connectivity discussion above. Leave off for standard face-connected behavior. -### Author +### Required Input Sources - Richard Beare. Department of Medicine, Monash University, Melbourne, Australia. +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. -### Related Filters +### See Also -- ValuedRegionalMinimaImageFilter -- ValuedRegionalExtremaImageFilter -- HMinimaImageFilter +- [ITK Valued Regional Minima Image Filter](ITKValuedRegionalMinimaImageFilter.md) % Auto generated parameter table will be inserted here @@ -36,7 +30,7 @@ This code was contributed in the Insight Journal paper: "Finding regional extrem ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMinimaImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMinimaImageFilter.md index 95d7bef3f2..74941269e0 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMinimaImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKValuedRegionalMinimaImageFilter.md @@ -1,6 +1,6 @@ # ITK Valued Regional Minima Image Filter -Transforms the image so that any pixel that is not a regional minima is set to the maximum value for the pixel type. Pixels that are regional minima retain their value. +Marks regional minima while preserving their original pixel intensities; all other pixels are set to the pixel-type maximum. ## Group (Subgroup) @@ -8,18 +8,21 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Regional minima are flat zones surrounded by pixels of higher value. A completely flat image will be marked as a regional minima by this filter. +A regional minimum is a connected flat zone of pixels that all share the same value and whose every neighboring pixel has a strictly higher value. Unlike the binary [ITK Regional Minima Image Filter](ITKRegionalMinimaImageFilter.md), this filter keeps each regional-minimum pixel at its original intensity and sets every other pixel to the maximum value for the pixel type, so the relative darkness of the detected valleys is retained. A completely flat image is marked entirely as a regional minimum. -This code was contributed in the Insight Journal paper: "Finding regional extrema - methods and performance" by Beare R., Lehmann G. +The pixel neighborhood is controlled by the **Fully Connected** attribute. When it is off ("face connected"), only face-adjacent pixels are considered neighbors, corresponding to a connectivity of 4 in 2D and 6 in 3D. When it is on, diagonally adjacent pixels are also included, corresponding to a connectivity of 8 in 2D and 26 in 3D; this tends to merge nearby minima into a single connected region. -### Author +### Parameter Guidance - Richard Beare. Department of Medicine, Monash University, Melbourne, Australia. +- **Fully Connected Components**: See the connectivity discussion above. Leave off for standard face-connected behavior. -### Related Filters +### Required Input Sources -- ValuedRegionalMaximaImageFilter , ValuedRegionalExtremaImageFilter , -- HMinimaImageFilter +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or a prior ITK image filter. + +### See Also + +- [ITK Valued Regional Maxima Image Filter](ITKValuedRegionalMaximaImageFilter.md) % Auto generated parameter table will be inserted here @@ -27,7 +30,7 @@ This code was contributed in the Insight Journal paper: "Finding regional extrem ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin**. ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKWhiteTopHatImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKWhiteTopHatImageFilter.md index c4e2b009eb..1536e54427 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKWhiteTopHatImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKWhiteTopHatImageFilter.md @@ -1,6 +1,6 @@ # ITK White Top Hat Image Filter -White top hat extracts local maxima that are larger than the structuring element. +Extracts small bright features by subtracting the grayscale opening from the original image. ## Group (Subgroup) @@ -8,32 +8,39 @@ ITKMathematicalMorphology (MathematicalMorphology) ## Description -Top-hats are described in Chapter 4.5 of Pierre Soille's book "Morphological Image Analysis: Principles and Applications", Second Edition, Springer, 2003. +The **white top-hat** isolates small **bright** features — bright spots and narrow bright ridges smaller than the **structuring element** (the probe shape swept over the image). It is computed as the original image minus its grayscale **opening**, which leaves the small bright details on a flat (near-zero) background. A common use is correcting uneven (bright) background illumination or extracting small bright details for measurement. The dark-feature counterpart is [ITK Black Top Hat Image Filter](ITKBlackTopHatImageFilter.md). -### Author +### Parameter Guidance - Gaetan Lehmann. Biologie du Developpement et de la Reproduction, INRA de Jouy-en-Josas, France. +- **Kernel Radius** — the radius of the structuring element, **in pixels** (one value per axis). It sets the size scale: features smaller than the structuring element are extracted, larger structures are removed. +- **Safe Border** — when on (default), a temporary border is added during processing to avoid edge artifacts and removed afterward. -### Related Filters +#### Kernel Type -![](Images/ITKWhiteTopHat.png) - -### Kernel Type - -The *Kernel Type* parameter selects the structuring element used for the morphological operation: +The *Kernel Type* parameter selects the structuring element shape: - **Annulus [0]**: A ring-shaped structuring element. - **Ball [1]**: A spherical structuring element (default). Most commonly used for general morphological operations. - **Box [2]**: A rectangular/cuboid structuring element. - **Cross [3]**: A cross-shaped structuring element. +### Required Input Sources + +Operates on any scalar (grayscale) image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +![White top-hat example.](Images/ITKWhiteTopHat.png) + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 4.5). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/ITKImageProcessing/docs/ITKZeroCrossingImageFilter.md b/src/Plugins/ITKImageProcessing/docs/ITKZeroCrossingImageFilter.md index cf01c32f8a..e2e6f4c2f2 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKZeroCrossingImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs/ITKZeroCrossingImageFilter.md @@ -1,6 +1,6 @@ # ITK Zero Crossing Image Filter -This filter finds the closest pixel to the zero-crossings (sign changes) in a signed itk::Image . +Marks the pixels that sit at sign changes (zero crossings) of a signed image, which typically correspond to edges. ## Group (Subgroup) @@ -8,25 +8,27 @@ ITKImageFeature (ImageFeature) ## Description -Pixels closest to zero-crossings are labeled with a foreground value. All other pixels are marked with a background value. The algorithm works by detecting differences in sign among neighbors using city-block style connectivity (4-neighbors in 2d, 6-neighbors in 3d, etc.). +A **zero crossing** is a place where a signed image changes sign — going from positive to negative or vice versa. When the input is a second-derivative image such as a Laplacian, these sign changes line up with the edges in the original image, so detecting them is a common edge-finding step. -## Parameter Information +This filter examines each pixel and its immediate neighbors using city-block (face) connectivity — 4 neighbors in 2D, 6 in 3D. Where a sign change is found, the pixel nearest the crossing is labeled as foreground; every other pixel is labeled as background. The result is a thin, binary edge map. -- The input to this filter is an itk::Image of arbitrary dimension. The algorithm assumes a signed data type (zero-crossings are not defined for unsigned int data types), and requires that operator>, operator<, operator==, and operator!= are defined. +The input must be a **signed** image. Zero crossings are not defined for unsigned data, since unsigned values never go negative. -- The output of the filter is a binary, labeled image of user-specified type. By default, zero-crossing pixels are labeled with a default "foreground" value of itk::NumericTraits::OneValue() , where OutputDataType is the data type of the output image. All other pixels are labeled with a default "background" value of itk::NumericTraits::ZeroValue() . +Use this filter after computing a Laplacian (or other signed response) to extract edge locations. -- There are two parameters for this filter. ForegroundValue is the value that marks zero-crossing pixels. The BackgroundValue is the value given to all other pixels. +### Parameter Guidance -## See Also +- **Foreground Value** — the label written to pixels that lie on a zero crossing (the detected edges). Default *1*. +- **Background Value** — the label written to all other pixels. Default *0*. -- [Image](https://itk.org/Doxygen/html/classitk_1_1Image.html) +### Required Input Sources -- [Neighborhood](https://itk.org/Doxygen/html/classitk_1_1Neighborhood.html) +Requires a **signed** scalar image whose sign changes are meaningful — most commonly the output of a Laplacian-of-Gaussian step such as [ITK Laplacian Recursive Gaussian Image Filter](ITKLaplacianRecursiveGaussianImageFilter.md). -- [NeighborhoodOperator](https://itk.org/Doxygen/html/classitk_1_1NeighborhoodOperator.html) +## See Also -- [NeighborhoodIterator](https://itk.org/Doxygen/html/classitk_1_1NeighborhoodIterator.html) +- [ITK Laplacian Recursive Gaussian Image Filter](ITKLaplacianRecursiveGaussianImageFilter.md) +- [ITK ZeroCrossingImageFilter (ITK Doxygen)](https://itk.org/Doxygen/html/classitk_1_1ZeroCrossingImageFilter.html) % Auto generated parameter table will be inserted here @@ -34,8 +36,8 @@ Pixels closest to zero-crossings are labeled with a foreground value. All other ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKBoundedReciprocalImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKBoundedReciprocalImageFilter.md similarity index 70% rename from src/Plugins/ITKImageProcessing/docs/ITKBoundedReciprocalImageFilter.md rename to src/Plugins/ITKImageProcessing/docs_disabled/ITKBoundedReciprocalImageFilter.md index 98c42b427d..108d07bd63 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKBoundedReciprocalImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKBoundedReciprocalImageFilter.md @@ -8,7 +8,7 @@ ITKImageIntensity (ImageIntensity) ## Description -The filter expects both the input and output images to have the same number of dimensions, and both of a scalar image type. +Computes `1 / (1 + x)` for each pixel value `x`. For non-negative input intensities the result is bounded in the range `(0, 1]`, which makes this filter useful for mapping an unbounded intensity range into a normalized interval. Output values are dimensionless. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/ITKImageProcessing/docs_disabled/ITKMorphologicalWatershedFromMarkersImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKMorphologicalWatershedFromMarkersImageFilter.md new file mode 100644 index 0000000000..ec8279c66f --- /dev/null +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKMorphologicalWatershedFromMarkersImageFilter.md @@ -0,0 +1,38 @@ +# ITK Morphological Watershed From Markers Image Filter + +Marker-controlled watershed segmentation: floods the image from user-supplied seeds so that each seed produces exactly one labeled region. + +## Group (Subgroup) + +ITKWatersheds (Watersheds) + +## Description + +The **watershed transform** treats a grayscale image as a terrain (bright = high ground, dark = low ground) and floods it from its low points, partitioning it into **catchment basins** separated by **watershed lines**. Run on its own, a watershed almost always produces far more regions than there are real objects, because every small dip seeds a basin (over-segmentation). + +The **marker-controlled** variant fixes this. Instead of seeding a basin at every local minimum, it floods only from a set of **markers** — labeled seed points the user places, typically one marker per object of interest plus one for the background. Exactly one output region is produced per marker, and each output region carries that marker's label. Choosing good markers (for example, the centers of objects found by thresholding and [ITK Connected Component Image Filter](ITKConnectedComponentImageFilter.md)) is what makes this approach robust. + +> **Not currently available:** in ITK this filter takes *two* images — the image to flood (usually a gradient/edge image) and a separate **marker (seed) label image**. The DREAM3D-NX wrapper only exposes a single input array (no marker-image parameter), so it is **not built into the application** at present. See [bluequartzsoftware/simplnx#1639](https://github.com/BlueQuartzSoftware/simplnx/issues/1639). For an unseeded watershed, use [ITK Morphological Watershed Image Filter](ITKMorphologicalWatershedImageFilter.md). + +### Parameter Guidance + +- **Mark Watershed Line** — when on, the boundary pixels between regions are written as 0; when off, no separating line is drawn. +- **Fully Connected** — controls neighbor connectivity (face-only versus face + edge + corner). Turn it on for thin, one-pixel-wide features. + +The output is a label image whose region labels come from the marker labels. Compare with the unseeded [ITK Morphological Watershed Image Filter](ITKMorphologicalWatershedImageFilter.md). + +## Reference + +Pierre Soille, *Morphological Image Analysis: Principles and Applications*, Second Edition, Springer, 2003 (Chapter 9.2). Beare R., Lehmann G., "The watershed transform in ITK — discussion and new developments," Insight Journal, . + +% Auto generated parameter table will be inserted here + +## Example Pipelines + +## License & Copyright + +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs/ITKNormalizeToConstantImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKNormalizeToConstantImageFilter.md similarity index 76% rename from src/Plugins/ITKImageProcessing/docs/ITKNormalizeToConstantImageFilter.md rename to src/Plugins/ITKImageProcessing/docs_disabled/ITKNormalizeToConstantImageFilter.md index e16ae7ad32..c9e7bdfd03 100644 --- a/src/Plugins/ITKImageProcessing/docs/ITKNormalizeToConstantImageFilter.md +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKNormalizeToConstantImageFilter.md @@ -1,4 +1,4 @@ -# ITK Normalize To Constant Image Filter (ITKNormalizeToConstantImage) +# ITK Normalize To Constant Image Filter Scales image pixel intensities to make the sum of all pixels equal a user-defined constant. @@ -8,9 +8,11 @@ ITKImageIntensity (ImageIntensity) ## Description -The default value of the constant is 1. It can be changed with SetConstant() . +Scales every pixel so that the sum of all pixel values equals the user-defined Constant. This transform is especially useful for normalizing a convolution kernel. -This transform is especially useful for normalizing a convolution kernel. +### Parameter Guidance + +- **Constant**: The target sum for all pixel values after scaling. This is a dimensionless value with a default of 1. This code was contributed in the Insight Journal paper: ["FFT based convolution" by Lehmann G. https://insight-journal.org/browse/publication/717](https://insight-journal.org/browse/publication/717) @@ -35,6 +37,6 @@ convolution" by Lehmann G. https://insight-journal.org/browse/publication/717](h Please see the description file distributed with this plugin. -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs_disabled/ITKSmoothingRecursiveGaussianImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKSmoothingRecursiveGaussianImageFilter.md new file mode 100644 index 0000000000..10abe07292 --- /dev/null +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKSmoothingRecursiveGaussianImageFilter.md @@ -0,0 +1,32 @@ +# ITK Smoothing Recursive Gaussian Image Filter + +Gaussian blur computed recursively, so the run time stays constant no matter how large the blur — preferred for wide smoothing. + +## Group (Subgroup) + +ITKSmoothing (Smoothing) + +## Description + +This filter produces the same kind of **Gaussian blur** as [ITK Discrete Gaussian Image Filter](ITKDiscreteGaussianImageFilter.md), but implements it with a recursive (IIR) approximation. The key advantage is that its cost is **independent of the blur width (sigma)** — a large blur takes no longer than a small one — so it is the better choice when smoothing strongly. For multi-component images each component is smoothed independently. + +### Parameter Guidance + +- **Sigma** — the Gaussian standard deviation (the blur radius). Larger values blur more. By default it is measured in the geometry's **physical/world units** (or pixels if image spacing is not used). It is specified as an integer value; typical values are around 1-3. +- **Normalize Across Scale** — a scale-normalization option used mainly when comparing the responses of this filter at several different Sigma values (multi-scale analysis); leave off for ordinary smoothing. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +% Auto generated parameter table will be inserted here + +## Example Pipelines + +## License & Copyright + +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs_disabled/ITKStandardDeviationProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKStandardDeviationProjectionImageFilter.md new file mode 100644 index 0000000000..211f48e911 --- /dev/null +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKStandardDeviationProjectionImageFilter.md @@ -0,0 +1,37 @@ +# ITK Standard Deviation Projection Image Filter + +Collapses a 3D volume to a 2D image by taking the standard deviation of voxel values along one axis. + +## Group (Subgroup) + +ITKImageStatistics (ImageStatistics) + +## Description + +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **standard deviation**: for each line of voxels parallel to the selected axis, the output voxel measures how much the values along that line vary about their mean. The result has one fewer dimension than the input. + +Where the volume is uniform along the collapsed axis, the standard deviation is near zero (dark). Where intensity varies strongly along that axis, the result is large (bright). Use this filter to **highlight variability** — for example, to find regions that change through a stack of slices rather than to summarize their average value. + +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` + +### Parameter Guidance + +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +% Auto generated parameter table will be inserted here + +## Example Pipelines + +## License & Copyright + +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/docs_disabled/ITKSumProjectionImageFilter.md b/src/Plugins/ITKImageProcessing/docs_disabled/ITKSumProjectionImageFilter.md new file mode 100644 index 0000000000..3e26910d7b --- /dev/null +++ b/src/Plugins/ITKImageProcessing/docs_disabled/ITKSumProjectionImageFilter.md @@ -0,0 +1,41 @@ +# ITK Sum Projection Image Filter + +Collapses a 3D volume to a 2D image by summing voxel values along one axis. + +## Group (Subgroup) + +ITKImageStatistics (ImageStatistics) + +## Description + +A **projection** collapses a 3D volume into a 2D image by combining all voxels along one axis into a single output value. This filter uses the **sum**: for each line of voxels parallel to the selected axis, the output voxel is the total of all values along that line. The result has one fewer dimension than the input. + +Sum projection accumulates intensity through the volume, much like an X-ray-style integrated view where the output brightness reflects the total material or signal along each line of sight. + +```{warning} +Summing many voxels can produce values far larger than any single input voxel. If the output array uses the same data type as the input (for example, an 8-bit or 16-bit integer), the accumulated sum can **exceed the type's range and overflow**, wrapping around to incorrect values. Convert the image to a wider type (such as float32) before this filter when overflow is a concern. +``` + +```{note} +This filter changes the dimensionality of the **Image Geometry** that the data is tied to. As a side effect, **every** Data Array stored in the same Attribute Matrix as the input and output array is also affected. +``` + +### Parameter Guidance + +- *Projection Dimension* — the axis to collapse, given as an index: *0*, *1*, or *2*. Index *0* is the slowest-moving dimension. The output image keeps the two remaining axes. + +### Required Input Sources + +Operates on any scalar image — typically from [Read Image](../SimplnxCore/ReadImageFilter.md), [Read Images [3D Stack]](../SimplnxCore/ReadImageStackFilter.md), or the output of a prior ITK image filter. + +% Auto generated parameter table will be inserted here + +## Example Pipelines + +## License & Copyright + +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/ITKImageProcessing/src/ITKImageProcessing/Filters/ITKIsoContourDistanceImageFilter.cpp b/src/Plugins/ITKImageProcessing/src/ITKImageProcessing/Filters/ITKIsoContourDistanceImageFilter.cpp index 507b380552..10aab17051 100644 --- a/src/Plugins/ITKImageProcessing/src/ITKImageProcessing/Filters/ITKIsoContourDistanceImageFilter.cpp +++ b/src/Plugins/ITKImageProcessing/src/ITKImageProcessing/Filters/ITKIsoContourDistanceImageFilter.cpp @@ -73,7 +73,10 @@ Parameters ITKIsoContourDistanceImageFilter::parameters() const Parameters params; params.insertSeparator(Parameters::Separator{"Input Parameter(s)"}); params.insert(std::make_unique(k_LevelSetValue_Key, "Level Set Value", "Set/Get the value of the level set to be located. The default value is 0.", 0.0)); - params.insert(std::make_unique(k_FarValue_Key, "Far Value", "Set/Get the value of the level set to be located. The default value is 0.", 10)); + params.insert(std::make_unique(k_FarValue_Key, "Far Value", + "The saturation distance assigned to pixels that are not adjacent to the iso-contour. Pixels beyond the immediate neighborhood of the contour are " + "clamped to this value. The default value is 10.", + 10)); params.insertSeparator(Parameters::Separator{"Input Cell Data"}); params.insert(std::make_unique(k_InputImageGeomPath_Key, "Image Geometry", "Select the Image Geometry Group from the DataStructure.", DataPath({"Image Geometry"}), diff --git a/src/Plugins/OrientationAnalysis/docs/AlignSectionsMisorientationFilter.md b/src/Plugins/OrientationAnalysis/docs/AlignSectionsMisorientationFilter.md index 0e9674d464..98fb777f7d 100644 --- a/src/Plugins/OrientationAnalysis/docs/AlignSectionsMisorientationFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/AlignSectionsMisorientationFilter.md @@ -6,20 +6,34 @@ Reconstruction (Alignment) ## Description -This **Filter** attempts to align consecutive 'sections' perpendicular to the Z-direction of the sample by determining the position that results in the minimum amount of misorientation between **Cells** directly above-below each other. The algorithm of this **Filter** is as follows: +This **Filter** aligns serial sections (2D slices stacked along the Z-direction) by finding the shift that minimizes the crystal orientation mismatch between cells on neighboring slices. This is the most commonly used alignment method for EBSD data because it directly uses the orientation information measured at each point. -1. Calculate the misorientation between each **Cell** in a section and the **Cell** directly above it in the next section -2. Count the number of **Cell** pairs that have a misorientation above the user defined tolerance and store that as the misalignment value for that position -3. Repeat steps 1 and 2 for each position when shifting the second slice (relative to the first) from three (3) **Cells** to the left to three (3) **Cells** to the right, as well as from three (3) **Cells** up to three (3) **Cells** down. *Note that this creates a 7x7 grid* -4. Determine the position in the 7x7 grid that has the lowest misalignment value. (It will be the position with the fewest different **Cell** pairs) -5. Repeat steps 1-4 with the center of each (new) 7x7 grid at the best position from the last 7x7 grid until the best position in the current/new 7x7 grid is the same as the last 7x7 grid -6. Repeat steps 1-5 for each pair of neighboring sections +### When to Use This Method -**Note that this is similar to a downhill simplex and can get caught in a local minimum!** +Use this method when your data contains crystal orientation measurements (quaternions or Euler angles) and you want to align sections based on the actual crystallographic content. This works well for most EBSD datasets. For data without orientation information, consider the [Align Sections (Feature Centroid)](../SimplnxCore/AlignSectionsFeatureCentroidFilter.md) or [Align Sections (Mutual Information)](AlignSectionsMutualInformationFilter.md) methods instead. -If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process. +### How This Filter Works -The user can also decide to remove a *background shift* present in the sample. The process for this is to fit a line to the X and Y shifts along the Z-direction of the sample. The individual shifts are then modified to make the slope of the fit line be 0. Effectively, this process is trying to keep the top and bottom section of the sample fixed. Some combinations of sample geometry and internal features can result in this algorithm introducing a 'shear' in the sample and the *Linear Background Subtraction* will attempt to correct for this. +The filter uses an iterative grid search to find the optimal alignment for each pair of neighboring sections: + +1. For a given relative position of two sections, calculate the misorientation between each **Cell** on the lower section and the **Cell** directly above it on the upper section +2. Count the number of cell pairs whose misorientation exceeds the user-defined tolerance. This count is the "misalignment score" for that position -- lower is better +3. Evaluate the misalignment score at all 49 positions in a 7x7 grid (shifting the upper section from -3 to +3 cells in both X and Y) +4. Select the position with the lowest misalignment score +5. Re-center the 7x7 grid on the best position and repeat until the best position no longer changes +6. Repeat for each pair of neighboring sections + +### Local Minima Warning + +This iterative grid search is similar to a downhill simplex optimization and **can get caught in a local minimum**. If alignment results look incorrect, try adjusting the misorientation tolerance or consider using the [Align Sections (Feature Centroid)](../SimplnxCore/AlignSectionsFeatureCentroidFilter.md) method, which does not have this limitation. + +### Masking + +If a mask array is provided, **Cells** flagged as *false* are excluded from the alignment calculation. This is useful for ignoring regions of bad data or regions outside the sample boundary. + +### Linear Background Subtraction + +Some combinations of sample geometry and internal features can cause the alignment to introduce a gradual "shear" across the sample. Enabling *Linear Background Subtraction* corrects for this by fitting a line to the X and Y shifts along the Z-direction and removing the linear trend. This effectively keeps the top and bottom sections of the sample fixed relative to each other. ## Optional Output Data @@ -44,12 +58,18 @@ In this new structure, what follows is what the created structures represent: In previous versions a file would have been produced instead. If you wish to recreate this, you can write the Attribute Matrix as a CSV/Text file. +### 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). +- **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). +- **Mask** (optional) -- a boolean array marking valid cells, typically produced by a threshold operation such as [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -+ (02) Small IN100 Full Reconstruction ++ `(02) Small IN100 Full Reconstruction` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/AlignSectionsMutualInformationFilter.md b/src/Plugins/OrientationAnalysis/docs/AlignSectionsMutualInformationFilter.md index 9fe3485150..7f267e4db7 100644 --- a/src/Plugins/OrientationAnalysis/docs/AlignSectionsMutualInformationFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/AlignSectionsMutualInformationFilter.md @@ -6,25 +6,35 @@ Reconstruction (Alignment) ## Description -This **Filter** segments each 2D slice, creating *Feature Ids* that are used when determining the *mutual information* between neighboring slices. The slices are shifted relative to one another until the position of maximum *mutual information* is determined for each section. The *Feature Ids* are temporary, they apply to this **Filter** only and are not related to the *Feature Ids* generated in other **Filters**. The algorithm of this **Filter** is listed below: +This **Filter** aligns serial sections (2D slices stacked along the Z-direction) by maximizing the *mutual information* between the feature patterns on neighboring slices. Rather than comparing individual cell orientations (as in [Align Sections (Misorientation)](AlignSectionsMisorientationFilter.md)), this method first groups cells into temporary features on each slice, then finds the shift that best aligns those feature patterns between slices. -1. Segment *Features* on each 'section' of the sample perpendicular to the Z-direction. This is done using the same algorithm in the [Segment Features (Misorientation)](@ref alignsectionsmisorientation) **Filter** (only in 2D on each section) -2. Calculate the *mutual information* between neighboring sections and store that as the misalignment value for that position. *Mutual information* is related to the ratio of joint probability to individual probabilities of variables (i.e., p(x,y)/p(x)p(y) ). Details of the actual *mutual information* calculation can be found in the references below, but can be thought of as the inherent dependence between variables (here the *Feature Ids* on neighboring sections). -3. Repeat step 2 for each position when shifting the second slice (relative to the first) from three (3) **Cells** to the left -to three (3) **Cells** to the right, as well as from three (3) **Cells** up to three (3) **Cells** down -*Note that this creates a 7x7 grid* -4. Determine the position in the 7x7 grid that has the highest *mutual information* value -5. Repeat steps 2-4 with the center of each (new) 7x7 grid at the best position from the last 7x7 grid until the best position in the current/new 7x7 grid is the same as the last 7x7 grid +### When to Use This Method -6) Repeat steps 2-5 for each pair of neighboring sections +This method is useful when feature-level pattern matching is more appropriate than cell-level orientation comparison. It can sometimes produce better results than misorientation-based alignment when the data has significant noise or when features are large relative to the misalignment. -**Note that this is similar to a downhill simplex and can get caught in a local minimum!** +### What is Mutual Information? -The user choses the level of *misorientation tolerance* by which to align **Cells**, where here the tolerance means the *misorientation* cannot exceed a given value. If the rotation angle is below the tolerance, then the **Cell** is grouped with other **Cells** that satisfy the criterion. +Mutual information is a statistical measure of how much information one variable provides about another. In this context, it measures how well the feature patterns on two neighboring slices correspond to each other. High mutual information means the features on one slice strongly predict the features on the adjacent slice -- indicating good alignment. -The approach used in this **Filter** is to group neighboring **Cells** on a slice that have a *misorientation* below the tolerance the user entered. *Misorientation* here means the minimum rotation angle of one **Cell's** crystal axis needed to coincide with another **Cell's** crystal axis. When the **Features** in the slices are defined, they are moved until *disks* in neighboring slices align with each other. +### How This Filter Works -If the user elects to use a mask array, the **Cells** flagged as *false* in the mask array will not be considered during the alignment process. +1. **Segment features on each slice:** Neighboring cells on each 2D slice are grouped into temporary features using a misorientation tolerance (the same algorithm as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md), applied in 2D). These feature IDs are internal to this filter and are not stored. +2. **Calculate mutual information:** For a given relative position of two slices, compute the mutual information between the feature ID patterns on the two slices. +3. **Grid search:** Evaluate the mutual information at all 49 positions in a 7x7 grid (shifting the upper slice from -3 to +3 cells in both X and Y). Select the position with the highest mutual information. +4. **Iterate:** Re-center the 7x7 grid on the best position and repeat until the best position no longer changes. +5. **Repeat** for each pair of neighboring sections. + +### Misorientation Tolerance + +The *misorientation tolerance* parameter controls how cells are grouped into temporary features on each slice. Cells whose orientations differ by less than this tolerance are grouped together. Lower values produce more, smaller features; higher values produce fewer, larger features. + +### Local Minima Warning + +This iterative grid search is similar to a downhill simplex optimization and **can get caught in a local minimum**. If alignment results look incorrect, try adjusting the misorientation tolerance or consider using the [Align Sections (Feature Centroid)](../SimplnxCore/AlignSectionsFeatureCentroidFilter.md) method, which does not have this limitation. + +### Masking + +If a mask array is provided, **Cells** flagged as *false* are excluded from the alignment calculation. ## Optional Output Data @@ -49,6 +59,13 @@ In this new structure, what follows is what the created structures represent: In previous versions a file would have been produced instead. If you wish to recreate this, you can write the Attribute Matrix as a CSV/Text file. +### 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). +- **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). +- **Mask** (optional) -- a boolean array marking valid cells, typically produced by a threshold operation such as [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + % Auto generated parameter table will be inserted here ## References @@ -65,7 +82,7 @@ Journal articles on *Mutual Information* that are useful: ## Example Pipelines -AlignSectionsMutualInformation ++ `AlignSectionsMutualInformation` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/BadDataNeighborOrientationCheckFilter.md b/src/Plugins/OrientationAnalysis/docs/BadDataNeighborOrientationCheckFilter.md index c2030698d3..ba46453696 100644 --- a/src/Plugins/OrientationAnalysis/docs/BadDataNeighborOrientationCheckFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/BadDataNeighborOrientationCheckFilter.md @@ -6,55 +6,54 @@ Processing (Cleanup) ## Description -This filter will change the value of a cell's `mask` value from **False** to **True** based on the misorientation between the target -cell and it's 6-face neighbors. This filter should be used to target isolated -voxels inside potential features (grains). +This **Filter** rescues *bad* cells (those with *Mask = false*) that are surrounded by good cells with consistent orientations. It does **not** modify any cell-level attributes other than the **Mask** array; it only flips the *Mask* value of qualifying cells from **false** to **true**, effectively re-classifying them as good. -### Algorithm Description +This is a sister filter to [Neighbor Orientation Correlation](NeighborOrientationCorrelationFilter.md). The key difference: this filter only updates the mask, while *Neighbor Orientation Correlation* copies full cell attributes from a neighbor. Use this filter as the **first pass** to recover cells that were marked bad by an over-aggressive threshold but are genuinely surrounded by valid neighbors; use *Neighbor Orientation Correlation* afterward to clean up cells whose orientation is genuinely wrong. -For each cell (voxel) in the input Image Geometry, if the *Mask* value of the target cell is **FALSE**, -then the misorientation between that cell and each of its 6-face -neighbor cells is calculated. If the number of misorientation values that fall below the -user defined threshold is equal to or greater than the user defined value of -`Required Number of Neighbors` then the current cells `mask` value is changed from -**False** to **True**. +### How This Filter Works -The filter will iteratively reduce the required number of neighbors from 6 until -it reaches the user defined number. So, if the user selects a required number -of neighbors of 4, then the filter will run with a required number of neighbors -of 6, then 5, then 4 before finishing. +For each cell whose *Mask* is **false**: -During the algorithm since the `mask` array is being updated continuously, each time -the `mask` array is updated, any neighbors of that changed voxel are evaluated again -to check if that neighbor now has the required number of valid neighbors. If this -check ends up being true then that neighbor voxel is added to the list of voxels to check. -This can lead to a **Flood Fill** type of algorithm. The user should take care to examine -the output from this filter to ensure that the filter is not being overly aggressive about -changing voxels. +1. Compute the misorientation between the cell and each of its 6 face-neighbors (cells in the +X, -X, +Y, -Y, +Z, -Z directions). +2. Count the number of neighbors whose misorientation falls below the user-specified *Misorientation Tolerance*. +3. If that count is at least *Required Number of Neighbors*, flip the cell's *Mask* from **false** to **true**. -### 2D Versus 3D Note +The filter steps down through *Required Number of Neighbors* from 6 to the user-defined floor: setting it to 4 runs at levels 6, 5, and 4 in sequence. -If the user is processing a 2D data set, **none** of the voxels can have 6 neighbors -since there are no neighbors in the +/-Z directions. +While the algorithm runs, the *Mask* array is updated continuously. When a cell's mask flips, its neighbors are re-evaluated -- they may now have enough valid neighbors to qualify themselves. **This can cascade into a flood fill**, especially if the user sets *Required Number of Neighbors* very low. Always inspect the output to confirm the filter is not overshooting. -### Warning - Data Modification +### Required Number of Neighbors -Only the *Mask* value defining the cell as *good* or *bad* is changed. No other cell level array is modified. +The *Required Number of Neighbors* parameter is the **count of agreeing face-neighbors needed to flip the mask** and ranges from **1 to 6**: -### Memory Considerations +- **6** -- only rescue cells where all 6 face-neighbors agree. Very conservative. +- **4-5** -- rescues most over-thresholded cells while leaving genuinely uncertain cells alone. +- **2-3** -- aggressive; risks cascading. +- **1** -- one matching neighbor is enough; effectively a flood fill. -The filter allocates a temporary `int32` neighbor-count array sized to the total voxel count -(4 bytes per voxel). For a 1-billion-voxel dataset, that is approximately 4 GB of additional -working memory during execution. This memory is released when the filter finishes. +### 2D vs 3D -## Example Data +In 2D data (Z dimension = 1), no cell can have 6 face-neighbors because there are no neighbors in the +Z and -Z directions. The maximum count for 2D is therefore 4. + +### Warning -- Data Modification + +Only the *Mask* array is modified. Every other cell-level array (orientations, phases, etc.) is left unchanged. To replace orientation data on cells whose orientations are wrong, run [Neighbor Orientation Correlation](NeighborOrientationCorrelationFilter.md) afterward. + +### Example Data | Example Input Image | Example Output Image | |---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | ![](Images/BadDataNeighborOrientationCheckFilter_1.png) | ![](Images/BadDataNeighborOrientationCheckFilter_2.png) | -| The Small IN100 data just after initial alignment filters have completed. | The Small IN100 data just after running this filter with a *Misorientation Tolerance* of 5 degrees and a *Required Number of Neighbors* of 4. | +| The Small IN100 data just after initial alignment filters have completed. | The Small IN100 data after running this filter with *Misorientation Tolerance* = 5° and *Required Number of Neighbors* = 4. | + +The cells that flipped from false (black) to true (IPF-colored) had Confidence Index just below the original mask threshold (CI > 0.1, IQ > 120) but had enough valid neighbors with consistent orientations to be rescued. + +### Required Input Sources -From the above before and after images you can see that this filter can help modify a mask that was generated through a simple threshold filter. This filter essentially uses neighbors to determine if a cell point should have had a mask value of false. The majority of cells that were changed from *false* or the black voxels, into valid IPF colored voxels, had a confidence index that fell just below the initial threshold applied (Confidence Index > 0.1 and Image Quality > 120). This filter determines that enough of that cell's neighbors had a mask value of true, the misorientation was < 5 degrees and the cell had enough valid neighbors that the cell's *mask* value was changed from **false** to **true**. +- **Mask Array** -- a boolean cell-level array, typically produced by [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) applied to EBSD confidence/quality scalars. +- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.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). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/CAxisSegmentFeaturesFilter.md b/src/Plugins/OrientationAnalysis/docs/CAxisSegmentFeaturesFilter.md index 6983636597..a83a205477 100644 --- a/src/Plugins/OrientationAnalysis/docs/CAxisSegmentFeaturesFilter.md +++ b/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 diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeAvgCAxesFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeAvgCAxesFilter.md index 7fafb63ad4..bbfe22e446 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeAvgCAxesFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeAvgCAxesFilter.md @@ -26,9 +26,9 @@ Each **Cell** (voxel) in a grain has its own measured orientation. This filter d This filter only produces valid results for hexagonal phases (6/mmm or 6/m symmetry). In hexagonal materials, the C-axis is unique -- there is only one [001] direction, so crystal symmetry does not create ambiguity. -In cubic materials, the [001], [010], and [100] directions are all crystallographically equivalent. Applying symmetry operators would move the [001] direction to different positions in the sample frame, making a simple average meaningless. For this reason, the filter **silently skips non-hexagonal cells** during accumulation. A **Feature** whose contributing cells are *all* non-hexagonal (or which has no cells assigned to it at all) will have its output set to **NaN**. +In cubic materials, the [001], [010], and [100] directions are all crystallographically equivalent. Applying symmetry operators would move the [001] direction to different positions in the sample frame, making a simple average meaningless. For this reason, **non-hexagonal phases will have their output values set to NaN**. -The filter will produce an error if no hexagonal phases are present in the data (`-76402`: "No phases that have a crystal symmetry of Hexagonal (6/mmm or 6/m) were found."). +The filter will produce an error if no hexagonal phases are present in the data. ### Required Input Sources diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeAvgOrientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeAvgOrientationsFilter.md index 0af418d45c..01643d23c2 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeAvgOrientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeAvgOrientationsFilter.md @@ -6,7 +6,11 @@ Statistics (Crystallography) ## Description -This **Filter** computes the average orientation of each **Feature** using one or more of three available averaging methods. Each method can be independently enabled, and their results are stored in separate output arrays. +This **Filter** computes the average crystal orientation for each **Feature** (grain). Since each grain is made up of many **Cells** (voxels) that each have their own measured orientation, this filter combines those individual measurements into a single representative orientation per grain. + +The average orientation is used by many downstream filters (e.g., misorientation calculations, Schmid factor, GBCD) and is one of the fundamental statistics computed during microstructure characterization. + +Three averaging methods are available, and each can be independently enabled. Their results are stored in separate output arrays. ### Method 1: Rodrigues Average (Original) @@ -71,6 +75,13 @@ These values may be exposed as user-configurable parameters in a future release. - **Multi-phase features:** The vMF/Watson methods use a single crystal structure per feature, taken from the phase of the feature's highest-index element; the Rodrigues method uses each element's own phase. Features are normally single-phase, so this distinction rarely matters. - **No method enabled:** If none of the three averaging methods is enabled the filter fails in preflight with error -54673. +### 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 Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.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). + % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeBoundaryStrengthsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeBoundaryStrengthsFilter.md index 3504791f0f..4b12758f8a 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeBoundaryStrengthsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeBoundaryStrengthsFilter.md @@ -6,39 +6,52 @@ Statistics (Crystallography) ## Description -**THIS FILTER ONLY WORKS ON Cubic m-3m LAUE CLASSES** +This **Filter** computes slip transmission metrics for each **Face** (triangle) on a grain boundary mesh. These metrics quantify how easily plastic deformation can transfer across a grain boundary, based on the geometric alignment of slip systems in the two grains on either side. -This **Filter** calculates the same metrics as in the Find Neighbor Slip Transmission Metrics **Filter**. However, this **Filter** stores the values in the **Face Attribute Matrix** of a **Triangle Geometry**. The algorithm the **Filter** uses is as follows: +This filter computes the same metrics as the [Compute Neighbor Slip Transmission Metrics](ComputeSlipTransmissionMetricsFilter.md) filter, but stores results per boundary **Face** rather than per **Feature**. This makes it suitable for visualization and analysis on a **Triangle Geometry** surface mesh. -1. Find the two **Features** that are separated by a **Face** in the **Triangle Geometry** -2. Get the average orientation of both of the **Features** -3. Calculate the transmission metrics from both directions (i.e. **Feature** 1 to **Feature** 2 and **Feature** 2 to **Feature** 1) -4. Store the metrics in the **Face** map -5. Repeat for all **Faces** +For a detailed explanation of the slip transmission concept and the individual metrics, see the [Compute Neighbor Slip Transmission Metrics](ComputeSlipTransmissionMetricsFilter.md) documentation. -*Note:* Each metric is calculated twice for the two different directions slip could approach the boundary. The values are stored on each **Face** in the **Face** map in a way that notes the direction (i.e., when **Feature** 1 has neighbor **Feature** 2 and when **Feature** 2 has neighbor **Feature** 1) because the direction across the boundary between the **Features** affects the value of the metric. +### Cubic Materials Only -## Luster-Morris Parameter (M' Values) +This filter only works on **cubic m-3m Laue classes**. -The values are calculated as presented in [1]. +### How This Filter Works -## Fracture Initiation Parameter (fip) +1. For each **Face** in the **Triangle Geometry**, the filter identifies the two **Features** on either side +2. The average orientation of both **Features** is retrieved +3. Transmission metrics are calculated in both directions (Feature 1 → Feature 2 and Feature 2 → Feature 1), since the direction of slip approaching the boundary affects the result +4. Both directional values are stored on the **Face** -Three (3) *fip* values are computed as outputs to this filter. These are best explained in [2], see page 021012-4 +### Luster-Morris Parameter (M') + +The Luster-Morris parameter measures geometric compatibility between slip systems across a boundary. Calculated as presented in [1]. + +### Fracture Initiation Parameters (F1, F1spt, F7) + +Three fracture initiation parameter values are computed per **Face**, as defined in [2] (see page 021012-4): ![Fracture Initiation Parameter F1](Images/ComputeNeighborSlipTransmission_F1.png) ![Fracture Initiation Parameter F1spt](Images/ComputeNeighborSlipTransmission_F1spt.png) -![Fracture Initiation Parameter F7.png](Images/ComputeNeighborSlipTransmission_F7.png) - +![Fracture Initiation Parameter F7](Images/ComputeNeighborSlipTransmission_F7.png) -## Citations +## References [1] [Luster, J., Morris, M.A., 1995. *Compatibility Of Deformation In Two-Phase Ti-Al Alloys: Dependence On Microstructure And Orientation Relationships*. **Metallurgical and Materials Transactions A 26, 1745**](https://link.springer.com/article/10.1007/BF02670762) [2] [D. Kumar, T. R. Bieler, P. Eisenlohr, D. E. Mason, M. A. Crimp, F. Roters, and D. Raabe. On Predicting Nucleation of Microcracks Due to Slip Twin Interactions at Grain Boundaries in Duplex Near γ-TiAl. Journal of Engineering Materials and Technology, 130(2):021012–12, 2008. doi:10.1115/1.2841620.](https://doi.org/10.1115/1.2841620) +### Required Input Sources + +This filter operates on a grain-boundary surface mesh and requires the following upstream steps: + +- **Triangle Geometry** and **Face Labels** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md). +- **Average Quaternions** -- the per-feature average orientation produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeCAxisLocationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeCAxisLocationsFilter.md index 9183413de0..b7bba6a59f 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeCAxisLocationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeCAxisLocationsFilter.md @@ -6,15 +6,41 @@ Statistics (Crystallography) ## Description -This **Filter** determines the direction of the C-axis for each **Element** by applying the quaternion of the **Element** to the <001> direction, which is the C-axis for *Hexagonal* materials. This will tell where the C-axis of the **Element** sits in the *sample reference frame*. +This **Filter** computes the C-axis direction for each individual **Cell** (voxel) in hexagonal materials. The result is a unit vector per **Cell** that indicates where that cell's C-axis points in the sample reference frame. -*Note:* This **Filter** will only work properly for *Hexagonal* materials. The **Filter** does not apply any symmetry operators because there is only one c-axis (<001>) in *Hexagonal* materials and thus all symmetry operators will leave the c-axis in the same position in the sample *reference frame*. However, in *Cubic* materials, for example, the {100} family of directions are all equivalent and the <001> direction will change location in the *sample reference frame* when symmetry operators are applied. +### What is the C-Axis? + +In hexagonal crystal structures (such as titanium, magnesium, and zinc), the *C-axis* is the unique crystallographic direction that runs along the long axis of the hexagonal unit cell (the [001] direction). This axis is important because many mechanical and physical properties of hexagonal materials vary depending on whether they are measured along or perpendicular to the C-axis. + +![Fig. 1: The C-axis in a hexagonal unit cell.](Images/ComputeAvgCAxes_HexagonalCAxis.png) + +### How This Filter Works + +Each **Cell** has a measured crystal orientation stored as a quaternion. This filter uses that orientation to rotate the crystal [001] direction into the physical sample coordinate system, producing a 3D unit vector that describes where the C-axis points. + +The output vectors are normalized to unit length and constrained to the upper hemisphere (positive Z component) to provide a unique, unambiguous representation. + +### Hexagonal Materials Only + +This filter only produces valid results for hexagonal phases (6/mmm or 6/m symmetry). In hexagonal materials, the C-axis is unique -- there is only one [001] direction, so crystal symmetry does not create ambiguity. + +In cubic materials, the [001], [010], and [100] directions are all crystallographically equivalent. Applying symmetry operators would move the [001] direction to different positions in the sample frame, making this computation ambiguous. For this reason, **non-hexagonal phases will have their output values set to NaN**. + +### Comparison with Compute Average C-Axis Orientations + +This filter computes the C-axis direction for each individual **Cell**. If you need the average C-axis direction for each **Feature** (grain) instead, use the [Compute Average C-Axis Orientations](ComputeAvgCAxesFilter.md) filter. + +### 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). % Auto generated parameter table will be inserted here ## Example Pipelines -EBSD_Hexagonal_Data_Analysis ++ `EBSD_Hexagonal_Data_Analysis` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborCAxisMisalignmentsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborCAxisMisalignmentsFilter.md index 2119f12cfa..bc7d2006c7 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborCAxisMisalignmentsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborCAxisMisalignmentsFilter.md @@ -6,25 +6,39 @@ Statistics (Crystallography) ## Description -For each feature, the C-Axis misalignments are determined for each neighbor of the feature. The neighbor list is a variable that is passed in by the user. This "NeighborList" could have been generated from any other appropriate filter. This means that a neighbor list could represent all neighbors that are physically connected to the current feature (Find Feature Neighbors), within a certain radius of the feature (Compute Feature Neighborhoods) or any other custom filter. +This **Filter** computes the C-axis misalignment angle between each **Feature** (grain) and its neighbors in hexagonal materials. The C-axis misalignment is the angular difference between the C-axis directions of two neighboring grains -- it measures how closely their unique crystallographic axes are aligned. -There are 2 outputs from this filter: -- The list of misalignments -- Optionally the average of all misalignments. +This is distinct from a full misorientation, which considers the complete rotational difference between two crystal orientations. C-axis misalignment only considers the alignment of the [001] direction, which is often the most mechanically significant axis in hexagonal materials. -**The misalignment values are stored as Degrees.** +### Flexible Neighbor Definition -### Notes +The neighbor list is supplied by the user and can come from any filter that produces neighbor relationships. For example: +- [Compute Feature Neighbors](../SimplnxCore/ComputeFeatureNeighborsFilter.md) -- neighbors that physically share a boundary +- [Compute Feature Neighborhoods](../SimplnxCore/ComputeNeighborhoodsFilter.md) -- neighbors within a specified radius +- Any other custom filter that generates a neighbor list -**NOTE:** Only features with identical phase values and a crystal structure of **Hexagonal_High** (6/mmm) or **Hexagonal_Low** (6/m) will be calculated. If two features have different phase values, or if the shared phase has a crystal structure that is not one of the two hexagonal Laue classes, then a value of NaN is set for the misalignment. +The filter also optionally computes the average misalignment across all of a feature's neighbors. -Results from this filter can differ from its original version in DREAM.3D 6.5.171 by around 0.0001 degrees. This version uses double precision and Eigen for matrix operations which account for the differences in output. +### Hexagonal Materials Only + +Only **Features** with identical phase values and a crystal structure of **Hexagonal_High** (6/mmm) or **Hexagonal_Low** (Hexagonal 6/m (C6h)) are compared. If two **Features** have different phases or a non-hexagonal crystal structure, a value of NaN is stored for the misalignment. See the [Compute Average C-Axis Orientations](ComputeAvgCAxesFilter.md) documentation for an explanation of why C-axis calculations are restricted to hexagonal materials. + +### Note + +Results from this filter may differ from the original DREAM.3D 6.5 version by approximately 0.0001 degrees due to the use of double precision and Eigen for matrix operations. + +### Required Input Sources + +- **Neighbor List** -- produced by [Compute Feature Neighbors](../SimplnxCore/ComputeFeatureNeighborsFilter.md) or [Compute Feature Neighborhoods](../SimplnxCore/ComputeNeighborhoodsFilter.md). +- **Average Quaternions** -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -EBSD_Hexagonal_Data_Analysis ++ `EBSD_Hexagonal_Data_Analysis` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborMisorientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborMisorientationsFilter.md index e8f05cbef5..5e8ec709ba 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborMisorientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureNeighborMisorientationsFilter.md @@ -6,19 +6,30 @@ Statistics (Crystallography) ## Description -This **Filter** determines, for each **Feature**, the misorientations with each of the **Features** that are in contact with it. The misorientations are stored as a list (for each **Feature**) of angles (in degrees). The axis of the misorientation is not stored by this **Filter**. +This **Filter** computes the misorientation angle between each **Feature** (grain) and its neighboring **Features**. Misorientation is the angular difference between the crystal orientations of two grains -- it describes how much one grain's crystal lattice is rotated relative to another's. -The user can also calculate the average misorientation between the feature and all contacting features. +![Fig. 1: The misorientation between two grains is the rotation relating their crystal orientations; its angle is the misorientation angle. Because a crystal has symmetry-equivalent orientations, the smallest equivalent angle — the disorientation — is what the filter reports.](Images/Misorientation_Concept.png) -### Notes +For each **Feature**, the filter produces a list of misorientation angles (in degrees), one for each neighboring **Feature** it shares a boundary with. The axis of the misorientation is not stored, only the angle. -**NOTE:** Only features with identical crystal structures will be calculated. If two features have different crystal structures then a value of NaN is set for the misorientation. +Optionally, the filter can also compute the average misorientation between a **Feature** and all of its neighbors. This average value provides a quick summary of how differently oriented a grain is compared to its surroundings. + +### Note + +Only **Features** with identical crystal structures are compared. If two neighboring **Features** have different crystal structures, a value of NaN is stored for their misorientation, since misorientation between different crystal systems is not physically meaningful. + +### Required Input Sources + +- **Neighbor List** -- produced by [Compute Feature Neighbors](../SimplnxCore/ComputeFeatureNeighborsFilter.md) or [Compute Feature Neighborhoods](../SimplnxCore/ComputeNeighborhoodsFilter.md). +- **Average Quaternions** -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -+ (04) Small IN100 Crystallographic Statistics ++ `(05) SmallIN100 Crystallographic Statistics` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceCAxisMisorientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceCAxisMisorientationsFilter.md index 197a9b68cf..96759db1c3 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceCAxisMisorientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceCAxisMisorientationsFilter.md @@ -6,17 +6,40 @@ Statistics (Crystallography) ## Description -This **Filter** calculates the misorientation angle between the C-axis of each **Cell** within a **Feature** and the average C-axis for that **Feature** and stores that value for each **Cell**. The average and standard deviation of those values for all **Cells** belonging to the same **Feature** is also stored for each **Feature**. +This **Filter** measures how much the C-axis orientation varies within each **Feature** (grain) in hexagonal materials. It does this by comparing the C-axis direction of each individual **Cell** (voxel) to the average C-axis direction for the grain it belongs to. -This filter requires at least one Hexagonal crystal structure phase (Hexagonal-Low 6/m or Hexagonal-High 6/mmm). Although it is not recommended, you can give input data with mixed phase types and all non hexagonal phases will be skipped in the calculations. +This metric is useful for characterizing intragranular orientation gradients -- regions within a grain where the crystal lattice has rotated relative to the grain's average orientation, which can indicate deformation, subgrain boundaries, or measurement noise. -Results from this filter can differ from its original version in DREAM3D 6.6 by around 0.0001. This version uses double precision in part of its calculation to improve agreement and accuracy between platforms (notably ARM). +### What This Filter Computes + +For each **Cell**, the filter calculates the angle (in degrees) between that cell's C-axis and the average C-axis of its parent **Feature**. The filter then computes summary statistics per **Feature**: + +- **Average misalignment** -- the mean C-axis deviation across all cells in the grain +- **Standard deviation** -- how much the deviation varies within the grain + +A low average misalignment indicates a grain with a uniform C-axis orientation. A high value suggests significant internal orientation variation. + +### Hexagonal Materials Only + +This filter requires at least one hexagonal crystal structure phase (6/m or 6/mmm). Non-hexagonal phases are skipped. See the [Compute Average C-Axis Orientations](ComputeAvgCAxesFilter.md) documentation for an explanation of why C-axis calculations are restricted to hexagonal materials. + +### Note + +Results may differ from the DREAM3D 6.6 version by approximately 0.0001 degrees due to improved double-precision calculations for cross-platform accuracy. + +### Required Input Sources + +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md) or [Segment Features (C-Axis Misalignment)](CAxisSegmentFeaturesFilter.md). +- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.md). +- **Cell Phases** -- typically read from EBSD data alongside the quaternions. +- **Average C-Axes** -- produced by [Compute Average C-Axis Orientations](ComputeAvgCAxesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -EBSD_Hexagonal_Data_Analysis ++ `EBSD_Hexagonal_Data_Analysis` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceMisorientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceMisorientationsFilter.md index 4332b76d13..50bd9b9d53 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceMisorientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeFeatureReferenceMisorientationsFilter.md @@ -6,16 +6,16 @@ Statistics (Crystallography) ## Description -This **Filter** calculates the misorientation angle between each **Cell** within a **Feature** and a -*reference orientation* for that **Feature**. The user can choose the *reference orientation* to -be used for the **Features** from a drop-down menu. The options for the *reference orientation* are -the average orientation of the **Feature** or the orientation of the **Cell** that is furthest from -the *boundary* of the **Feature**. +This **Filter** measures how much crystal orientation varies within each **Feature** (grain) by computing the misorientation angle between each **Cell** (voxel) and a chosen *reference orientation* for that **Feature**. -Note: the average orientation of the **Feature** is a typical choice, but if the **Feature** has -undergone plastic deformation and the amount of lattice rotation developed is of interest, then -it may be more reasonable to use the orientation *near the center* of the **Feature** as it may -not have rotated and thus serve as a better *reference orientation*. +This is useful for detecting intragranular orientation gradients caused by plastic deformation, subgrain formation, or other processes that cause the crystal lattice to rotate within a grain. + +### Choosing a Reference Orientation + +The user selects the reference orientation from two options. The choice depends on the physical question being asked: + +- **Average Feature Orientation** -- Uses the average orientation of all cells in the grain. This is the typical choice for characterizing overall orientation spread within a grain. +- **Orientation Farthest from Feature Boundary** -- Uses the orientation of the cell nearest to the Euclidean center of the grain (farthest from any boundary). If the grain has undergone plastic deformation, boundary regions tend to rotate more than the interior. Using the center cell as the reference provides a more stable baseline that better reveals the pattern of lattice rotation from the interior outward. ### Reference Orientation @@ -53,6 +53,15 @@ feature boundary, and use that voxel's orientation as the **reference orientatio ![ComputeFeatureReferenceMisorientations_1.png](Images/ComputeFeatureReferenceMisorientations_1.png) +### Required Input Sources + +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md). +- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.md). +- **Cell Phases** -- typically read from EBSD data alongside the quaternions. +- **Average Quaternions** (for Average Feature Orientation mode) -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Boundary Euclidean Distances** (for Orientation Farthest from Feature Boundary mode) -- produced by [Compute Euclidean Distance Map](../SimplnxCore/ComputeEuclideanDistMapFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeGBCDFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeGBCDFilter.md index 5bb54a2536..8c5f756a67 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeGBCDFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeGBCDFilter.md @@ -6,13 +6,55 @@ Statistics (Crystallography) ## Description -This **Filter** computes the 5D grain boundary character distribution (GBCD) for a **Triangle Geometry**, which is the relative area of grain boundary for a given misorientation and normal. The GBCD can be visualized by using either the **Write GBCD Pole Figure (GMT)** or the **Write GBCD Pole Figure (VTK)** **Filters**. +This **Filter** computes the Grain Boundary Character Distribution (GBCD) for a **Triangle Geometry**. The GBCD is a statistical description of the types of grain boundaries present in a polycrystalline material. It answers the question: *"What fraction of the total grain boundary area has a given misorientation and boundary plane orientation?"* + +### What is the GBCD? + +In a polycrystalline material, grains meet at boundaries. Each boundary can be described by five parameters: + +- **3 parameters** for the *misorientation* -- the rotational difference between the crystal orientations of the two grains on either side of the boundary +- **2 parameters** for the *boundary plane normal* -- the direction the boundary surface faces, expressed in the crystal reference frame + +The GBCD is a histogram over this 5-dimensional space. It records how much grain boundary area exists for each combination of misorientation and boundary plane orientation, normalized so that a random distribution would give a value of 1.0. Results are reported in *multiples of a random distribution* (MRD), so a value of 2.0 means there is twice as much boundary of that type as would be expected in a random polycrystal. + +### How This Filter Works + +1. For each triangular face on the grain boundary mesh, the filter identifies the two grains on either side. +2. It computes the misorientation between the two grains and determines the boundary plane normal in the crystal reference frame. +3. Crystal symmetry is applied to map each boundary into a unique representation. +4. The boundary is placed into the appropriate bin of the 5D histogram, weighted by its area. +5. The result is normalized by the total boundary area. + +The **GBCD Resolution** parameter controls the bin size of the histogram. Smaller values give finer resolution but require more boundary data for statistical reliability. + +### Note + +Only boundaries between grains of the same phase are included in the calculation. The GBCD can be visualized by using the [Write GBCD Pole Figure (GMT)](WriteGBCDGMTFileFilter.md) or [Compute GBCD Pole Figure](ComputeGBCDPoleFigureFilter.md) filters. + +For an alternative approach to computing the GBCD using continuous metrics instead of binning, see the [Compute GBCD (Metric-Based Approach)](ComputeGBCDMetricBasedFilter.md) filter. + +### Required Input Sources + +This filter operates on a grain-boundary surface mesh and requires the following upstream steps: + +- **Triangle Geometry** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md), optionally followed by [Laplacian Smoothing](../SimplnxCore/LaplacianSmoothingFilter.md). +- **Face Labels** -- produced alongside the mesh by [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md). +- **Face Normals** -- produced by [Compute Triangle Normals](../SimplnxCore/TriangleNormalFilter.md). +- **Face Areas** -- produced by [Compute Triangle Areas](../SimplnxCore/ComputeTriangleAreasFilter.md). +- **Feature Euler Angles / Feature Phases** -- the feature-level average Euler angles and phases. Averages are produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md); phases by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). + +## References + +[1] G. S. Rohrer, "Grain boundary energy anisotropy: a review," *Journal of Materials Science*, vol. 46, pp. 5881-5895, 2011. DOI: [10.1007/s10853-011-5677-3](https://doi.org/10.1007/s10853-011-5677-3) + +[2] G. S. Rohrer, "Measuring and Interpreting the Structure of Grain-Boundary Networks," *Journal of the American Ceramic Society*, vol. 94, no. 3, pp. 633-646, 2011. DOI: [10.1111/j.1551-2916.2011.04384.x](https://doi.org/10.1111/j.1551-2916.2011.04384.x) % Auto generated parameter table will be inserted here ## Example Pipelines -+ (08) Small IN100 GBCD ++ `(08) Small IN100 GBCD` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeGBCDMetricBasedFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeGBCDMetricBasedFilter.md index 092dc86566..5ab6dffb45 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeGBCDMetricBasedFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeGBCDMetricBasedFilter.md @@ -6,11 +6,18 @@ Statistics (Crystallography) ## Description -This **Filter** computes a section through the five-dimensional grain boundary distirbution for a fixed misorientation. An example of such a section is shown in Fig. 1. Differently than **Compute GBCD Filter**, which uses a method based on partition of the boundary space into bins, this **Filter** implements an alternative metric-based approach described by K. Glowinski and A. Morawiec in [Analysis of experimental grain boundary distributions based on boundary-space metrics, Metall. Mater. Trans. A 45, 3189-3194 (2014)](https://link.springer.com/article/10.1007/s11661-014-2325-y) +This **Filter** computes a section through the five-dimensional grain boundary character distribution (GBCD) for a fixed misorientation, using a metric-based approach rather than binning. An example of such a section is shown in Fig. 1. + +Unlike the [Compute GBCD](ComputeGBCDFilter.md) filter, which partitions the boundary space into discrete bins, this filter uses a continuous metric-based approach described by K. Glowinski and A. Morawiec in [Analysis of experimental grain boundary distributions based on boundary-space metrics, Metall. Mater. Trans. A 45, 3189-3194 (2014)](https://link.springer.com/article/10.1007/s11661-014-2325-y). The metric-based approach avoids discretization artifacts and can produce smoother distributions, especially with limited data. ![Fig. 1: Section for the 17.9 deg./[111] misorientation through the grain boundary distribution obtained using this Filter for the small IN100 data set. Units are multiples of random distribution (MRDs).](Images/ComputeGBCDMetricBased_dist.png) -Metrics in the boundary space can be defined in a number of ways, but it is essential that two boundaries are close (distant) if they have similar (different) geometric features, and that symmetrically equivalent representations of boundaries are taken into consideration. Formally, the boundary space is a Cartesian product of the misorientation and boundary-normal subspaces. For computational reasons and because of considerably different resolutions in determinination of grain misorientation and boundary-plane parameters, it is convenient to use a separate metric in each subspace. With separate metrics, the procedure for computing distribution values for a selected misorientation has two stages. First, boundary segments with misorientations located not farther from the fixed misorientation than a limiting distance ρm are selected. In the second stage, the distribution is probed at evenly distributed normal directions (see Fig. 2), and areas of boundaries whose normals deviate from a given direction by less than ρp are summed. (The radii ρm and ρp should be tailored to resolution, amount, and quality of data and set.) Eventually, the obtained distribution is normalized in order to express it in the conventional units, i.e., multiples of the random distribution. +The metric-based approach defines distance measures in the boundary space so that boundaries with similar geometry are considered "close" and boundaries with different geometry are considered "distant," taking crystal symmetry into account. The procedure has two stages: + +1. **Misorientation selection:** Boundary segments whose misorientation is within a limiting angular distance ρm of the user-specified fixed misorientation are selected. +2. **Normal probing:** The distribution is sampled at evenly distributed normal directions (see Fig. 2). For each sampling direction, the areas of boundaries whose normals fall within ρp of that direction are summed. + +The limiting distances ρm and ρp should be chosen based on the resolution, amount, and quality of the data. The result is normalized and expressed in multiples of a random distribution (MRD). | Image | |-------| @@ -55,6 +62,14 @@ The *Limiting Distances* parameter selects the maximum angular deviations used w - **7 deg. Misorientations; 7 deg. Plane Inclinations [5]**: Use a 7-degree radius for both misorientations and plane inclinations. - **8 deg. Misorientations; 8 deg. Plane Inclinations [6]**: Use an 8-degree radius for both misorientations and plane inclinations. +### Required Input Sources + +This filter operates on a grain-boundary surface mesh and requires the following upstream steps: + +- **Triangle Geometry** with **Face Labels**, **Face Normals**, **Face Areas**, and **Node Types** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md), followed by [Compute Triangle Normals](../SimplnxCore/TriangleNormalFilter.md) and [Compute Triangle Areas](../SimplnxCore/ComputeTriangleAreasFilter.md). +- **Feature Euler Angles / Feature Phases** -- feature-level averages produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md) and [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). + % Auto generated parameter table will be inserted here ## References diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeGBPDMetricBasedFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeGBPDMetricBasedFilter.md index 6591151393..265e2664fd 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeGBPDMetricBasedFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeGBPDMetricBasedFilter.md @@ -6,7 +6,17 @@ Statistics (Crystallography) ## Description -This **Filter** computes the grain boundary plane distribution (GBPD) like that shown in Fig. 1. It should be noted that most GBPDs presented so far in literature were obtained using a method based on partition of the grain boundary space into bins, similar to that implemented in the *Compute GBCD* **Filter**. This **Filter** calculates the GBPD using an alternative approach adapted from the one included in the *Compute GBCD (Metric-based Approach)* **Filter** and described by K. Glowinski and A. Morawiec in [Analysis of experimental grain boundary distributions based on boundary-space metrics, Metall. Mater. Trans. A 45, 3189-3194 (2014)](http://link.springer.com/article/10.1007%2Fs11661-014-2325-y). Briefly, the GBPD is probed at evenly distributed sampling directions (similarly to *Compute GBCD (Metric-based Approach)* **Filter**) and areas of mesh segments with their normal vectors deviated by less than a limiting angle ρp from a given direction are summed. If *n*S is the number of crystal symmetry transformations, each boundary plane segment is represented by up to 4 × *n*S equivalent vectors, and all of them are processed. It is enough to sample the distribution at directions corresponding to the standard stereographic triangle (or, in general, to a fundamental region corresponding to a considered crystallographic point group); values at remaining points are obtained based on crystal symmetries. After summing the boundary areas, the distribution is normalized. First, the values at sampling vectors are divided by the total area of all segments. Then, in order to express the distribution in the conventional units, i.e., multiples of random distribution (MRDs), the obtained fractional values are divided by the volume *v* = (*A* nS) / (4π), where *A* is the area of a spherical cap determined by ρp. +This **Filter** computes the Grain Boundary Plane Distribution (GBPD), which describes the relative frequency of grain boundary plane orientations in a polycrystalline material, regardless of the misorientation across the boundary. While the GBCD (see [Compute GBCD](ComputeGBCDFilter.md)) describes boundaries in the full 5D space of misorientation + plane normal, the GBPD considers only the 2D distribution of boundary plane normals. + +An example GBPD is shown in Fig. 1. + +### Metric-Based Approach + +This filter uses a metric-based approach adapted from the [Compute GBCD (Metric-Based Approach)](ComputeGBCDMetricBasedFilter.md) filter, as described by K. Glowinski and A. Morawiec in [Analysis of experimental grain boundary distributions based on boundary-space metrics, Metall. Mater. Trans. A 45, 3189-3194 (2014)](http://link.springer.com/article/10.1007%2Fs11661-014-2325-y). + +The distribution is sampled at evenly distributed directions. For each sampling direction, the areas of mesh segments whose normals fall within a limiting angle ρp of that direction are summed. Crystal symmetry is applied so that each boundary segment is represented by up to 4 × *n*S equivalent vectors (where *n*S is the number of symmetry transformations). Only directions within the standard stereographic triangle need to be sampled; values at other points are obtained from symmetry. + +After summing boundary areas, the distribution is normalized to multiples of a random distribution (MRD). A value of 1.0 means that plane orientation is as frequent as in a random polycrystal; values above 1.0 indicate preferred boundary plane orientations. ![Fig. 1: GBPD obtained for Small IN100 with the limiting distance set to 7° and with triangles adjacent to triple lines removed. Units are MRDs.](Images/ComputeGBPDMetricBased_example.png) @@ -16,7 +26,7 @@ This **Filter** also calculates statistical errors of the distributions using th is the relative error of the distribution function at a given point, *f* is the value of the function at that point, and *n* stands for the number of grain boundaries (**not** the number of mesh triangles) in the considered network. The errors can be calculated either as their absolute values, i.e., ε × *f* or as relative errors, i.e., 100% × ε. The latter are computed in a way that if the relative error exceeds 100%, it is rounded down to 100%. -See also the documentation for {ref}`Compute GBCD (Metric-based Approach) Filter ` for additional information. +See also the documentation for [Compute GBCD (Metric-Based Approach)](ComputeGBCDMetricBasedFilter.md) for additional information. ## Format of Output Files @@ -32,6 +42,15 @@ Then, the directions are given as [ sin θ × cos φ , sin θ ## Feedback In the case of any questions, suggestions, bugs, etc., please feel free to email the author of this **Filter** at kglowinski *at* ymail.com + +### Required Input Sources + +This filter operates on a grain-boundary surface mesh and requires the following upstream steps: + +- **Triangle Geometry** with **Face Labels**, **Face Normals**, **Face Areas**, and **Node Types** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md), followed by [Compute Triangle Normals](../SimplnxCore/TriangleNormalFilter.md) and [Compute Triangle Areas](../SimplnxCore/ComputeTriangleAreasFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). + % Auto generated parameter table will be inserted here ## References diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeKernelAvgMisorientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeKernelAvgMisorientationsFilter.md index 29d6fd447c..375dd08423 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeKernelAvgMisorientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeKernelAvgMisorientationsFilter.md @@ -6,22 +6,64 @@ Statistics (Crystallography) ## Description -This **Filter** determines the Kernel Average Misorientation (KAM) for each **Cell**. The user can select the size of the kernel to be used in the calculation. The kernel size entered by the user is the *radius* of the kernel (i.e., entering values of *1*, *2*, *3* will result in a kernel that is *3*, *5*, and *7* **Cells** in size in the X, Y and Z directions, respectively). The algorithm for determination of KAM is as follows: +This **Filter** determines the Kernel Average Misorientation (KAM) for each **Cell**. The user can select the size of the kernel (in voxels) to be used in the calculation. The algorithm for the determination of KAM is as follows: -1. Calculate the misorientation angle between each **Cell** in a kernel and the central **Cell** of the kernel +1. Calculate the misorientation angle between each **Cell** in a kernel and the central **Cell** of the kernel **only** if the kernel cell belongs to the same `FeatureId`. 2. Average all of the misorientations for the kernel and store at the central **Cell** -The calculation will **not** consider cells that belong to different 'feature Ids', i.e., different grains. +Only **Cells** that belong to the same **Feature** (i.e., have the same Feature Id) as the central **Cell** are included in the average. -*Note:* All **Cells** in the kernel are weighted equally during the averaging, though they are not equidistant from the central **Cell**. +### Note + +All **Cells** in the kernel are weighted equally during the averaging, though they are not equidistant from the central **Cell**. + +### Understanding the Kernel Radius + +The *Kernel Radius* parameter has three components (X, Y, Z), and each value specifies how many **Cells** to extend outward from the center **Cell** along that axis. The resulting kernel size along each axis is: + +![Fig. 1: The kernel radius to kernel size formula.](Images/ComputeKernelAvgMisorientations_Formula.png) + +The kernel extends the specified radius in *both* directions (e.g., left and right) along each axis, plus includes the center **Cell** itself -- hence the formula. The radius can be set independently for each axis. For example, a Kernel Radius of *(1, 2, 3)* produces a kernel that is 3 × 5 × 7 **Cells** in the X, Y, and Z directions, respectively. + +#### 1D Examples + +Consider a single row of **Cells**. With a radius of 1, the kernel extends 1 **Cell** in each direction from the center, giving a kernel of size 3: + +![Fig. 2: 1D kernel with radius 1 produces a kernel size of 3.](Images/ComputeKernelAvgMisorientations_1D_Radius1.png) + +Increasing the radius to 2 extends 2 **Cells** in each direction, giving a kernel of size 5: + +![Fig. 3: 1D kernel with radius 2 produces a kernel size of 5.](Images/ComputeKernelAvgMisorientations_1D_Radius2.png) + +#### 2D Examples + +In 2D, the kernel forms a rectangular region around the center **Cell**. With a symmetric radius of (1, 1), the kernel is a 3 × 3 square: + +![Fig. 4: 2D kernel with radius (1, 1, 0) produces a 3x3 kernel of 9 cells.](Images/ComputeKernelAvgMisorientations_2D_Radius110.png) + +When different radii are used per axis, the kernel becomes non-square. With X Radius = 1 and Y Radius = 2, the kernel is 3 **Cells** wide and 5 **Cells** tall: + +![Fig. 5: 2D kernel with radius (1, 2, 0) produces a 3x5 kernel of 15 cells.](Images/ComputeKernelAvgMisorientations_2D_Radius120.png) + +In 3D, the Z Radius works the same way, extending into adjacent slices above and below the center **Cell**. + +#### Quick Reference + +![Fig. 6: Common radius values and their resulting kernel sizes.](Images/ComputeKernelAvgMisorientations_Table.png) + +### Required Input Sources + +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md). +- **Cell Quaternions** -- typically read from EBSD data via [Read H5EBSD](ReadH5EbsdFilter.md), [Read CTF Data](ReadCtfDataFilter.md), or [Read ANG Data](ReadAngDataFilter.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). % Auto generated parameter table will be inserted here ## Example Pipelines -+ (04) Small IN100 Crystallographic Statistics -+ EBSD_File_Processing/aptr12_Analysis -+ EBSD_File_Processing/avtr12_Analysis ++ `MassifPipeline` ++ `(05) SmallIN100 Crystallographic Statistics` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeSchmidsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeSchmidsFilter.md index fea1712097..dee10769d3 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeSchmidsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeSchmidsFilter.md @@ -6,19 +6,47 @@ Statistics (Crystallography) ## Description -This **Filter** calculates the Schmid factor of each **Feature** given its average orientation and a user defined loading axis. The Schmid Factor is the combination of the component of the axial force *F* that lies parallel to the slip direction and the component that lies perpendicular to the slip plane. The equation for the Schmid Factor is given as: +This **Filter** calculates the Schmid factor for each **Feature** (grain), which measures how favorably oriented that grain is for plastic deformation under a given loading direction. A higher Schmid factor means the grain is more likely to deform (slip) under the applied load. -Schmid Factor = (cos φ cos λ) +### What is the Schmid Factor? -*The angle φ is the angle between the tensile axis and the slip plane normal, and λ is the angle between the tensile axis and the slip direction in the slip plane.* +When a force is applied to a polycrystalline material, each grain responds differently depending on how its internal crystal planes are oriented relative to the loading direction. Deformation occurs by *slip* -- atoms sliding along specific crystal planes in specific directions. Each combination of a slip plane and a slip direction is called a *slip system*. -The **Filter** determines the Schmid factor for each **Feature** by using the above equation for all possible slip systems (given the **Feature's** crystal structure). The largest Schmid factor from all of the slip systems is stored for the **Feature**. Only the Schmid factor is used in determining which slip system's Schmid factor to report. The critical resolved shear stress for the different slip systems is not considered. +The Schmid factor quantifies how much of the applied force is resolved onto a given slip system: + +**Schmid Factor = cos(φ) × cos(λ)** + +where: + +- **φ** is the angle between the loading axis and the *slip plane normal* (the direction perpendicular to the slip plane) +- **λ** is the angle between the loading axis and the *slip direction* (the direction atoms slide along within the slip plane) + +The Schmid factor ranges from 0 to 0.5. A value of 0.5 means the slip system is optimally aligned with the applied load. A value near 0 means the slip system is poorly oriented for deformation. + +![Fig. 1: The geometric relationship between the tensile axis, slip plane, and slip direction that defines the Schmid factor.](Images/ComputeSchmids_SchmidFactor.png) + +### How This Filter Works + +1. The user specifies a **Loading Direction** as a unit vector in the sample reference frame (e.g., [0, 0, 1] for loading along the Z-axis). This is a dimensionless direction, not a magnitude. +2. For each **Feature**, the filter rotates the loading direction from the sample frame into the grain's crystal frame using the grain's average orientation. +3. The filter evaluates the Schmid factor for every slip system available for that grain's crystal structure. +4. By default, the slip system with the **largest** Schmid factor is reported. Alternatively, the user can specify a particular slip plane and slip direction to evaluate. + +### Note + +Only the geometric Schmid factor is considered. The critical resolved shear stress (CRSS), which varies between slip systems in real materials, is not taken into account. This means the reported "most favorable" slip system is based purely on geometric alignment, not on the actual stress required to activate slip. + +### Required Input Sources + +- **Average Quaternions** -- the per-feature average orientation produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -+ (05) SmallIN100 Crystallographic Statistics ++ `(05) SmallIN100 Crystallographic Statistics` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeShapesFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeShapesFilter.md index afc6050c09..b0e5c862ad 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeShapesFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeShapesFilter.md @@ -6,33 +6,48 @@ Statistics (Morphological) ## Description -This **Filter** calculates the second-order moments of each **Feature** in order to determine the *principal axis lengths, principal axis directions, aspect ratios and moment invariant Omega3s*. The *principal axis lengths* are those of a "best-fit" ellipsoid. The algorithm for determining the moments and these values is as follows: +This **Filter** characterizes the 3D shape of each **Feature** (grain or particle) by fitting a best-fit ellipsoid to its voxels. The result is a set of shape descriptors including axis lengths, aspect ratios, axis orientations, and a shape invariant (Omega3). -1. For each **Cell**, determine the x, y and z distance to the centroid of the **Feature** that owns the **Cell** -2. For each **Cell**, calculate Ixx, Iyy, Izz, Ixy, Ixz and Iyz using the x, y and z distances determined in step 1. -3. Sum the individual Ixx, Iyy, Izz, Ixy, Ixz and Iyz values for all **Cells** belonging to the same **Feature** -4. Find the *eigenvalues* and *eigenvectors* of the *3x3* symmetric matrix defined by the *6* values calculated in step 3 for each **Feature** -5. Use the relationship of *principal moments* to the *principal axis lengths* for an ellipsoid, which can be found in [4], to determine the *Semi-Axis Lengths* -6. Calculate the *Aspect Ratios* from the *Semi-Axis Lengths* found in step 5. -7. Determine the Euler angles required to represent the *principal axis directions* in the *sample reference frame* and store them as the **Feature**'s *Axis Euler Angles*. -8. Calculate the moment variant Omega3 as definied in [2] and is discussed further in [1] and [3] +### What This Filter Produces + +- **Semi-Axis Lengths** -- The half-lengths of the three principal axes of the best-fit ellipsoid (a ≥ b ≥ c). These describe the size and elongation of the grain. +- **Aspect Ratios** -- The ratios b/a and c/a, which describe the grain's shape independent of its size. An equiaxed (roughly spherical) grain has aspect ratios near 1.0; an elongated grain has lower values. +- **Axis Euler Angles** -- The orientation of the ellipsoid's principal axes in the sample reference frame, stored as Euler angles. These describe which direction the grain is elongated. +- **Omega3** -- A dimensionless shape invariant derived from the second-order moments [2]. Omega3 is 1.0 for a perfect sphere and decreases for shapes that deviate from spherical. It provides a single-number summary of how "round" a grain is, independent of its size or orientation. + +### How This Filter Works + +1. For each **Cell**, compute the x, y, and z distances from the cell center to the centroid of its parent **Feature** +2. Accumulate the second-order moment terms (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) for all **Cells** in each **Feature** +3. Solve for the eigenvalues and eigenvectors of the resulting 3x3 moment tensor for each **Feature** +4. Convert eigenvalues to ellipsoid semi-axis lengths using the relationship between principal moments and axis lengths [4] +5. Compute aspect ratios, axis orientation angles, and the Omega3 shape invariant + +### Note + +For shape analysis on triangle geometry meshes rather than voxelized image geometry, see the [Compute Feature Shapes (Triangle Geometry)](ComputeShapesTriangleGeomFilter.md) filter. + +### Required Input Sources + +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](../SimplnxCore/ScalarSegmentFeaturesFilter.md). +- **Feature Centroids** -- produced by [Compute Feature Centroids](../SimplnxCore/ComputeFeatureCentroidsFilter.md). % Auto generated parameter table will be inserted here -## References ## +## References [1] Representation and Reconstruction of Three-dimensional Microstructures in Ni-based Superalloys, AFOSR FA9550-07-1-0179 Final Report, 20 Dec 2010. -[2] On the use of moment invariants for the automated classifcation of 3-D particle shapes, J. MacSleyne, J.P. Simmons and M. De Graef, Modeling and Simulations in Materials Science and Engineering, 16, 045008 (2008). +[2] J. MacSleyne, J.P. Simmons, and M. De Graef. On the use of moment invariants for the automated classification of 3-D particle shapes. *Modeling and Simulations in Materials Science and Engineering*, 16, 045008 (2008). -[3] n-Dimensional Moment Invariants and Conceptual Mathematical Theory of Recognition n-Dimensional Solids, Alexander G. Mamistvalov, IEEE TRANSACTIONS ON PATTERN ANALYSIS AND MACHINE INTELLIGENCE, VOL. 20, NO. 8, AUGUST 1998, p. 819-831. +[3] A.G. Mamistvalov. n-Dimensional Moment Invariants and Conceptual Mathematical Theory of Recognition n-Dimensional Solids. *IEEE Transactions on Pattern Analysis and Machine Intelligence*, 20(8), 819-831 (1998). -[4] M. Groeber, M. Uchic, D. Dimiduk, and S. Ghosh. A Framework for Automated Analysis and Simulation of 3D Polycrystalline Microstructures, Part 1: Statistical Characterization Acta Materialia, 56 (2008), 1257-1273. +[4] M. Groeber, M. Uchic, D. Dimiduk, and S. Ghosh. A Framework for Automated Analysis and Simulation of 3D Polycrystalline Microstructures, Part 1: Statistical Characterization. *Acta Materialia*, 56, 1257-1273 (2008). ## Example Pipelines -+ (03) Small IN100 Morphological Statistics -+ (06) SmallIN100 Synthetic ++ `(03) Small IN100 Morphological Statistics` ++ `(06) SmallIN100 Synthetic` ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeShapesTriangleGeomFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeShapesTriangleGeomFilter.md index b87ee1bb6e..35344f98e7 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeShapesTriangleGeomFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeShapesTriangleGeomFilter.md @@ -4,23 +4,22 @@ Statistics (Morphological) -## Caveats +## Description -This filter has two caveats. +This **Filter** characterizes the 3D shape of each enclosed **Feature** in a **Triangle Geometry** surface mesh by fitting a best-fit ellipsoid. It produces the same types of shape descriptors as the [Compute Feature Shapes (Image Geometry)](ComputeShapesFilter.md) filter -- axis lengths, aspect ratios, axis orientations, and the Omega3 shape invariant -- but operates on triangle meshes rather than voxelized data. -Firstly, the axial lengths of this filter will be different than those produced by the voxelized version of this filter. This is for two reasons: +For a description of what each output represents (semi-axis lengths, aspect ratios, Omega3, etc.), see the [Compute Feature Shapes (Image Geometry)](ComputeShapesFilter.md) documentation. -- The sampling rate and density for the grid that was used to voxelize the mesh. See *Sample Triangle Geometry on Regular Grid* (RegularGridSampleSurfaceMesh). -- This filter determines axial lengths via distance from feature centroid to mesh intersection points along each of the principle axes. This means they are relative to the mesh itself rather than the grid it exists in. +### Differences from the Image Geometry Version -Secondly, shapes that exhibit rotational symmetry (e.g. cube, sphere, regular octahedron, etc.) may have different Euler Angles than those of the voxelized implementation, but they are functionally identical. This is more prevalent in meshes with less traingles, but this is seemly due to the fact the tested shapes are more uniform in low-poly. It is presumed that fiducial markers will stabilize ouputs for these specific shapes. +- **Axis lengths will differ** from the voxelized version because this filter measures distances from the feature centroid to mesh intersection points along the principal axes, rather than using voxel-based moment calculations. The voxelized result also depends on the sampling resolution used to create the grid. +- **Euler angles for symmetric shapes** (cube, sphere, octahedron, etc.) may differ numerically from the voxelized version but represent equivalent orientations. This is more apparent in low-polygon meshes. -## Description +### Mesh Quality Requirements -This **Filter** calculates the second-order moments of each enclosed **Feature** in a **Triangle Geometry**. The -second-order moments allow for the determination of the *principal axis lengths, principal axis directions, aspect -ratios and moment invariant Omega3s*. The *principal axis lengths* are those of a "best-fit" ellipsoid. The algorithm -for determining the moments and these values is as follows: +Accurate results require the mesh to be **watertight** (fully enclosed with no holes or gaps). The filter computes the Euler characteristic of each mesh region, which can indicate whether a mesh is watertight. See [Euler characteristic](https://en.wikipedia.org/wiki/Euler_characteristic) for more information. If a region is not watertight, the computed shape values may be inaccurate. + +### How This Filter Works 1. For each **Triangle** on the bounding surface of a **Feature**, construct a tetrahedron whose fourth vertex is the centroid of the **Feature**, ensuring normals are consistent (this **Filter** uses the convention where normals point @@ -41,14 +40,10 @@ for determining the moments and these values is as follows: represented, resulting in inaccurate Omega3 values. This problem is especially apparent for perfect rectangular prisms, but any shape with clear sharp corners may be affected. -This filter also computes the Euler Characteristic value which **can** be an indication of the __watertightness__ of the mesh(s). See -more information at [https://en.wikipedia.org/wiki/Euler_characteristic](https://en.wikipedia.org/wiki/Euler_characteristic) - -## WARNING +### Required Input Sources -Accurate computations depend on the mesh being water tight. If a triangle mesh has multiple regions -then these values will be computed for each region. If a region is not watertight then the computed -values are probably not correct. +- **Triangle Geometry** with **Face Labels** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md). +- **Feature Centroids** -- produced by [Compute Feature Centroids](../SimplnxCore/ComputeFeatureCentroidsFilter.md), typically on the voxelized feature data before meshing. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeSlipTransmissionMetricsFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeSlipTransmissionMetricsFilter.md index 4b2fa465ce..6ce3b6e6f2 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeSlipTransmissionMetricsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeSlipTransmissionMetricsFilter.md @@ -6,35 +6,51 @@ Statistics (Crystallography) ## Description -**THIS FILTER ONLY WORKS ON Cubic m-3m LAUE CLASSES** +This **Filter** calculates a suite of *slip transmission metrics* for each pair of neighboring **Features** (grains). These metrics quantify how easily plastic deformation (slip) can transfer across a grain boundary from one grain to another, based on the geometric alignment of their slip systems. -This **Filter** calculates a suite of *slip transmission metrics* that are related to the alignment of slip directions and planes across **Feature** boundaries. The algorithm for calculation of these metrics is as follows: +When a material deforms, slip occurs along specific crystallographic planes and directions within each grain. At grain boundaries, slip in one grain must either transmit into the neighboring grain, be blocked, or nucleate new slip. The degree of geometric compatibility between the slip systems on each side of a boundary is a key factor in determining whether transmission occurs or whether stress concentrations develop that can lead to crack initiation. -1. Get the average orientation of the **Feature** -2. Get the **Feature**'s list of neighboring **Features** -3. Get the average orientation of each neighboring **Feature** -4. Calculate metrics given by equations in *slip transmission metrics* -5. Store metrics in lists for the **Feature** -6. Repeat for all **Features** +### Cubic Materials Only -*Note:* The transmission metrics are calculated using the average orientations for neighboring **Features** and not the local orientation near the boundary. Also, the metrics are calculated twice (i.e., when **Feature** 1 has neighbor **Feature** 2 and when **Feature** 2 has neighbor **Feature** 1) because the direction across the boundary between the **Features** affects the value of the metric. +This filter only works on **cubic m-3m Laue classes**. -## Luster-Morris Parameter (M' Values) +### How This Filter Works -The values are calculated as presented in [1]. +1. For each **Feature**, the filter retrieves its average orientation and list of neighboring **Features** +2. For each neighbor pair, the filter evaluates all possible combinations of slip systems across the boundary +3. The transmission metrics are computed in both directions (Feature 1 → Feature 2 and Feature 2 → Feature 1) because the directionality affects the result +4. Results are stored as lists per **Feature**, one value per neighbor -## Fracture Initiation Parameter (fip) +### Note -Three (3) *fip* values are computed as outputs to this filter. These are best explained in [2], see page 021012-4 +The metrics are calculated using the **average orientations** of neighboring grains, not the local orientations near the boundary. + +### Luster-Morris Parameter (M') + +The Luster-Morris parameter (M') measures the geometric compatibility between two slip systems across a boundary. A value of 1.0 indicates perfect alignment; lower values indicate poorer compatibility. Calculated as presented in [1]. + +### Fracture Initiation Parameters (F1, F1spt, F7) + +Three fracture initiation parameter (fip) values are computed, which relate to the likelihood of crack nucleation at grain boundaries due to slip incompatibility. These are defined in [2] (see page 021012-4): ![Fracture Initiation Parameter F1](Images/ComputeNeighborSlipTransmission_F1.png) ![Fracture Initiation Parameter F1spt](Images/ComputeNeighborSlipTransmission_F1spt.png) -![Fracture Initiation Parameter F7.png](Images/ComputeNeighborSlipTransmission_F7.png) +![Fracture Initiation Parameter F7](Images/ComputeNeighborSlipTransmission_F7.png) + +### Comparison with Compute Feature Boundary Strength Metrics + +This filter stores results per **Feature** (in neighbor lists). The [Compute Feature Boundary Strength Metrics](ComputeBoundaryStrengthsFilter.md) filter computes the same metrics but stores results per **Face** on a **Triangle Geometry**, which is useful for visualization on the boundary mesh. + +### Required Input Sources +- **Neighbor List** -- produced by [Compute Feature Neighbors](../SimplnxCore/ComputeFeatureNeighborsFilter.md) or [Compute Feature Neighborhoods](../SimplnxCore/ComputeNeighborhoodsFilter.md). +- **Average Quaternions** -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). -## Citations +## References [1] [Luster, J., Morris, M.A., 1995. *Compatibility Of Deformation In Two-Phase Ti-Al Alloys: Dependence On Microstructure And Orientation Relationships*. **Metallurgical and Materials Transactions A 26, 1745**](https://link.springer.com/article/10.1007/BF02670762) diff --git a/src/Plugins/OrientationAnalysis/docs/ComputeTwinBoundariesFilter.md b/src/Plugins/OrientationAnalysis/docs/ComputeTwinBoundariesFilter.md index 5712cbb442..08ea5bcffc 100644 --- a/src/Plugins/OrientationAnalysis/docs/ComputeTwinBoundariesFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ComputeTwinBoundariesFilter.md @@ -6,14 +6,36 @@ Statistics (Crystallography) ## Description -This **Filter** identifies all **Triangles** between neighboring **Features** that have a σ = 3 twin relationship. The **Filter** uses the average orientation of the **Features** on either side of the **Triangle** to determine the *misorientation* between the **Features**. If the *axis-angle* that describes the *misorientation* is within both the axis and angle user-defined tolerance, then the **Triangle** is flagged as being a twin. After the **Triangle** is flagged as a twin, the crystal direction parallel to the **Face** normal is determined and compared with the *misorientation axis* if *Compute Coherence* is selected. The misalignment of these two crystal directions is stored as the incoherence value for the **Triangle** (in degrees). Note that this **Filter** will only extract twin boundaries if the twin **Feature** is the same phase as the parent **Feature**. +This **Filter** identifies twin boundaries on a **Triangle Geometry** surface mesh. A twin boundary is a special type of grain boundary where two grains share a specific crystallographic relationship -- their crystal lattices are mirror images of each other across the boundary plane. + +### What is a Twin Boundary? + +Twins are grains that share a highly symmetric orientation relationship. The most common type is the Σ3 twin, where the two grains are related by a 60-degree rotation about the <111> crystal direction. Twin boundaries are significant because they tend to have very low energy and distinct mechanical properties compared to general grain boundaries. They are particularly common in FCC metals such as copper, nickel, and austenitic stainless steel. + +### How This Filter Works + +1. For each **Triangle** on the grain boundary mesh, the filter computes the misorientation between the two **Features** on either side using their average orientations. +2. If the misorientation axis and angle match the Σ3 twin relationship within the user-defined tolerances, the **Triangle** is flagged as a twin boundary. +3. If **Compute Coherence** is enabled, the filter additionally measures the *incoherence* -- the angle (in degrees) between the boundary plane normal and the misorientation axis, both expressed in the crystal reference frame. A perfectly coherent twin has an incoherence of 0 degrees, meaning the boundary plane is exactly the twin plane. Higher incoherence values indicate a boundary that has the correct misorientation but is not on the ideal twin plane. + +### Note + +Only boundaries between **Features** of the same phase are evaluated. ### Output Type for Twin Boundaries Array -The *Output Type for Twin Boundaries Array* parameter controls the data type used to store the twin boundary identification result: +- **boolean [0]**: Stores the result as true/false +- **uint8 [1]**: Stores the result as 1/0 + +### Required Input Sources + +This filter operates on a grain-boundary surface mesh and requires the following upstream steps: -- **boolean [0]**: Stores the twin boundary flag as a boolean array (true if the **Triangle** is a twin boundary, false otherwise). -- **uint8 [1]**: Stores the twin boundary flag as an unsigned 8-bit integer array (1 if the **Triangle** is a twin boundary, 0 otherwise). +- **Face Labels** -- produced by a surface meshing filter such as [Quick Surface Mesh](../SimplnxCore/QuickSurfaceMeshFilter.md). +- **Face Normals** (only when *Find Coherence* is enabled) -- produced by [Compute Triangle Normals](../SimplnxCore/TriangleNormalFilter.md). +- **Average Quaternions** -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Crystal Structures** -- ensemble-level array read from EBSD data or created by [Create Ensemble Info](CreateEnsembleInfoFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/ConvertOrientationsFilter.md b/src/Plugins/OrientationAnalysis/docs/ConvertOrientationsFilter.md index 856cd5c596..11a375a510 100644 --- a/src/Plugins/OrientationAnalysis/docs/ConvertOrientationsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ConvertOrientationsFilter.md @@ -12,6 +12,8 @@ The following table lists the various orientation representations that are suppo is capable of converting between any representation with some caveats. The Input and Output Orientation Type are represented as a zero based index into the combo box widget. +![Fig. 1: The eight orientation representations Convert Orientation Representation maps between, with their zero-based indices and component counts. All describe the same 3D crystal rotation.](Images/ConvertOrientations_Representations.png) + ### Input Orientation Type The *Input Orientation Type* parameter provides the following choices: @@ -75,12 +77,12 @@ The valid range for Euler angles is (Degrees): + Phi : 0 to 180 + phi-2: 0 to 360 -Rodrigues Vector: Length must be positive and the vector must be normalized. -Homochoric Vector: Sum of Squares must = 1.0 -Quaternion: Scalar part must be positive and have unit norm -Axis Angle: Angle must be in the range of 0-Pi. -Stereographic Vector: Must be unit norm -Orientation Matrix: Determinant must be +1.0 +- Rodrigues Vector: Length must be positive and the vector must be normalized. +- Homochoric Vector: Sum of Squares must = 1.0 +- Quaternion: Scalar part must be positive and have unit norm +- Axis Angle: Angle must be in the range of 0-Pi. +- Stereographic Vector: Must be unit norm +- Orientation Matrix: Determinant must be +1.0 ### Data Conversion Notes diff --git a/src/Plugins/OrientationAnalysis/docs/EBSDSegmentFeaturesFilter.md b/src/Plugins/OrientationAnalysis/docs/EBSDSegmentFeaturesFilter.md index 73e65dbedb..efd83821af 100644 --- a/src/Plugins/OrientationAnalysis/docs/EBSDSegmentFeaturesFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/EBSDSegmentFeaturesFilter.md @@ -6,19 +6,49 @@ Reconstruction (Segmentation) ## Description -This **Filter** segments the **Features** by grouping neighboring **Cells** that satisfy the *misorientation tolerance*, i.e., have misorientation angle less than the value set by the user. The process by which the **Features** are identified is given below and is a standard *burn algorithm*. +This **Filter** groups neighboring **Cells** (voxels) that have similar crystal orientations into **Features** (grains), producing a *FeatureIds* array that labels every cell in the input **Image Geometry** with a grain number. This is the primary grain-segmentation filter for EBSD data and is usually the first feature-generating step in a reconstruction pipeline. -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 misorientation with each neighbor) -3. Add each neighbor **Cell** that has a misorientation 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 +For segmentation based only on C-axis alignment in hexagonal materials, see [Segment Features (C-Axis Misalignment)](CAxisSegmentFeaturesFilter.md). For segmentation based on a scalar value rather than orientation, see [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. +### What is Misorientation-Based Segmentation? -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. +A **grain** in a polycrystalline material is a region of crystal with a nearly-uniform lattice orientation. At grain boundaries the lattice rotates abruptly -- typically by many degrees -- from one grain to the next. Within a grain, orientation changes are small (sub-degree to a few degrees), due to noise, elastic strain, or mild plastic deformation. -If the data is specified as **Periodic**, the segmentation will check if features wrap around geometry bounds in a tileable fashion. If any such features are detected, the filter will throw a warning that centroid data may be incorrect. +*Misorientation* is the angular rotation that maps one crystal orientation onto another. By walking cell-to-cell and merging neighbors whose misorientation is below a threshold, this filter carves the cell-level orientation map into discrete grains. + +### How This Filter Works + +The filter uses a standard *burn algorithm* to grow each grain outward from a seed cell: + +1. Randomly pick an unassigned **Cell** and give it a new *Feature Id*. +2. Compute the misorientation angle between the seed cell and each neighbor (see **Neighbor Scheme** below). Crystal symmetry is applied so that the smallest symmetry-equivalent angle is used. +3. Any neighbor whose misorientation angle is less than the user-specified *Misorientation 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. + +### Example: Before and After + +The single EBSD slice below is shown first as an IPF (inverse pole figure) color map of the +raw cell orientations, then after misorientation-based segmentation, where each grain has been +assigned a distinct *Feature Id* and colored categorically. + +| IPF Color Map (input orientations) | Segmented Grains (Feature Ids) | +|:--:|:--:| +| ![EBSD IPF color map of the input slice](Images/EBSDSegmentFeatures_before_ipf.png) | ![Grains after misorientation segmentation](Images/EBSDSegmentFeatures_after_grains.png) | + +### Typical Tolerance Values + +The *Misorientation Tolerance* is in **degrees**. The right value depends on what you are trying to resolve: + +- **5 degrees** -- the industry-standard default for general grain segmentation. Works well across most materials. +- **2-3 degrees** -- tighter; useful when the data is very clean and you want to resolve subgrains or low-angle boundaries. +- **10-15 degrees** -- the classical "high-angle grain boundary" threshold. Useful if you want to ignore subgrain structure entirely and segment only the high-angle grains. + +Smaller tolerances produce more, smaller features and will pick up noise and subgrain boundaries as feature splits. Larger tolerances produce fewer, larger features at the cost of possibly merging neighboring grains that have a low-angle boundary between them. + +### Phase Handling + +Only cells belonging to the same phase are ever merged. Cells of different phases are always considered different features regardless of their orientation, because misorientation between different crystal systems is not physically meaningful. Cells with *phase = 0* (the "Unknown" phase) are treated as unsegmentable and receive Feature Id 0. ### Neighbor Scheme @@ -27,11 +57,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; switch to *All Connected* when diagonal connectivity should merge a grain that would otherwise be split into two features. | Neighbor Scheme = "Face Only" | Neighbor Scheme = "All Connected" | |:--:|:--:| @@ -49,6 +75,21 @@ 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. This is essential for EBSD data where low-confidence cells should not be merged into grains -- typically use a threshold on the confidence index or image quality to build the mask via [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). + +### Periodic Option + +If the input data represents a **periodic** volume (e.g., a synthetic microstructure that tiles across opposite faces), enable *Is Periodic*. The filter will detect features that wrap across the geometry bounds and emit a warning that centroid and other spatial statistics may be incorrect for those features. + +### 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). +- **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 diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.png new file mode 100644 index 0000000000..6e816e9f22 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.svg new file mode 100644 index 0000000000..cc5e0e9118 --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius1.svg @@ -0,0 +1,65 @@ + + + + + + + + + + + + 1D Example: Radius = 1 → Kernel Size = 3 + + + + + + ... + + + + + -1 + + + + Center + + + + +1 + + + + + ... + + + + + + R = 1 + + + + + R = 1 + + + + + + Kernel Size = 3 cells + + + + + + Center cell + + Kernel neighbor + + Outside kernel + + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.png new file mode 100644 index 0000000000..3c5406e949 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.svg new file mode 100644 index 0000000000..41a066aaaa --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_1D_Radius2.svg @@ -0,0 +1,71 @@ + + + + + + + + + + + + 1D Example: Radius = 2 → Kernel Size = 5 + + + + + + ... + + + + -2 + + + + -1 + + + + Center + + + + +1 + + + + +2 + + + + ... + + + + + + R = 2 + + + + + R = 2 + + + + + + Kernel Size = 5 cells + + + + + + Center cell + + Kernel neighbor + + Outside kernel + + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.png new file mode 100644 index 0000000000..73ea9abf3a Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.svg new file mode 100644 index 0000000000..02684fce6b --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius110.svg @@ -0,0 +1,92 @@ + + + + + + + + + + + + 2D View: Radius (1, 1, 0) + 3 × 3 kernel = 9 cells examined per voxel + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + X (R=1) + Y (R=1) + + + + + + Center (C) + + Kernel neighbor + + Outside kernel + + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.png new file mode 100644 index 0000000000..5295564025 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.svg new file mode 100644 index 0000000000..01399ff105 --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_2D_Radius120.svg @@ -0,0 +1,93 @@ + + + + + + + + + + + + 2D View: Radius (1, 2, 0) + 3 × 5 kernel = 15 cells examined per voxel + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + X (R=1) + Y (R=2) + + + + + + Center (C) + + Kernel neighbor + + Outside kernel + + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.png new file mode 100644 index 0000000000..2cde8310d8 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.svg new file mode 100644 index 0000000000..26205b18bf --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Formula.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + How Kernel Radius Relates to Kernel Size + + + + Kernel Size = (2 × Radius) + 1 + + + The radius extends in both directions along each axis, plus the center cell itself. + Each axis (X, Y, Z) can have a different radius value. + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.png new file mode 100644 index 0000000000..3b4134d670 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.svg new file mode 100644 index 0000000000..df239d576b --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeKernelAvgMisorientations_Table.svg @@ -0,0 +1,47 @@ + + + + + + Quick Reference: Radius → Kernel Size + + + + Radius (X,Y,Z) + + Kernel Size + + Cells per Dim + + Total Cells + + + + (1, 1, 1) + + 3 × 3 × 3 + + 3 + + 27 + + + + (2, 2, 2) + + 5 × 5 × 5 + + 5 + + 125 + + + + (3, 3, 3) + + 7 × 7 × 7 + + 7 + + 343 + \ No newline at end of file diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.png b/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.png new file mode 100644 index 0000000000..3cd47d2741 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.svg b/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.svg new file mode 100644 index 0000000000..7b0c0e1557 --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ComputeSchmids_SchmidFactor.svg @@ -0,0 +1,82 @@ + + + + + + + + Schmid Factor — Geometric Relationship + + + Schmid Factor = cos(φ) × cos(λ),  range: 0 to 0.5 + + + + + + + + + + + Slip plane + + + + + + + F (tensile) + + + + + + F (tensile) + + + + Slip plane + + + normal + + + + Slip + + + direction + + + + φ + + + + + + λ + + + + + + φ + = angle between tensile axis and slip plane normal + + + + λ + = angle between tensile axis and slip direction + + + + Slip plane (amber) + + + Maximum Schmid factor + 0.5 (at φ = λ = 45°) + + + diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.png b/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.png new file mode 100644 index 0000000000..ba94c128a1 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.svg b/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.svg new file mode 100644 index 0000000000..68dc0ba8df --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/ConvertOrientations_Representations.svg @@ -0,0 +1,81 @@ + + + Orientation representations + All eight forms describe the same 3D crystal rotation + + + + Convert Orientations: input [ i ] → output [ j ] + + + + + + 0 + Euler Angles + 3 components + (φ1, Φ, φ2) Bunge Z-X-Z + + + + + 1 + Orientation Matrix + 9 components + 3 × 3 rotation matrix + + + + + 2 + Quaternion + 4 components + (x, y, z), w + + + + + 3 + Axis-Angle + 4 components + axis (x, y, z), angle° + + + + + + + 4 + Rodrigues + 4 components + (x, y, z), w + + + + + 5 + Homochoric + 3 components + (x, y, z) + + + + + 6 + Cubochoric + 3 components + (x, y, z) + + + + + 7 + Stereographic + 3 components + (x, y, z) + + + + Euler Angles and Quaternions are the most commonly used; the filter converts between any pair (within numerical precision). + Choose the input and output representation from the list above. + diff --git a/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_after_grains.png b/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_after_grains.png new file mode 100644 index 0000000000..0504f95526 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_after_grains.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_before_ipf.png b/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_before_ipf.png new file mode 100644 index 0000000000..95346d4ba2 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/EBSDSegmentFeatures_before_ipf.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.png b/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.png new file mode 100644 index 0000000000..bc7963da26 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.svg b/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.svg new file mode 100644 index 0000000000..46c8c787f9 --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/EBSD_SampleVsCrystalReferenceFrame.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.png b/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.png new file mode 100644 index 0000000000..14a9ed1d76 Binary files /dev/null and b/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.png differ diff --git a/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.svg b/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.svg new file mode 100644 index 0000000000..fb57cf8404 --- /dev/null +++ b/src/Plugins/OrientationAnalysis/docs/Images/Misorientation_Concept.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/src/Plugins/OrientationAnalysis/docs/MergeTwinsFilter.md b/src/Plugins/OrientationAnalysis/docs/MergeTwinsFilter.md index 2ce1719337..dddb01c786 100644 --- a/src/Plugins/OrientationAnalysis/docs/MergeTwinsFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/MergeTwinsFilter.md @@ -6,9 +6,60 @@ Reconstruction (Grouping) ## Description -*THIS FILTER ONLY WORKS ON CUBIC-HIGH (m3m) Laue Classes.* +This **Filter** groups neighboring **Features** (grains) that share a *twin relationship* into a single *parent* grain. Twins are sub-grains of a parent grain that share a highly specific crystallographic relationship, and for many downstream analyses -- morphology, size distributions, neighbor statistics -- it is useful to treat a grain and its twin variants as one entity rather than as separate grains. -This **Filter** groups neighboring **Features** that are in a twin relationship with each other (currently only FCC σ = 3 twins). The algorithm for grouping the **Features** is analogous to the algorithm for segmenting the **Features** - only the average orientation of the **Features** are used instead of the orientations of the individual **Elements**. The user can specify a tolerance on both the *axis* and the *angle* that defines the twin relationship (i.e., a tolerance of 1 degree for both tolerances would allow the neighboring **Features** to be grouped if their misorientation was between 59-61 degrees about an axis within 1 degree of <111>, since the Sigma 3 twin relationship is 60 degrees about <111>). +Only the FCC *Σ3* twin relationship is detected by this filter. + +### What is a Twin? + +A **twin** is a region within a grain whose crystal lattice is a mirror image of the surrounding parent grain across a specific plane, called the *twin plane*. Mechanically, the twinned region is still part of the same grain structure; crystallographically, it has a different -- but highly specific -- orientation. + +The most common twin in FCC metals (copper, nickel, aluminum, austenitic stainless steels, superalloys such as IN100 and Inconel) is the **Σ3 twin**. Two grains are in a Σ3 twin relationship when they are related by a 60° rotation about the `<111>` crystal direction. This is often called an *annealing twin* because it frequently forms during recrystallization. + +The "Σ3" notation comes from *Coincidence Site Lattice* (CSL) theory: Σ is the reciprocal density of lattice sites shared between the two crystals, and Σ3 means 1 out of every 3 atomic sites line up exactly across the boundary. + +### Why Merge Twins? + +After segmentation (for example with the *Segment Features (Misorientation)* filter), each twin variant is identified as its own separate **Feature** because it has a distinct average orientation from its parent. This is correct from a pure orientation standpoint, but can mislead morphological and statistical analyses: + +- A grain with three twin bands will be counted as four separate grains, inflating the apparent grain count. +- Grain-size distributions will be skewed smaller because twin variants are smaller than the parent. +- Neighbor statistics will count twin-to-parent boundaries as regular grain boundaries. + +Merging twin variants back into a single parent grain produces a *post-twin* grain structure that more closely reflects what a metallurgist would call a "grain" under an optical microscope, and is usually the correct input for morphological statistics. + +### How This Filter Works + +The filter uses a burn-style grouping algorithm operating on the **Feature** level (not the **Cell** level): + +1. A **Feature** that has not yet been assigned a parent is selected as the starting point and given a new *Parent Id*. +2. For each of its contiguous neighbors (provided by the input *Contiguous Neighbor List*), the filter computes the misorientation between the two features using their average quaternions. +3. If the misorientation axis is within the *Axis Tolerance* of `<111>` **and** the misorientation angle is within the *Angle Tolerance* of 60°, the neighbor is in a Σ3 twin relationship with the current feature and is assigned the same *Parent Id*. +4. The grouping then extends recursively through the newly added neighbor's own neighbors, so that a chain of twins-of-twins is absorbed into one parent. +5. When no more features can be added to the current parent group, a new unassigned feature is picked and the process repeats until every eligible feature has a *Parent Id*. + +### Parameter Guidance + +- **Axis Tolerance (degrees)**: How far the misorientation rotation axis can deviate from the ideal `<111>` direction and still be accepted as a twin. Default is 3°. Typical values range from 1° to 5°. Tighter tolerance = fewer false positives but may miss slightly distorted real twins. +- **Angle Tolerance (degrees)**: How far the misorientation rotation angle can deviate from the ideal 60° and still be accepted as a twin. Default is 2°. Typical values range from 1° to 3°. + +Both tolerances are in **degrees**. A tolerance of 3°/2° accepts a neighbor as a twin if its misorientation falls within roughly 58°-62° about an axis within 3° of `<111>`. + +### Required Input Sources + +This filter requires that several prior operations have already been run: + +- **Cell Feature Ids** -- produced by a segmentation filter (e.g., [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md)). +- **Contiguous Neighbor List** -- produced by [Compute Feature Neighbors](../SimplnxCore/ComputeFeatureNeighborsFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](../SimplnxCore/ComputeFeaturePhasesFilter.md). +- **Average Quaternions** -- produced by [Compute Average Orientations](ComputeAvgOrientationsFilter.md). +- **Crystal Structures** -- the ensemble-level array describing each phase's Laue class. + +### Limitations + +- **Cubic-High (m3m) only.** The filter only evaluates twin relationships for phases with the m3m Laue class (FCC and BCC cubic materials). Phases with other symmetries are skipped with a warning; their features remain ungrouped. Only FCC materials actually exhibit Σ3 annealing twins in practice. +- **Σ3 only.** Other CSL boundaries (Σ5, Σ7, Σ9, etc.) are not detected. +- **Requires well-computed average orientations.** The twin detection is only as accurate as the input *Average Quaternions*. If twin variants were segmented together with the parent (too-loose segmentation tolerance), the average orientation will be wrong and this filter will not reliably detect twins. % Auto generated parameter table will be inserted here @@ -16,7 +67,6 @@ This **Filter** groups neighboring **Features** that are in a twin relationship + (02) Small IN100 Full Reconstruction - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/OrientationAnalysis/docs/NeighborOrientationCorrelationFilter.md b/src/Plugins/OrientationAnalysis/docs/NeighborOrientationCorrelationFilter.md index 2b126da737..a122874006 100644 --- a/src/Plugins/OrientationAnalysis/docs/NeighborOrientationCorrelationFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/NeighborOrientationCorrelationFilter.md @@ -22,7 +22,7 @@ Neighbors are defined as the "nearest neighbors" which share a "face". For 3D st | 1 | (13.0, 0.0, 0.0) CI=0.2 | (0.0, 0.0, 0.0) CI=0.05 | (12.0, 0.0, 0.0) CI=0.2 | | 2 | | (15.0, 0.0, 0.0) CI=0.2 | | -Schematic layout of the neighboring cells. Only the In-Plane neighbors are shown. +Cell (1,1) has CI = 0.05, which is below a 0.1 minimum, so it is flagged. Its 4 in-plane neighbors all have orientations within 5 degrees of each other (Euler angles around (12-15, 0, 0)) but more than 5 degrees from (1,1)'s orientation (0, 0, 0). At *Cleanup Level* = 4, the four neighbors agree, so (1,1)'s attributes are replaced with one of them. In this example, cell (1,1) has a confidence index < 0.1. Its four neighbors are compared pairwise with each other: (13.0), (14.0), (12.0) and (15.0) are all within a few degrees of each other, so every neighbor participates in several similar pairs. The central cell (1,1) has all of its attributes replaced with those of the neighbor holding the highest similar-pair count. Note that the central cell's own orientation and phase play no role in choosing the replacement — only the mutual similarity of its neighbors matters. @@ -31,13 +31,13 @@ In this example, cell (1,1) has a confidence index < 0.1. Its four neighbors are | Example Input/Output Images | |--------------------------------| | ![](Images/BadDataNeighborOrientationCheckFilter_2.png) | -| The Small IN100 data just after some intial cleanup filters have been used. | +| The Small IN100 data just after some initial cleanup filters have been used. | | ![](Images/NeighborOrientationCorrelationFilter_1.png) | -| The Small IN100 data just after running this filter with a *Misorientation Tolerance* of 5 degrees, and a *Cleanup Level* of 2 and a minimum *Confidence Index* of 0.2 | +| The Small IN100 data after running this filter with *Misorientation Tolerance* = 5°, *Cleanup Level* = 2, and *Minimum Confidence Index* = 0.2. | -These before and after images show how this filter can be used to "fill in" data that was deemed non-indexed (in EBSD terms). The user should be careful with this filter as it is meant to clean up small sets of voxels and not flood fill an entire volume of voxels. +These before-and-after images show how this filter can fill in non-indexed EBSD cells. Use it for small isolated bad regions, not for flood-filling entire low-confidence areas. -### Warning - Cell Level Data Modification +### Warning - Cell-Level Data Modification This filter will copy all attribute data from neighboring cells into the target cell if the criteria is met. Arrays listed in *Attribute Arrays to Ignore* are excluded from the copy. diff --git a/src/Plugins/OrientationAnalysis/docs/ReadAngDataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadAngDataFilter.md index 4639bd6ea0..f52b7f90ce 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadAngDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadAngDataFilter.md @@ -25,14 +25,17 @@ The **Image Geometry** dimensions come from the `NCOLS_EVEN`/`NROWS` header valu The created **Image Geometry** is always marked as **micrometers**, matching standard EDAX SEM-based `.ang` files. Legacy DREAM.3D 6.5 detected certain retired TEM/ACOM `.ang` variants and marked them as nanometers; EDAX retired those file formats over a decade ago and this filter does not special-case them. If you are importing such an archival file, set the geometry units manually after import. + +![Fig. 1: An EBSD orientation is the rotation (Euler angles) between the sample reference frame (specimen axes) and the crystal reference frame (lattice axes). Import conventions may require realigning the sample frame with Rotate Sample Reference Frame and/or the crystal frame with Rotate Euler Reference Frame.](Images/EBSD_SampleVsCrystalReferenceFrame.png) + ### Default TSL Transformations -If the data has come from a TSL acquisition system and the settings of the acquisition software were in the default modes, the following reference frame transformations may need to be performed based on the version of the OIM Analysis software being used to collect the data: +If the data has come from a TSL acquisition system and the settings of the acquisition software were in the default modes, the following reference frame transformations may need to be performed based on the version of the OIM Analysis software being used to collect the data. These rotations can be applied with [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) and [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md): + Sample Reference Frame: 180o about the <010> Axis + Crystal Reference Frame: 90o about the <001> Axis -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The Threshold Objects **Filter** can be used to define this *mask* by thresholding on values such as *Confidence Index* > 0.1 or *Image Quality* > desired quality. +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Confidence Index* > 0.1 or *Image Quality* > desired quality. **Confidence Index** and **Image Quality** are per-pixel metrics that describe how reliable each individual measurement is. ### Note About Sample Grid @@ -42,8 +45,15 @@ OIMAnalysis can create EBSD data sampled on a hexagonal grid. The user can look # GRID: HexGrid ``` -If the user's .ang files are hexagonal grid files then they will need to run the {ref}`Convert EDAX Hex Grid to Square Grid (.ang)` filter to first convert the input files to square gridded files. This filter rejects hexagonal grid files during preflight with error `-19500`. +If the user's .ang files are hexagonal grid files then they will need to run the [Convert EDAX Hex Grid to Square Grid (.ang)](ConvertHexGridToSquareGridFilter.md) filter first to convert the input files to square-gridded files. This filter rejects hexagonal grid files during preflight with error `-19500`. + +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. + +### Required Input Sources +None — this filter reads directly from a `.ang` file on disk. ### Note on .ang file Data Ordering diff --git a/src/Plugins/OrientationAnalysis/docs/ReadChannel5DataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadChannel5DataFilter.md index 46e2d2ea8b..338176d0dd 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadChannel5DataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadChannel5DataFilter.md @@ -6,31 +6,40 @@ IO (Input) ## Description -This filter will read a single .cpr/.crc file pair into a new ImageGeometry. A **Cell Attribute Matrix** and -Ensemble Attribute Matrix** will also be created to hold the imported EBSD information. Currently, the user has no -control over the names of the created **Attribute Arrays**. The user should be aware that simply reading the file -then performing operations that are dependent on the proper crystallographic and sample reference frame will be -**undefined, inaccurate and/or wrong**. In order to bring the crystal reference frame and sample reference frame -into coincidence, rotations will need to be applied to the data. An excellent reference for this is the following PDF file: +This filter reads a single `.cpr`/`.crc` file pair (the EBSD scan format written by Oxford Instruments / HKL Channel 5 software) into a new **Image Geometry**. Reading the files directly lets the data be used immediately by other filters, instead of having to first build an intermediate `.h5ebsd` file. A **Cell Attribute Matrix** (per-pixel data) and an **Ensemble Attribute Matrix** (per-phase data) are created to hold the imported EBSD information. The user currently has no control over the names of the created **Attribute Arrays**. + +The scan stores an **orientation** at every pixel as three **Euler angles** (three angles, in the Bunge Z-X-Z convention, describing how the measured crystal at that pixel is rotated relative to the sample). + +The user should be aware that simply reading the file and then performing operations that depend on a correct crystal reference frame (the axes fixed to the crystal lattice) and sample reference frame (the axes fixed to the physical specimen) will be **undefined, inaccurate and/or wrong**. To bring the crystal and sample reference frames into coincidence, rotations may need to be applied to the data. An excellent reference for this is the following PDF file: [http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf](http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf) + +![Fig. 1: An EBSD orientation is the rotation (Euler angles) between the sample reference frame (specimen axes) and the crystal reference frame (lattice axes). Import conventions may require realigning the sample frame with Rotate Sample Reference Frame and/or the crystal frame with Rotate Euler Reference Frame.](Images/EBSD_SampleVsCrystalReferenceFrame.png) + ### Default HKL Transformations If the data has come from a HKL acquisition system and the settings of the acquisition software were in the -default modes, then the following reference frame transformations need to be performed: +default modes, then the following reference frame transformations need to be performed. These rotations can be applied with [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) and [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md): + Sample Reference Frame: 180o about the <010> Axis + Crystal Reference Frame: None -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The Threshold Objects -**Filter** can be used to define this *mask* by thresholding on values such as *Error* = 0. This will mark all scan points +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Error* = 0. This will mark all scan points that have Error=0 as TRUE, which means those scan points are valid for processing. ### Radians and Degrees -2D .cpr/.crc files have their angles in **radians**. +2D `.cpr`/`.crc` files store their angles in **radians**. + +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. -### The Axis Alignment Issue for Hexagonal Symmetry [1] +### Required Input Sources + +None — this filter reads directly from a `.cpr`/`.crc` file pair on disk. + +### The Axis Alignment Issue for Hexagonal Symmetry (Advanced) [1] + The issue with hexagonal materials is the alignment of the Cartesian coordinate system used for calculations with the crystal coordinate system (the Bravais lattice). + In one convention (e.g. EDAX.TSL), the x-axis, i.e. [1,0,0], is aligned with the crystal a1 axis, i.e. the [2,-1,-1,0] direction. In this case, the y-axis is aligned with the [0,1,-1,0] direction. (Green Axis in Figure 1) @@ -39,21 +48,17 @@ that have Error=0 as TRUE, which means those scan points are valid for processin + Caution: it appears that the axis alignment is a choice that must be made when installing TSL software so determination of which convention is in use must be made on a case-by-case basis. It is fixed to the y-convention in the HKL software. + The main clue that something is wrong in a conversion is that either the 2110 & 1010 pole figures are transposed, or that a peak in the inverse pole figure that should be present at 2110 has shifted over to 1010. + DREAM3D-NX uses the TSL/EDAX convention. -+ **The result of this is that the filter will by default add 30 degrees to the second Euler Angle (phi2) when reading Oxford Instr (.ctf) files. This can be disabled by the user if necessary.** ++ **The result of this is that the filter will by default add 30 degrees to the second Euler Angle (phi2) when reading Oxford Instr Channel 5 (.cpr/.crc) files. This can be disabled by the user if necessary.** | Figure 1 | |-----------------------------------------------------------------------------------------------------------| | ![Figure showing 30 Degree conversions](Images/Hexagonal_Axis_Alignment.png) | -| Figure 1:**showing TSL and Oxford Instr. conventions. EDAX/TSL is in **Green**. Oxford Inst. is in**Red | +| **Figure 1:** showing TSL and Oxford Instr. conventions. EDAX/TSL is in **Green**. Oxford Inst. is in **Red**. | % Auto generated parameter table will be inserted here -## Example Pipelines - - - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/OrientationAnalysis/docs/ReadCtfDataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadCtfDataFilter.md index 12e3dbeb4a..27ab63ebe7 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadCtfDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadCtfDataFilter.md @@ -6,23 +6,37 @@ IO (Input) ## Description -This **Filter** will read a single .ctf file into a new **Image Geometry**, allowing the immediate use of **Filters** on the data instead of having to generate the intermediate .h5ebsd file. A **Cell Attribute Matrix** and Ensemble Attribute Matrix** will also be created to hold the imported EBSD information. Currently, the user has no control over the names of the created **Attribute Arrays**. The user should be aware that simply reading the file then performing operations that are dependent on the proper crystallographic and sample reference frame will be **undefined, inaccurate and/or wrong**. In order to bring the crystal reference frame and sample reference frame into coincidence, rotations will need to be applied to the data. An excellent reference for this is the following PDF file: +This filter reads a single `.ctf` file (the EBSD scan format written by Oxford Instruments / HKL Channel 5 software) into a new **Image Geometry**. Reading the file directly lets the data be used immediately by other filters, instead of having to first build an intermediate `.h5ebsd` file. A **Cell Attribute Matrix** (per-pixel data) and an **Ensemble Attribute Matrix** (per-phase data) are created to hold the imported EBSD information. The user currently has no control over the names of the created **Attribute Arrays**. + +The scan stores an **orientation** at every pixel as three **Euler angles** (three angles, in the Bunge Z-X-Z convention, describing how the measured crystal at that pixel is rotated relative to the sample). + +The user should be aware that simply reading the file and then performing operations that depend on a correct crystal reference frame (the axes fixed to the crystal lattice) and sample reference frame (the axes fixed to the physical specimen) will be **undefined, inaccurate and/or wrong**. To bring the crystal and sample reference frames into coincidence, rotations may need to be applied to the data. An excellent reference for this is the following PDF file: [http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf](http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf) +![Fig. 1: An EBSD orientation is the rotation (Euler angles) between the sample reference frame (specimen axes) and the crystal reference frame (lattice axes). Import conventions may require realigning the sample frame with Rotate Sample Reference Frame and/or the crystal frame with Rotate Euler Reference Frame.](Images/EBSD_SampleVsCrystalReferenceFrame.png) + ### Default HKL Transformations -If the data has come from a HKL acquisition system and the settings of the acquisition software were in the default modes, then the following reference frame transformations need to be performed: +If the data has come from a HKL acquisition system and the settings of the acquisition software were in the default modes, then the following reference frame transformations need to be performed. These rotations can be applied with [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) and [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md): + Sample Reference Frame: 180o about the <010> Axis + Crystal Reference Frame: None -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The Threshold Objects **Filter** can be used to define this *mask* by thresholding on values such as *Error* = 0. +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Error* = 0. ### Radians and Degrees -Most 2D .ctf files have their angles in **degrees** where as DREAM3D-NX expects radians. The filter provides an option to convert the Euler Angles to Radians and is turned on by default. The user is encouraged to create an IPF Image of their EBSD data to ensure that they do in-fact need to have this option enabled. +Most 2D `.ctf` files store their angles in **degrees**, whereas DREAM3D-NX expects radians. The filter provides an option to convert the Euler angles to radians, turned on by default. The user is encouraged to create an IPF (Inverse Pole Figure) image of their EBSD data to confirm whether this option actually needs to be enabled. + +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. + +### Required Input Sources + +None — this filter reads directly from a `.ctf` file on disk. -### The Axis Alignment Issue for Hexagonal Symmetry [1] +### The Axis Alignment Issue for Hexagonal Symmetry (Advanced) [1] + The issue with hexagonal materials is the alignment of the Cartesian coordinate system used for calculations with the crystal coordinate system (the Bravais lattice). + In one convention (e.g. EDAX.TSL), the x-axis, i.e. [1,0,0], is aligned with the crystal a1 axis, i.e. the [2,-1,-1,0] direction. In this case, the y-axis is aligned with the [0,1,-1,0] direction. (Green Axis in Figure 1) @@ -36,7 +50,7 @@ Most 2D .ctf files have their angles in **degrees** where as DREAM3D-NX expects | Figure 1 | |--------| | ![Figure showing 30 Degree conversions](Images/Hexagonal_Axis_Alignment.png) | -| Figure 1:**showing TSL and Oxford Instr. conventions. EDAX/TSL is in **Green**. Oxford Inst. is in**Red | +| **Figure 1:** showing TSL and Oxford Instr. conventions. EDAX/TSL is in **Green**. Oxford Inst. is in **Red**. | % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/ReadEnsembleInfoFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadEnsembleInfoFilter.md index e07d25fe00..381b53d596 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadEnsembleInfoFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadEnsembleInfoFilter.md @@ -6,7 +6,13 @@ IO (Input) ## Description -This **Filter** reads in information about the crystal structure and phase types of all the **Features** that are contained in a **Cell** based volume. These values are needed to allow the calculation of statistics on the volume, if they have not already been provided by some other means. The format of the input file is a simple ASCII text file with the extension .ini or .txt. The first group in the file is the name [EnsembleInfo] in square brackets with the key Number_Phases=*number of phases* that are contained in the volume. Subsequent groups in the file list the **Phase Number**, **Crystal Structure** and **Phase Type**. The proper values for the crystal structure and phase type come from internal constants within DREAM3D-NX and are listed here: +An **Ensemble** in DREAM3D-NX is a *phase*: a distinct material or crystal type present in the sample. This filter reads a small ASCII text file that describes each phase and creates the per-phase metadata that many statistics filters require. Specifically, for every phase it records a **Crystal Structure** (the crystal symmetry, which determines how orientations and misorientations are computed) and a **Phase Type** (the role the phase plays, such as a primary matrix phase or a precipitate phase). + +The filter does not create a new geometry. The *Data Container* parameter selects an existing geometry or data group, and the filter adds a new **Ensemble Attribute Matrix** (per-phase data) containing the **Crystal Structures** and **Phase Types** arrays into it. Downstream statistics and synthetic-structure filters read these arrays to know how to treat each phase. This information is needed to compute statistics on the volume when it has not already been provided by some other means (for example, by an EBSD reader). + +The input file is a simple ASCII text file with either a `.ini` or `.txt` extension; both use the same format. The first group is named `[EnsembleInfo]` in square brackets with the key `Number_Phases=`*number of phases* contained in the volume. Subsequent groups list the **Phase Number**, **Crystal Structure** and **Phase Type**. The valid string values for the crystal structure and phase type come from internal constants within DREAM3D-NX and are listed below. These tables describe the *content of the input file*, not the filter's parameters. + +A **Crystal Structure** value names the Laue (point-group) symmetry of the phase. A **Phase Type** value names the role the phase plays in subsequent analysis. **Crystal Structure** @@ -52,9 +58,11 @@ For example, if you have a structure that has 2 phases that consist of a Cubic P CrystalStructure=Hexagonal_High PhaseType=MatrixPhase -% Auto generated parameter table will be inserted here +### Required Input Sources + +None — this filter reads directly from a `.ini` or `.txt` file on disk. It does require an existing **Data Container** (a geometry or data group) into which the created **Ensemble Attribute Matrix** is placed. -## Example Pipelines +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ReadGrainMapper3DFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadGrainMapper3DFilter.md index 9731256294..9a13f73393 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadGrainMapper3DFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadGrainMapper3DFilter.md @@ -6,11 +6,11 @@ Readers ## Description -This filter will read Version 4 and Version 5 GrainMapper3D HDF5 files. +This filter reads Version 4 and Version 5 **GrainMapper3D** HDF5 (`.h5`) files. GrainMapper3D is [XNovo Technology](https://xnovotech.com)'s lab diffraction-contrast-tomography (LabDCT) reconstruction software, used to reconstruct 3D crystallographic grain maps from laboratory X-ray measurements. -- Euler data is read as radians -- The Image Geometry that is produced is in units of millimeters -- The user has the opportunity to create compatible Orientation Data and Phase data. See below. +- Euler data is read in **radians**. +- The **Image Geometry** that is produced is in units of **millimeters**. This differs from the micron length-unit assumption made by many downstream DREAM3D-NX filters (for example, size and spacing computations). Be aware of this difference when chaining this reader into a pipeline. +- The user has the opportunity to create DREAM3D-NX compatible Orientation Data and Phase data. See below. ## Parameter Discussion @@ -22,18 +22,22 @@ will be output. Specifically, the Rodrigues vector will be converted into a 4 component and the conjugate computed. The quaternion order will be changed from wxyz to xyzw and the conjugate will be computed. -PhaseId data will be converted to "int32" (as an option) to make that data immediately compatible -with DREAM3D's filters. +PhaseId data will be converted to *int32* (when the *Create Compatible Phase Data* option is checked) to make that data immediately compatible with DREAM3D-NX's filters. -IPFColors can be stored as either uint8 or float values. If you want to immediately view the IPF Colors then -the user should check the box for "Create Compatible IPF Color Data" +IPF (inverse pole figure) colors can be stored in the file as either *uint8* or *float32* values. To immediately view the IPF colors that came from the file, the user should check the box for *Create Compatible IPFColor Data*, which converts any *float32* color data to *uint8*. ## Special Notes -The IPF colors (if any) that are read in from the file are *NOT* compatible with the IPF -Color legends provided by DREAM3D-NX or EBSDLib. The user can use the "Compute IPF Colors" -if they need to specifically understand the crystallographic orientations or they -can obtain the IPF legends from XNovo. +The IPF colors (if any) that are read in from the file are **NOT** compatible with the IPF color legends provided by DREAM3D-NX or EBSDLib. There are two distinct options at play, and they should not be confused: + +- *Create Compatible IPFColor Data* only re-types the colors that were *already computed by GrainMapper3D* so they can be displayed; it does not recompute them against DREAM3D-NX's legends. +- To obtain IPF colors that match the DREAM3D-NX / EBSDLib legends, run [Compute IPF Colors](ComputeIPFColorsFilter.md) downstream on the imported orientation data. Alternatively, the user can obtain the matching IPF legends from XNovo. + +Use [Compute IPF Colors](ComputeIPFColorsFilter.md) if you need to specifically understand the crystallographic orientations using DREAM3D-NX's color conventions. + +## Required Input Sources + +None. This filter reads directly from a `.h5` GrainMapper3D file and creates the **Image Geometry**, **Cell** data, and **Ensemble** data itself. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/ReadH5EbsdFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadH5EbsdFilter.md index 6d32874b7c..46adc1a0c9 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadH5EbsdFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadH5EbsdFilter.md @@ -6,7 +6,11 @@ IO (Input) ## Description -This **Filter** reads from the .h5ebsd file that was generated with the *Import Orientation File(s) to H5EBSD* **Filter**. +This filter reads orientation data from a `.h5ebsd` file into a new **Image Geometry**. A `.h5ebsd` file is an HDF5 container that bundles one or more EBSD scan slices (along with their metadata) into a single file, which makes reading a multi-slice 3D volume fast and convenient. + +### Required Input Sources + +The `.h5ebsd` file read by this filter is not a manufacturer's native export. It must first be produced from one or more raw EBSD scan files (such as `.ang` or `.ctf`) using the [Import Orientation File(s) to H5EBSD](EbsdToH5EbsdFilter.md) filter. ![Read H5Ebsd File User Interface](Images/ReadH5Ebsd_UI.png) @@ -21,11 +25,11 @@ The **user** is solely responsible for knowing any sample reference frame transf If the user does not want the **Read H5Ebsd** filter to perform any transformations then the checkbox can be unchecked and the user can manually perform any desired transformations by inserting the appropriate filters into the pipeline. The suggested filters are: -+ {ref}`Rotate Euler Reference Frame ` -+ {ref}`Rotate Sample Reference Frame ` -+ {ref}`Convert Angles to Degrees or Radians ` ++ [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md) ++ [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) ++ [Convert Angles to Degrees or Radians](../SimplnxCore/ChangeAngleRepresentationFilter.md) -An excellant reference for this is the following PDF file: +An excellent reference for this is the following PDF file: [http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf](http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf) | Incorrect | Correct | @@ -34,19 +38,23 @@ An excellant reference for this is the following PDF file: | Euler angles were treated as Radians | Euler angles were converted from Degrees to Radians | |"Interstitial Free (IF) Steel courtesy of [1]"| | -### The Axis Alignment Issue for Hexagonal Symmetry [2] +### The Axis Alignment Issue for Hexagonal Symmetry (Advanced) [2] + The issue with hexagonal materials is the alignment of the Cartesian coordinate system used for calculations with the crystal coordinate system (the Bravais lattice). + In one convention (e.g. EDAX.TSL), the x-axis, i.e. [1,0,0], is aligned with the crystal a1 axis, i.e. the [2,-1,-1,0] direction. In this case, the y-axis is aligned with the [0,1,-1,0] direction. (Green Axis in Figure 1) + In the other convention, (e.g. Oxford Instr, Univ. Metz software), the x-axis, i.e. [1,0,0], is aligned with the crystal [1,0,-1,0] direction. In this case, the y-axis is aligned with the [-1,2,-1,0] direction. (Red Axis in Figure 1) -+ This is important because texture analysis can lead to an ambiguity as to the alignment of [2,-1,-1,0] versus [1,0,-1,0], with apparent **30** shifts in the data. ++ This is important because texture analysis can lead to an ambiguity as to the alignment of [2,-1,-1,0] versus [1,0,-1,0], with apparent **30 degree** shifts in the data. + Caution: it appears that the axis alignment is a choice that must be made when installing TSL software so determination of which convention is in use must be made on a case-by-case basis. It is fixed to the y-convention in the HKL software. + The main clue that something is wrong in a conversion is that either the 2110 & 1010 pole figures are transposed, or that a peak in the inverse pole figure that should be present at 2110 has shifted over to 1010. + DREAM3D-NX uses the TSL/EDAX convention. -+ **The result of this is that the filter will *AUTOMATICALLY* add 30 to phi2 when reading Oxford Instr (.ctf) files or .h5ebsd files denoted with the HKL manufacturer ID. There is no way to turn off this behavior.** ++ **The result of this is that the filter will *AUTOMATICALLY* add 30 degrees to phi2 when reading Oxford Instr (.ctf) files or .h5ebsd files denoted with the HKL manufacturer ID. There is no way to turn off this behavior.** ![Figure 1 showing TSL \& Oxford Instr. conventions.](Images/Hexagonal_Axis_Alignment.png) +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles (three angles, in the Bunge Z-X-Z convention, describing each crystal's orientation relative to the sample) are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/docs/ReadH5EspritDataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadH5EspritDataFilter.md index b98dd6b163..24c223b796 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadH5EspritDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadH5EspritDataFilter.md @@ -6,7 +6,9 @@ IO (Input) ## Description -This **Filter** will read a single .h5 file into a new **Image Geometry**, allowing the immediate use of **Filters** on the data instead of having to generate the intermediate .h5ebsd file. A **Cell Attribute Matrix** and Ensemble Attribute Matrix** will also be created to hold the imported EBSD information. Currently, the user has no control over the names of the created **Attribute Arrays**. +This filter reads a single `.h5` file (the HDF5-based EBSD export from Bruker Nano's Esprit software) into a new **Image Geometry**. Reading the file directly lets the data be used immediately by other filters, instead of having to first build an intermediate `.h5ebsd` file. A **Cell Attribute Matrix** (per-pixel data) and an **Ensemble Attribute Matrix** (per-phase data) are created to hold the imported EBSD information. The user currently has no control over the names of the created **Attribute Arrays**. + +The scan stores an **orientation** at every pixel as three **Euler angles** (three angles, in the Bunge Z-X-Z convention, describing how the measured crystal at that pixel is rotated relative to the sample). | User interface before entering a proper "Z Spacing" value and selecting which scans to include. | |-------| @@ -18,25 +20,31 @@ This **Filter** will read a single .h5 file into a new **Image Geometry**, allow ## Notes About Reference Frames -The user should be aware that simply reading the file then performing operations that are dependent on the proper crystallographic and sample reference frame will be undefined or simply **wrong**. In order to bring the crystal reference frame and sample reference frame into coincidence, rotations will need to be applied to the data. The recommended filters are: +The user should be aware that simply reading the file then performing operations that are dependent on the proper crystal reference frame (the axes fixed to the crystal lattice) and sample reference frame (the axes fixed to the physical specimen) will be undefined or simply **wrong**. To bring the crystal and sample reference frames into coincidence, rotations may need to be applied to the data. The recommended filters are: -+ {ref}`Rotate Euler Reference Frame ` -+ {ref}`Rotate Sample Reference Frame ` ++ [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md) ++ [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) If the data has come from a TSL acquisition system and the settings of the acquisition software were in the default modes, the following reference frame transformations may need to be performed based on the version of the OIM Analysis software being used to collect the data: + Sample Reference Frame: 180o about the <010> Axis + Crystal Reference Frame: 90o about the <001> Axis -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The {ref}`Threshold Objects ` Filter can be used to define this *mask* by thresholding on values such as *MAD* > xx. +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Mean Angular Deviation (MAD)* > xx. The **Mean Angular Deviation (MAD)** is a per-pixel metric describing how well the indexed solution fit the measured pattern (lower is better). -+ Note: If the X Step or Y Step within the HDF5 file for a scan is ZERO, those values will be set to 1.0 when the filter runs. This is needed ++ Note: If the X Step or Y Step within the HDF5 file for a scan is ZERO, those values will be set to 1.0 micron when the filter runs. This is needed as the user has no effective way to fix the HDF5 file. If the user needs a different -spacing value, the user can utilize the {ref}`Set Origin and Spacing` filter. +spacing value, the user can utilize the [Set Origin & Spacing (Image Geom)](../SimplnxCore/SetImageGeomOriginScalingFilter.md) filter. -% Auto generated parameter table will be inserted here +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. -## Example Pipelines +### Required Input Sources + +None — this filter reads directly from a `.h5` file on disk. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ReadH5OimDataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadH5OimDataFilter.md index 4c604e0921..055dc6ae90 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadH5OimDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadH5OimDataFilter.md @@ -6,7 +6,9 @@ IO (Input) ## Description -This **Filter** will read a single .h5 file into a new **Image Geometry**, allowing the immediate use of **Filters** on the data instead of having to generate the intermediate .h5ebsd file. A **Cell Attribute Matrix** and Ensemble Attribute Matrix** will also be created to hold the imported EBSD information. Currently, the user has no control over the names of the created **Attribute Arrays**. +This filter reads a single `.h5` file (the HDF5-based EBSD export from EDAX OIM Analysis software) into a new **Image Geometry**. Reading the file directly lets the data be used immediately by other filters, instead of having to first build an intermediate `.h5ebsd` file. A **Cell Attribute Matrix** (per-pixel data) and an **Ensemble Attribute Matrix** (per-phase data) are created to hold the imported EBSD information. The user currently has no control over the names of the created **Attribute Arrays**. + +The scan stores an **orientation** at every pixel as three **Euler angles** (three angles, in the Bunge Z-X-Z convention, describing how the measured crystal at that pixel is rotated relative to the sample). When stacking multiple slices into a 3D volume, the *Z Spacing* parameter sets the out-of-plane distance between adjacent slices in microns, and the *Origin* parameter sets the location of the volume's corner in microns. ![User interface before entering a proper "Z Spacing" value and selecting which scans to include.](Images/ReadEDAXH5_1.png) @@ -14,10 +16,10 @@ This **Filter** will read a single .h5 file into a new **Image Geometry**, allow ## Notes About Reference Frames -The user should be aware that simply reading the file then performing operations that are dependent on the proper crystallographic and sample reference frame will be undefined or simply **wrong**. In order to bring the crystal reference frame and sample reference frame into coincidence, rotations will need to be applied to the data. The recommended filters are: +The user should be aware that simply reading the file then performing operations that are dependent on the proper crystal reference frame (the axes fixed to the crystal lattice) and sample reference frame (the axes fixed to the physical specimen) will be undefined or simply **wrong**. To bring the crystal and sample reference frames into coincidence, rotations may need to be applied to the data. The recommended filters are: -- {ref}`Rotate Euler Reference Frame ` -- {ref}`Rotate Sample Reference Frame ` +- [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md) +- [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) If the data has come from a TSL acquisition system and the settings of the acquisition software were in the default modes, the following reference frame transformations may need to be performed based on the version of the OIM Analysis software being used to collect the data: @@ -26,16 +28,22 @@ If the data has come from a TSL acquisition system and the settings of the acqui ### Important Consideration for Sample Reference Frame -If the user is importing more than a single slice from the HDF5 file and using the "Rotate Sample Reference Frame" filter, +If the user is importing more than a single slice from the HDF5 file and using the [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) filter, the user should **CHECK** the option **ON** for "Perform Slice By Slice Transform". ## Thresholding out Unindexed Scan Points -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The {ref}`Threshold Objects ` **Filter** can be used to define this *mask* by thresholding on values such as *Confidence Index* > xx or *Image Quality* > desired quality. +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Confidence Index* > xx or *Image Quality* > desired quality. **Confidence Index** and **Image Quality** are per-pixel metrics that describe how reliable each individual measurement is. -% Auto generated parameter table will be inserted here +## Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, and so on) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. -## Example Pipelines +## Required Input Sources + +None — this filter reads directly from a `.h5` file on disk. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/OrientationAnalysis/docs/ReadH5OinaDataFilter.md b/src/Plugins/OrientationAnalysis/docs/ReadH5OinaDataFilter.md index 0aba362da8..191ca58f05 100644 --- a/src/Plugins/OrientationAnalysis/docs/ReadH5OinaDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/ReadH5OinaDataFilter.md @@ -6,32 +6,36 @@ IO (Input) ## Description -This filter will read data from a single .h5oina file into a new **Image Geometry**, allowing the immediate use of -**Filters** on the data instead of having to generate the intermediate .h5ebsd file. A **Cell Attribute Matrix** and -**Ensemble Attribute Matrix** will also be created to hold the imported EBSD information. Currently, the user has no control -over the names of the created **Attribute Arrays**. +This filter reads data from a single `.h5oina` file (the HDF5-based export from Oxford Instruments' AZtec software) into a new **Image Geometry**. Reading the file directly lets the data be used immediately by other filters, instead of having to first build an intermediate `.h5ebsd` file. A **Cell Attribute Matrix** (per-pixel data) and an **Ensemble Attribute Matrix** (per-phase data) are created to hold the imported EBSD information. The user currently has no control over the names of the created **Attribute Arrays**. + +### What This Filter Produces + +The file is EBSD (Electron Backscatter Diffraction) scan data. The most important imported arrays are: + +- **Orientation** — stored as three **Euler angles** per pixel (the three angles, in Bunge Z-X-Z convention, that describe how each measured crystal is rotated relative to the sample). Orientation is the basis for almost all downstream crystallographic analysis. +- **Phase** — a per-pixel index identifying which material (phase) was measured at that point. +- **Pattern-quality metrics** — values such as Band Contrast, Band Slope, Bands, and Mean Angular Deviation describe how clear and reliable each measurement is. These are commonly used to flag unreliable pixels (see *Reference Frames* below). +- **Per-phase (Ensemble) data** — the crystal structure, lattice constants, and material name for each phase. An **Ensemble** here means one distinct material/crystal type. ### Limitations of the Filter -The current implementation only understands the FORMAT VERSION 2.0 of the H5OINA file. This means that a user -can use a newer H5OINA file but the filter will only extract out the VERSION 2.0 headers and data. If the user -needs additional data from the file, the "Import HDF5 Dataset" filter can be used to agment this filter. +The current implementation only understands **FORMAT VERSION 2.0** of the H5OINA file. A user can still read a newer H5OINA file, but the filter will only extract the VERSION 2.0 headers and data. If additional data is needed from the file, the [Read HDF5 Dataset](../SimplnxCore/ReadHDF5DatasetFilter.md) filter can be used to augment this filter. ![Overview of the user interface.](Images/ImportH5OinaFilter_1.png) ## Notes About Reference Frames -In order to bring the crystal reference frame and sample reference frame into coincidence, rotations **MAY** need to be applied to the data. There are 2 filters that can perform the necessary rotations. +In order to bring the crystal reference frame and the sample reference frame into coincidence, rotations **MAY** need to be applied to the data. Two filters can perform the necessary rotations: -- {ref}`Rotate Euler Reference Frame ` -- {ref}`Rotate Sample Reference Frame ` +- [Rotate Euler Reference Frame](RotateEulerRefFrameFilter.md) +- [Rotate Sample Reference Frame](../SimplnxCore/RotateSampleRefFrameFilter.md) -Historical reference frame operations for a .ctf file are the following: +Historical reference frame operations for Oxford data are the following: + Sample Reference Frame: 180o about the <010> Axis + Crystal Reference Frame: None -The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The Threshold Objects **Filter** can be used to define this *mask* by thresholding on values such as *Error* = 0. +The user also may want to assign un-indexed pixels to be ignored by flagging them as "bad". The [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md) filter can be used to define this *mask* by thresholding on values such as *Error* = 0. ### Radians and Degrees @@ -46,44 +50,22 @@ All orientation data in the H5OINA file are in radians. + Caution: it appears that the axis alignment is a choice that must be made when installing TSL software so determination of which convention is in use must be made on a case-by-case basis. It is fixed to the y-convention in the HKL software. + The main clue that something is wrong in a conversion is that either the 2110 & 1010 pole figures are transposed, or that a peak in the inverse pole figure that should be present at 2110 has shifted over to 1010. + DREAM3D-NX uses the TSL/EDAX convention. -+ __The result of this is that the filter will by default add 30 degrees to the second Euler Angle (phi2) when reading Oxford Instr (.ctf) files. This can be disabled by the user if necessary.__ ++ __The result of this is that the filter will by default add 30 degrees to the second Euler Angle (phi2) when reading Oxford `.h5oina` files. This can be disabled by the user if necessary.__ | Figure 1 | |--------| | ![Figure showing 30 Degree conversions](Images/Hexagonal_Axis_Alignment.png) | | **Figure 1:** showing TSL and Oxford Instr. conventions. EDAX/TSL is in **Green**. Oxford Inst. is in **Red** | -## Parameters - -| Name | Type | Description | -|------|------| ----------- | -| Input File | File Path | The input .h5 file path | -| Scan Name | String | The name of the scan in the .h5oina file. | -| Z Spacing | float | The spacing in microns between each layer. | -| Origin | float (3x1) | The origin of the volume | -| Import Pattern Data | bool | Default=OFF | -| Hexagonal Axis Alignment | bool | Should the filter convert a Hexagonal phase to the EDAX standard for x-axis alignment | -| Convert Phase data to Int32 | bool | Should the phase data be converted to Int32 or keep the original uint8 | - -## Created Objects - -| Kind | Default Name | Type | Comp Dims | Description | -|-------------|--------------|------|-----------|----------------------------------------| -| Data Container | ImageDataContainer | N/A | N/A | Created Data Container name with an **Image Geometry** | -| Attribute Matrix | Cell Data | Cell | N/A | Created **Cell Attribute Matrix** name | -| Attribute Matrix | Cell Ensemble Data | Cell Ensemble | N/A | Created **Cell Ensemble Attribute Matrix** name | -| Cell Attribute Array | Band Contrast | uint8 | (1) | | -| Cell Attribute Array | Band Slope | uint8 | (1) | | -| Cell Attribute Array | Bands | uint8 | (1) | | -| Cell Attribute Array | Error | uint8 | (1) | The error descriptions are saved as attributes in the .h5oina file | -| Cell Attribute Array | Euler | float | (3) | Three angles defining the orientation of the **Cell** in Bunge convention (Z-X-Z) | -| Cell Attribute Array | MeanAngularDeviation | float | (1) | | -| Cell Attribute Array | Phase | uint8 | (1) | | -| Cell Attribute Array | X | float | (1) | The X Position of the scan point | -| Cell Attribute Array | Y | float | (1) | The Y Position of the scan point | -| Ensemble Attribute Array | CrystalStructures | uint32_t | (1) | Enumeration representing the crystal structure for each **Ensemble** | -| Ensemble Attribute Array | LatticeConstants | float | (6) | The 6 values that define the lattice constants for each **Ensemble**| -| Ensemble Attribute Array | MaterialName | String | (1) | Name of each **Ensemble** | +### Downstream Processing + +Once the reference frames are correct, the imported Euler angles are typically converted to other orientation representations (quaternions, etc.) with [Convert Orientation Representation](ConvertOrientationsFilter.md) before computing misorientations, segmenting grains, or generating pole figures. + +## Required Input Sources + +None — this filter reads directly from a `.h5oina` file on disk. + +% Auto generated parameter table will be inserted here ## Example Pipelines @@ -91,6 +73,6 @@ All orientation data in the H5OINA file are in radians. [1] Rollett, A.D. Lecture Slides located at [http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf](http://pajarito.materials.cmu.edu/rollett/27750/L17-EBSD-analysis-31Mar16.pdf) -## DREAM3DNX Help +## DREAM3D-NX Help -Check out our GitHub community page at [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) to report bugs, ask the community for help, discuss features, or get help from the developers. +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/OrientationAnalysis/docs/WriteGBCDGMTFileFilter.md b/src/Plugins/OrientationAnalysis/docs/WriteGBCDGMTFileFilter.md index add24285be..c4f33b475d 100644 --- a/src/Plugins/OrientationAnalysis/docs/WriteGBCDGMTFileFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/WriteGBCDGMTFileFilter.md @@ -6,9 +6,34 @@ IO (Output) ## Description -This **Filter** creates a .dat file that can be used in conjunction with [GMT](http://gmt.soest.hawaii.edu/) to generate a grain boundary character distribution (GBCD) pole figure. The user must select the relevant phase for which to write the pole figure by entering the *phase index*. +This filter exports a **grain boundary character distribution (GBCD)** as a plain-text `.dat` file that the external [Generic Mapping Tools (GMT)](https://www.generic-mapping-tools.org/) package can render into a pole figure image. The filter does not draw the pole figure itself — it writes the data file that GMT then turns into a picture. -![GMT Visualization of the Small IN100 GBCD Results](Images/WriteGBCDGMTFile.png) +### What is a GBCD Pole Figure? + +A **grain boundary** is the internal interface where two grains (individual crystals) meet inside a material. The **grain boundary character distribution (GBCD)** measures how often boundaries of a particular crystallographic character occur, compared to what a completely random arrangement would produce. + +For a chosen **misorientation** (the rotation that relates the crystal orientations of the two grains on either side of a boundary), the GBCD describes how the boundary-plane normals are distributed in space. That distribution is displayed on a **pole figure**: a 2D circular plot that maps 3D directions onto a disk. The plotted values are in **multiples of a random distribution (MRD)**, where *1.0* means "as common as a random arrangement" and values above *1.0* mark boundary planes that occur more often than random. + +### What This Filter Does + +This filter is one step in an external toolchain: + +[Compute GBCD](ComputeGBCDFilter.md) → **Write GBCD Pole Figure (GMT 5)** → GMT → rendered pole figure + +It samples the GBCD for the selected phase and misorientation and writes the result to a `.dat` text file. GMT (a separate, freely available command-line mapping toolkit) reads that file to produce the final image. + +### Parameter Guidance + +- **Phase of Interest** — the 1-based index of the **Ensemble** (phase) whose boundaries are plotted. A value of *1* selects the first real phase; index *0* is reserved for the unindexed/background ensemble. This value is a dimensionless index. +- **Misorientation Axis-Angle** — selects which boundary misorientation to plot. The first value is the misorientation **angle in degrees**; the remaining three are the crystallographic axis **(h, k, l)**, a dimensionless crystal direction. For example, *60° about (1, 1, 1)* selects the Σ3 twin misorientation common in cubic materials. +- **Output GMT File** — the path of the `.dat` file to write. GMT reads this file to draw the pole figure. + +![GMT visualization of the Small IN100 GBCD results. The contours show the distribution of grain-boundary plane normals (in MRD) for the selected misorientation.](Images/WriteGBCDGMTFile.png) + +### Required Input Sources + +- **GBCD** -- produced by [Compute GBCD](ComputeGBCDFilter.md). +- **Crystal Structures** -- typically read from EBSD data via [Read H5EBSD File](ReadH5EbsdFilter.md), [Read EDAX EBSD Data (.ang)](ReadAngDataFilter.md), or [Read Oxford Instr. EBSD Data (.ctf)](ReadCtfDataFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/OrientationAnalysis/docs/WriteGBCDTriangleDataFilter.md b/src/Plugins/OrientationAnalysis/docs/WriteGBCDTriangleDataFilter.md index e354bea86b..672ab37b22 100644 --- a/src/Plugins/OrientationAnalysis/docs/WriteGBCDTriangleDataFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/WriteGBCDTriangleDataFilter.md @@ -6,27 +6,43 @@ IO (Output) ## Description -This **Filter** writes relevant information about the Grain Boundary Character Distribution (GBCD) on an existing set of triangles. The information written includes the inward and outward Euler angles, normals, and areas for each triangle. The file format was originally defined by Prof. Greg Rohrer (CMU). +This filter writes a plain-text file describing the **grain boundary character distribution (GBCD)** for each triangle in a surface mesh. A **grain boundary** is the internal interface where two grains (individual crystals) meet inside a material; a surface mesh represents those interfaces as a collection of triangles in a **Triangle Geometry**. -## Example Output +For every boundary triangle the filter writes one line per triangle containing: - # Triangles Produced from DREAM3D version 5.2 - # Column 1-3: right hand average orientation (phi1, PHI, phi2 in RADIANS) - # Column 4-6: left hand average orientation (phi1, PHI, phi2 in RADIANS) - # Column 7-9: triangle normal - # Column 8: surface area +- The **average crystal orientation** of the grain on each side of the boundary, expressed as a set of Bunge **Euler angles** (phi1, PHI, phi2) in *radians*. +- The triangle **normal**, a unit direction (three unitless direction cosines) pointing perpendicular to the triangle face. +- The triangle **surface area**, in the squared units of the mesh vertex coordinates (square microns for typical EBSD data). + +### Inward / Outward (Left / Right) Average Orientations + +Each boundary triangle separates exactly two grains. The "right hand" (outward) and "left hand" (inward) average orientations are simply the average crystal orientations of those two grains, one on each side of the triangle. Listing both sides lets downstream tools reconstruct the **misorientation** (the rotation relating the two grains) across the boundary. + +### File Format + +The file begins with comment lines describing the ten data columns, followed by one row per triangle. Each row has ten space-separated values: + + # Column 1-3: right hand (outward) average orientation (phi1, PHI, phi2 in RADIANS) + # Column 4-6: left hand (inward) average orientation (phi1, PHI, phi2 in RADIANS) + # Column 7-9: triangle normal (unitless direction cosines) + # Column 10: triangle surface area 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 0.0000 0.8829 -0.4696 0.0240 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 0.4532 0.3203 -0.8319 0.0211 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 1.0000 0.0000 0.0000 0.0312 - 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 0.9939 0.0780 0.0780 0.0315 - 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 0.0000 0.9985 0.0551 0.0332 - 0.2662 0.6970 4.4347 0.7993 0.6738 3.5200 0.5074 0.7638 -0.3989 0.0260 0.7993 0.6738 3.5200 0.2662 0.6970 4.4347 0.0000 -0.7792 0.6268 0.0182 - 0.7993 0.6738 3.5200 0.2662 0.6970 4.4347 -0.5737 -0.0995 0.8130 0.0221 - 3.4109 0.6178 1.0586 0.2662 0.6970 4.4347 1.0000 0.0000 0.0000 0.0312 - 3.4109 0.6178 1.0586 0.2662 0.6970 4.4347 0.9822 0.1328 0.1328 0.0256 .. +The file format was originally defined by Prof. Gregory S. Rohrer (Carnegie Mellon University) for use with the Rohrer group's stereological grain-boundary analysis tools. See G. S. Rohrer, "Grain boundary energy anisotropy: a review," *Journal of Materials Science* 46 (2011) 5881-5895, and the associated GBCD/stereology software distributed by his group. + +### Required Input Sources + +- **Face Labels** -- produced by the surface-meshing step, [Create Surface Mesh (QuickMesh)](../SimplnxCore/QuickSurfaceMeshFilter.md). Identifies the two **Features** (grains) on either side of each triangle. +- **Face Normals** -- produced by [Compute Triangle Normals](../SimplnxCore/TriangleNormalFilter.md). +- **Face Areas** -- produced by [Compute Triangle Areas](../SimplnxCore/ComputeTriangleAreasFilter.md). +- **Average Euler Angles** -- per-**Feature** average orientations produced by [Compute Feature Average Orientations](ComputeAvgOrientationsFilter.md). + +Phase and orientation data for the grains ultimately come from an EBSD reader such as [Read H5EBSD File](ReadH5EbsdFilter.md), [Read EDAX EBSD Data (.ang)](ReadAngDataFilter.md), or [Read Oxford Instr. EBSD Data (.ctf)](ReadCtfDataFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/docs/WriteINLFileFilter.md b/src/Plugins/OrientationAnalysis/docs/WriteINLFileFilter.md index a53b3c674a..1b1f02138a 100644 --- a/src/Plugins/OrientationAnalysis/docs/WriteINLFileFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/WriteINLFileFilter.md @@ -8,17 +8,19 @@ IO (Output) This **Filter** writes out **Cell** data from an **Image Geometry** to a file format used by the Idaho National Laboratory (INL). The format is columnar and space delimited, with header lines denoted by the "#" character. The columns are the following: -- phi1 -- Phi -- phi2 -- x Position (Microns) -- y Position (Microns) -- z Position (Microns) -- Feature Id -- Phase Id -- Symmetry - -Some information about the phase is included in the header section of the file in addition to values for the origin, step size, dimensions and number of **Features** in the file. +- phi1 -- first Bunge Euler angle, in **radians** +- Phi -- second Bunge Euler angle, in **radians** +- phi2 -- third Bunge Euler angle, in **radians** +- x Position -- in **microns** +- y Position -- in **microns** +- z Position -- in **microns** +- Feature Id -- the grain (feature) each cell belongs to +- Phase Id -- the ensemble (phase) each cell belongs to +- Symmetry -- the crystal-symmetry code for the cell's phase + +The **Symmetry** column holds the integer crystal-symmetry code corresponding to the cell's crystal structure (for example, *43* denotes cubic m-3m and *62* denotes hexagonal 6/mmm). The codes follow the EBSDLib `CrystalStructure` enumeration and are taken from the **Crystal Structures** ensemble array. + +Some information about the phase is included in the header section of the file in addition to values for the origin, step size, and dimensions. The origin, **step sizes** (`X_STEP`, `Y_STEP`, `Z_STEP`), and min/max positions in the header are all in **microns**. The header also reports the number of **Features** in the file. ## Example Output @@ -64,6 +66,13 @@ Some information about the phase is included in the header section of the file i 0.266234 0.697020 4.434729 -34.750004 10.250000 -29.000000 639 1 43 0.266234 0.697020 4.434729 -34.500004 10.250000 -29.000000 639 1 43 +## Required Input Sources + +- **Cell Euler Angles** -- typically read from EBSD data via [Read H5EBSD File](ReadH5EbsdFilter.md), [Read EDAX EBSD Data (.ang)](ReadAngDataFilter.md), or [Read Oxford Instr. EBSD Data (.ctf)](ReadCtfDataFilter.md). Must be in radians (Bunge Z-X-Z convention). +- **Cell Phases** -- read alongside the Euler angles from the same EBSD reader. +- **Crystal Structures** -- the **Ensemble**-level array read alongside the phases from the same EBSD reader. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](../SimplnxCore/ScalarSegmentFeaturesFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/docs/WriteStatsGenOdfAngleFileFilter.md b/src/Plugins/OrientationAnalysis/docs/WriteStatsGenOdfAngleFileFilter.md index a247014250..9fe88d1efd 100644 --- a/src/Plugins/OrientationAnalysis/docs/WriteStatsGenOdfAngleFileFilter.md +++ b/src/Plugins/OrientationAnalysis/docs/WriteStatsGenOdfAngleFileFilter.md @@ -6,7 +6,7 @@ IO (Output) ## Description -This **Filter** is used in a workflow where the user would like to generate a synthetic microstructure with an ODF that matches (as closely as possible) an existing experimental data set or other data set that is being mimicked. The basic workflow is the following: +This **Filter** is used in a workflow where the user would like to generate a synthetic microstructure with an **Orientation Distribution Function (ODF)** that matches (as closely as possible) an existing experimental data set or other data set that is being mimicked. The ODF describes how crystallographic orientations are statistically distributed in the material. The basic workflow is the following: 1. Import Euler angle data (e.g., ANG or CTF files) 2. Optionally threshold the data so each cell is marked as allowable or not-allowable @@ -21,13 +21,13 @@ This **Filter** is used in a workflow where the user would like to generate a sy ## Important Change from Earlier Versions of StatsGenerator -StatsGenerator can not load data from standard .ang or .ctf files. If you want to get the ODF from an existing experimental data set and you have one of those files then you must use the functionality of this filter +StatsGenerator cannot load data from standard .ang or .ctf files. If you want to get the ODF from an existing experimental data set and you have one of those files then you must use the functionality of this filter. ## Notes on Implementation + A separate file is written for each phase + Spaces are the default as the delimiters between values. The user can select another value -+ Default values of 1.0 are used for both the *weight* and *sigma*. **If the user needs a stronger texture due to a low number of angles then larger values should be used such as 10, 100 or even 1000.** ++ Default values of 1.0 are used for both the *weight* and *sigma*. Both values are dimensionless. **If the user needs a stronger texture due to a low number of angles then larger values should be used such as 10, 100 or even 1000.** + The user has the option to convert the supplied Euler angles to degrees. **StatsGenerator** is able to import Euler angles as either degrees or radians based on user input, so the output type from this **Filter** could remain as radians or be converted to degrees. The user should remain cognizant of what representation their angles are in so that the correct option is chosen during the import process in **StatsGenerator** ## Example File @@ -62,6 +62,12 @@ The *Delimiter* parameter provides the following choices: - **: (colon) [3]**: Uses a colon as the column separator. - **\t (tab) [4]**: Uses a tab character as the column separator. +## Required Input Sources + +- **Euler Angles** -- typically read from EBSD data via [Read H5EBSD File](ReadH5EbsdFilter.md), [Read EDAX EBSD Data (.ang)](ReadAngDataFilter.md), or [Read Oxford Instr. EBSD Data (.ctf)](ReadCtfDataFilter.md). Supplied in radians (Bunge Z-X-Z convention); use the *Convert to Degrees* option only if **StatsGenerator** will import them as degrees. +- **Phases** -- read alongside the Euler angles from the same EBSD reader. A separate output file is written for each phase. +- **Mask** (optional) -- typically produced by [Multi-Threshold Objects](../SimplnxCore/MultiThresholdObjectsFilter.md). Only required when *Only Write Good Elements* is checked. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/Algorithms/WriteGBCDTriangleData.cpp b/src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/Algorithms/WriteGBCDTriangleData.cpp index 3640b156eb..4491620267 100644 --- a/src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/Algorithms/WriteGBCDTriangleData.cpp +++ b/src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/Algorithms/WriteGBCDTriangleData.cpp @@ -43,7 +43,7 @@ Result<> WriteGBCDTriangleData::operator()() fprintf(f, "# Column 1-3: right hand average orientation (phi1, PHI, phi2 in RADIANS)\n"); fprintf(f, "# Column 4-6: left hand average orientation (phi1, PHI, phi2 in RADIANS)\n"); fprintf(f, "# Column 7-9: triangle normal\n"); - fprintf(f, "# Column 8: surface area\n"); + fprintf(f, "# Column 10: surface area\n"); int32 gid0 = 0; // Feature identifier 0 int32 gid1 = 0; // Feature identifier 1 diff --git a/src/Plugins/SimplnxCore/docs/AddBadDataFilter.md b/src/Plugins/SimplnxCore/docs/AddBadDataFilter.md index fd8d6ea231..c8095347ce 100644 --- a/src/Plugins/SimplnxCore/docs/AddBadDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/AddBadDataFilter.md @@ -6,11 +6,43 @@ Synthetic Building (Misc) ## Description -This **Filter** adds "bad" data to an **Image Geometry**. This **Filter** is intended to add "realism" (i.e., more representative of an experimental dataset) to synthetic structures that don not have any "bad" **Cells**. The user can choose to add "random noise" and/or "noise" along **Feature** boundaries. For a given type of noise, the user must then set the volume fraction of **Cells** to set as "bad". The volume fractions entered apply to only the set of **Cells** that the noise would affect. For example, if the user chose *0.2* for the volume fraction of boundary "noise", then each boundary **Cell** would have a *20%* chance of being changed to a "bad" **Cell** and all other **Cells** would have a *0%* chance of being changed. In order to compute noise over the **Feature** boundaries, the **Filter** needs the Manhattan distances for each **Cell** from the **Feature** boundaries. Note that the computed Manhattan distances are floating point values, but this **Filter** requires an integer array. To create the necessary integer array, use the Convert Attributer Data Type **Filter** to cast the Manhattan distance array to an integer array. +This **Filter** adds synthetic *bad data* to a clean **Image Geometry**. It is intended to make synthetic microstructures look more like real experimental data, which always contains some unindexed cells, noise points, and boundary artifacts. The user controls how much noise to add and where (random throughout the volume, along feature boundaries, or both). -All **Attribute Arrays** that belong to the same **Attribute Matrix** as the selected *Feature Boundary Euclidean Distances* array will have noise added to them. To flag a value as "noise", this **Filter** will initialize a selected *tuple* in the **Attribute Array** to **0**. Note that a zero value *may not* necessarily represent a "bad" data point in any kind of **Attribute Array**. +### Why Use This Filter? -For more information on synthetic building, visit the tutorial. +Synthetic microstructures generated by reconstruction or packing pipelines have perfectly clean cell data -- every cell is assigned to a feature with a valid orientation. Real EBSD scans never look like that. When a synthetic structure is used to seed a downstream simulation that will eventually be compared against experimental measurements, that perfection becomes a problem: the cleanup filters in the experimental pipeline (e.g., [Fill Bad Data](FillBadDataFilter.md), [Neighbor Orientation Correlation](../OrientationAnalysis/NeighborOrientationCorrelationFilter.md)) have nothing to do, and the comparison stops being apples-to-apples. Adding synthetic bad data lets you exercise the same cleanup pipeline on synthetic data as on experimental data. + +### Random vs. Boundary Noise + +The filter supports two independent noise modes; either, both, or neither can be enabled. + +- **Random Noise** (Poisson) -- bad cells are scattered uniformly throughout the volume. Models random non-indexed points caused by detector dropout, surface contamination, or low signal. +- **Boundary Noise** -- bad cells are placed only on cells near a **Feature** boundary. Models the practical reality that EBSD signal is weakest right at grain boundaries, where the beam straddles two crystal orientations. + +### Volume Fraction Semantics + +For each enabled noise mode, the user specifies a *volume fraction* between 0 and 1. **The fraction applies only to the cells that the noise mode would affect, not the whole volume:** + +- *Random* volume fraction = 0.2 -> each cell anywhere in the volume has a 20% chance of being marked bad. +- *Boundary* volume fraction = 0.2 -> each *boundary* cell has a 20% chance of being marked bad. Non-boundary cells are unaffected (0% chance). + +This means a volume fraction of 0.2 in boundary-only mode introduces far fewer bad cells than 0.2 in random mode, because only boundary cells are at risk. + +### What "Bad" Means in Output + +To flag a cell as bad, the filter sets the corresponding tuple in every **Attribute Array** in the same **Attribute Matrix** as the *Boundary Euclidean Distances* input to **0**. This includes Feature Ids, Phases, Quaternions, and any other cell-level data sharing that matrix. Be aware that "0" may be a legitimate value for some arrays (e.g., a phase index) and that the convention here is shared with experimental cleanup filters that interpret Feature Id 0 as bad. + +### Prerequisite Steps + +This filter needs to know which cells are near a feature boundary. That information comes from a Manhattan-distance map, which must be computed and converted before this filter runs: + +1. Run [Compute Euclidean Distance Map](ComputeEuclideanDistMapFilter.md) on the segmented data to produce a *Boundary Euclidean Distances* array (cell-level, float32). +2. Run [Convert Data Type](ConvertDataFilter.md) on that array to cast it to an integer type. This filter's input requires an integer array. + +### Required Input Sources + +- **Boundary Euclidean Distances** (integer array) -- produced by [Compute Euclidean Distance Map](ComputeEuclideanDistMapFilter.md), then cast to integer with [Convert Data Type](ConvertDataFilter.md). +- **Image Geometry** containing cell-level data -- typically a synthetic structure from a packing or reconstruction pipeline. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/AlignSectionsFeatureCentroidFilter.md b/src/Plugins/SimplnxCore/docs/AlignSectionsFeatureCentroidFilter.md index aa02d810ce..3694e5302f 100644 --- a/src/Plugins/SimplnxCore/docs/AlignSectionsFeatureCentroidFilter.md +++ b/src/Plugins/SimplnxCore/docs/AlignSectionsFeatureCentroidFilter.md @@ -6,17 +6,27 @@ Reconstruction (Alignment) ## Description -This **Filter** attempts to align 'sections' of the sample perpendicular to the Z-direction by determining the position that closest aligns the centroid(s) of previously defined "regions". The "regions" are defined by a boolean array where the **Cells** have been flagged by another **Filter**. Typically, during reading/processing of the data, each **Cell** is subject to a "quality metric" (or threshold) that defines if the **Cell** is *good*. This threshold can be used to define areas of each slice that are bad, either due to actual features in the microstructure or external references inserted by the user/experimentalist. If these "regions" of *bad* **Cells** are believed to be consistent through sections, then this **Filter** will preserve that by aligning those "regions" on top of one another on consecutive sections. The algorithm of this **Filter** is as follows: +This **Filter** aligns serial sections (2D slices stacked along the Z-direction) by shifting each section so that the centroid of a user-defined region lines up from one section to the next. This is one of several section alignment methods available in DREAM3DNX. -1. Determine the centroid of all **Cells** that are flagged with a boolean value equal to *true* for each section -2. Determine the shifts that place centroids of consecutive sections on top of one another -3. Round the shifts determined in step 2 to the nearest multiple of the **Cell** resolution. (This forces the sections to be shifted by full **Cell** increments) +### When to Use This Method -If the user elects to *Use Reference Slice*, then each section's centroid is shifted to lie on top of the reference slice's centroid position and not its neighboring section's centroid position. +This method works well when a consistent region of interest (defined by a boolean mask) can be identified across all slices. For example, if a quality threshold has been applied so that "good" cells are flagged as *true*, the centroid of those *true* cells represents the center of the usable data on each slice. Aligning these centroids stacks the usable regions on top of each other. -**Note that this is algorithm cannot get caught in a local minimum!** +Unlike the misorientation-based and mutual-information-based alignment methods, the centroid method **cannot get caught in a local minimum**, making it more robust for certain datasets. -The user can also decide to remove a *background shift* present in the sample. The process for this is to fit a line to the X and Y shifts along the Z-direction of the sample. The individual shifts are then modified to make the slope of the fit line be 0. Effectively, this process is trying to keep the top and bottom section of the sample fixed. Some combinations of sample geometry and internal features can result in this algorithm introducing a 'shear' in the sample and the *Linear Background Subtraction* will attempt to correct for this. +### How This Filter Works + +1. For each section (Z-slice), compute the centroid of all **Cells** where the boolean mask is *true* +2. Compute the X and Y shifts needed to align each section's centroid with the previous section's centroid +3. Round the shifts to the nearest multiple of the **Cell** resolution (sections are shifted by whole-cell increments) + +### Reference Slice Option + +If *Use Reference Slice* is enabled, each section is shifted to align with a single fixed reference slice rather than its immediate neighbor. This prevents small errors from accumulating across many sections. + +### Linear Background Subtraction + +Some combinations of sample geometry and internal features can cause the alignment to introduce a gradual "shear" across the sample. Enabling *Linear Background Subtraction* corrects for this by fitting a line to the X and Y shifts along the Z-direction and removing the linear trend. This effectively keeps the top and bottom sections of the sample fixed relative to each other. ## Optional Output Data @@ -43,12 +53,15 @@ In this new structure, what follows is what the created structures represent: In previous versions a file would have been produced instead. If you wish to recreate this, you can write the Attribute Matrix as a CSV/Text file. +### Required Input Sources + +- **Mask** -- a boolean array marking valid cells, typically produced by a threshold operation such as [Multi-Threshold Objects](MultiThresholdObjectsFilter.md) applied to quality or confidence-index arrays. % Auto generated parameter table will be inserted here ## Example Pipelines -+ (02) Small IN100 Full Reconstruction ++ `(02) Small IN100 Full Reconstruction` ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/AlignSectionsListFilter.md b/src/Plugins/SimplnxCore/docs/AlignSectionsListFilter.md index f361fc9597..61abab9ac6 100644 --- a/src/Plugins/SimplnxCore/docs/AlignSectionsListFilter.md +++ b/src/Plugins/SimplnxCore/docs/AlignSectionsListFilter.md @@ -6,81 +6,57 @@ Reconstruction (Alignment) ## Description -This **Filter** will apply the precalculated cell shifts to each section of an Image Geometry. It allows for both *relative* or *cumulative* cell shifts. The difference between the two being the former is dependent on the previous slice's position. Under the covers, relative is translated to cumulative before applying shifts to the cells themselves. Previously, the only accepted input was utilizing relative shifts, so use those for backwards compatibility. See the **Handling User Created Shifts File** and **Example Pipelines** sections of this documentation for further hints. +This **Filter** applies precomputed cell shifts to each section of an **Image Geometry**. Unlike the other alignment filters (which calculate shifts automatically), this filter takes a set of known X and Y shifts as input and applies them directly. This is useful for: -### Input Array Type +- Applying shifts that were computed by another alignment filter in a previous run +- Applying user-measured or externally-calculated alignment corrections +- Re-applying a known good alignment to a dataset -The *Input Array Type* parameter controls how the shift values in the input arrays are interpreted: +### Shift Units -- **Relative [0]**: Each shift value is a relative offset between adjacent sections. The shift for section N describes how far section N has moved compared to section N-1. These values are internally converted to cumulative shifts before being applied. -- **Cumulative [1]**: Each shift value is an absolute (cumulative) offset measured from a fixed reference point. The shift for section N describes how far section N has moved from that reference. +All shift values are in **cell (voxel) units**, not physical units. A shift of 3 means move the section by 3 cells, regardless of the cell's physical size (spacing). The shifts must be integers. -## Handling User Created Shifts File +### Relative vs. Cumulative Shifts -In this section we will be covering how to get a user defined shift file into the algorithm. This has been included in the documentation for posterity, as the capability was removed in order to offer a less rigid file structuring and to centralize the I/O paradigm. +The input shifts can be provided in either format: -### File Information +- **Relative [0]**: Each shift describes the offset of section N relative to section N-1. The filter internally converts these to cumulative shifts before applying them. +- **Cumulative [1]**: Each shift describes the absolute offset of section N from a fixed reference point. -**Requirements:** - -- The number of shifts (`x` and `y` both) must be equivalent to the number of slices (Z dimension of the geometry) -- The slices must be ordered from the bottom of the sample to the top of the sample. +### Preparing Shift Data from a File -If using relative shifts for the algorithm, the first line of shifts should be the second slice relative to the first, then the next line is the third slice relative to the second, and so on +If your shifts are stored in an external file, you need to import them into a DataArray before using this filter: -**Recommendations:** +**Requirements:** +- The number of shift entries must equal the number of slices (Z dimension of the geometry) +- Slices must be ordered from bottom to top -The **user** created alignment file is recommended have the format as follows: +**Recommended file format** (space-delimited, two values per line): ```console xshift yshift xshift yshift xshift yshift -etc... -``` - -**Backwards Compatibility Information:** - -For versions of 7.0.3 and below, the DREAM3D and DREAM3DNX produced had the following format: - -```console -slice_m slice_m+1 newxshift newyshift xshifts yshifts -slice_n slice_n+1 newxshift newyshift xshifts yshifts -etc... +... ``` -Where: - -- `newxshift` and `newyshift` were the relative shifts -- `xshifts` and `yshifts` were the cumulative shifts. -- `xcentroid` and `ycentroid` were appended to the end for `AlignSectionsFeatureCentroid` - -**Note: Previous implementations of `AlignSectionsFeatureCentroid` were printing zeros for the relative shifts, so if you are using a file produced by that you must use cumulative shifts.** - -### Importing - -Use "Read CSV File" (`ReadCSVFileFilter`) or "Read Text Data Array" (`ReadTextDataArrayFilter`) to get your data into an array. - -**Recommendations:** - -If you have a file matching the recommended **user** created alignement file above, the process can be expidited with "Read Text Data Array" (`ReadTextDataArrayFilter`). +**To import this format:** -To do so: +1. Use the [Read Text Data Array](ReadTextDataArrayFilter.md) filter +2. Set *Input Numeric Type* to `signed int 64 bit` +3. Set *Number of Components* to `2` +4. Set *Delimiter* to space +5. Set the *Data Array Dimensions* to match the Z dimension of your geometry -1. supply your file in the "Input Text File" parameter -2. set "Input Numeric Type" parameter to `signed int 64 bit` -3. set "Number of Components" parameter to `2` -4. change the "Delimiter" parameter to ` (space)` (index number `2` for python) -5. in the "Created Array Path" parameter, leave the path empty, and name it according to the type of shifts ("relative_shifts" or "cumulative_shifts") -6. get the tuple dims of the Z dimension of your geometry, and put it into the "Data Array Dimensions (Slowest to Fastest)" parameter +For more complex file formats (e.g., legacy DREAM3D alignment files with 6 columns), use the [Read CSV File](ReadCSVFileFilter.md) filter instead. See the backwards compatibility example pipeline for details. -**Backwards Compatibility Information:** +### Note on Legacy Files -For alignment shifts files from the previous version, you **must** use the "Read CSV File" (`ReadCSVFileFilter`). This is a complicated filter parameter wise, so see the documentation provided with the filter. It is recommended to store these in an Attribute Matrix with dimensions equivalent to that of the Z dimension of the target geometry. +Alignment shift files from DREAM3D/DREAM3DNX versions 7.0.3 and earlier used a 6-column format with both relative and cumulative shifts. If using these files, import via the [Read CSV File](ReadCSVFileFilter.md) filter and select the appropriate columns. Files produced by the legacy `AlignSectionsFeatureCentroid` contained zeros for relative shifts -- use cumulative shifts for those. -### Conclusion +### Required Input Sources -The imported data should be prepared and compatible with the Align Sections List input by now. If you have further questions see one of the example pipelines below. +- **Cell Shifts Array** -- a two-component int64 array with one entry per Z-slice. Import this from an external file using [Read Text Data Array](ReadTextDataArrayFilter.md) (simple format) or [Read CSV File](ReadCSVFileFilter.md) (complex/legacy format); or pass the *Relative Shifts* / *Cumulative Shifts* array produced by another alignment filter such as [Align Sections (Feature Centroid)](AlignSectionsFeatureCentroidFilter.md), [Align Sections (Misorientation)](../OrientationAnalysis/AlignSectionsMisorientationFilter.md), or [Align Sections (Mutual Information)](../OrientationAnalysis/AlignSectionsMutualInformationFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/AppendImageGeometryFilter.md b/src/Plugins/SimplnxCore/docs/AppendImageGeometryFilter.md index 461278fb64..a5193b6835 100644 --- a/src/Plugins/SimplnxCore/docs/AppendImageGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/AppendImageGeometryFilter.md @@ -6,8 +6,9 @@ Sampling (Memory/Management) ## Description -This filter allows the user to append one or multiple image geometries to a given image geometry, in any direction (X,Y,Z). The input and -destination **ImageGeometry** objects must have the same dimensions in the directions that are NOT chosen. If the X direction is chosen, the geometries must match in Y & Z. If the Y direction is chosen, the geometries must match in X & Z. If the Z direction is chosen, the geometries must match in X & Y. Optional checks for equal **Resolution** values can also be performed. +This **Filter** appends one or more **Image Geometries** to a destination Image Geometry along a chosen axis (X, Y, or Z), producing a single larger Image Geometry. The input geometries must have matching dimensions in the two axes that are *not* the append direction. Optionally, the filter can also verify that the input and destination geometries have matching spacing on all axes before appending. + +For an introduction to Image Geometry dimensions and spacing, see [Create Image Geometry](CreateImageGeometryFilter.md). This filter also has an option to mirror the resulting geometry in the chosen direction. If the X direction is chosen, it will mirror the positions of the YZ planes. If the Y direction is chosen, it will mirror the positions of the XZ planes. If the Z direction is chosen, it will mirror the positions of the XY planes. @@ -94,6 +95,10 @@ And here is what the geometry looks like after appending the three pieces togeth | ![](Images/AppendImageGeometry/z_complete.png) | ![](Images/AppendImageGeometry/z_mirrored.png) | |:----------------------:|:----------------------:| +### Required Input Sources + +- **Destination Image Geometry** and **Input Image Geometries** -- all geometries to be appended. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. All must share matching cell-level Attribute Array names if cell data is to be preserved during the append. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ApplyTransformationToGeometryFilter.md b/src/Plugins/SimplnxCore/docs/ApplyTransformationToGeometryFilter.md index 17595465f7..ad1814b64f 100644 --- a/src/Plugins/SimplnxCore/docs/ApplyTransformationToGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/ApplyTransformationToGeometryFilter.md @@ -6,137 +6,97 @@ Rotation, Scale & Transformation ## Description -This **Filter** applies a spatial transformation to either a node **Geometry** or an **Image Geometry**. +This **Filter** applies a spatial transformation -- rotation, translation, scaling, or an arbitrary 4x4 matrix -- to a **Geometry**. Both **Image Geometries** and node-based geometries (Vertex, Edge, Triangle, Quadrilateral, Tetrahedral, Hexahedral) are supported. -### Node Geometries +![Fig. 1: The "Rotation" transform type rotates the geometry by an angle θ (in degrees) about a user-specified axis (x, y, z). Unlike Rotate Sample Reference Frame, this is a true geometric transform that moves the geometry itself.](Images/ApplyTransformationToGeometry_AxisAngle.png) - A node **Geometry** is any geometry that requires explicit definition of **Vertex** positions. Specifically, **Vertex**, **Edge**, **Triangle**, **Quadrilateral**, and **Tetrahedral** **Geometries** may be transformed by this **Filter**. The transformation is applied in place, so the input **Geometry** will be modified. +### Node Geometries -- **NO** interpolation will take place as the only changes that take place are the actual coordinates of the vertices. +For node-based geometries, the transformation modifies vertex positions only. No interpolation occurs. Multiple transformations can be applied in succession without artifacts. ### Image Geometry -If the user selects an **Image Geometry** then there are 2 additional required filter parameters that need to be set: - -- **Interpolation Method**: This will be used when transferring the data from the old geometry to the newly transformed geometry. -- **Cell Attribute Matrix**: This Attribute Matrix holds the data that is associated with each cell of the image geometry. - -The linear/Bi-Linear/Tri-Linear Interpolation is adapted from the equations presented -in [https://www.cs.purdue.edu/homes/cs530/slides/04.DataStructure.pdf, page 36}](https://www.cs.purdue.edu/homes/cs530/slides/04.DataStructure.pdf) +For Image Geometries, transformation requires re-gridding because cell positions are implicit in the grid spacing and origin. After transformation, a new grid is generated and cell data is interpolated onto it. This is governed by two extra parameters: -## Example Image Geometry Transformations - -| Description | Example Output Image | -|-------------|----------------------| -| Input Image | ![Input Image](Images/ApplyTransformation_AsRead.png) | -| After Rotation of 45 Degrees around the <001> axis | ![Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_Rotated.png) | -| Scaled by 2x in the X and Y axis | ![Scaled by 2x in the X and Y axis.](Images/ApplyTransformation_Scaled.png) | +- **Interpolation Method** -- how cell data values are sampled from the old grid (see below). +- **Cell Attribute Matrix** -- which attribute matrix holds the cell data to transform. -## Image Geometry Caveat +### Image Geometry Caveat: Successive Transformations -Using this filter several times in a row to apply several transforms in succession to the same image geometry is highly likely to result in visual artifacts related to the intermediate re-gridding of the image geometry between transformations. For example, let's rotate an image geometry 90 degrees along the Z axis: +Applying multiple transformations one-at-a-time to an Image Geometry produces visible re-gridding artifacts because each intermediate step re-samples the data. The following example shows a 90-degree rotation done as a single step versus as two 45-degree steps: | Description | Image | |-------------|----------------------| | Input Image | ![Input Image](Images/ApplyTransformation_ImageGeom.png) | -| After Rotation of 90 Degrees around the <001> axis | ![Rotation of 90 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final.png) | +| After single 90-degree rotation around <001> | ![Rotation of 90 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final.png) | +| After first 45-degree rotation | ![1st Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Intermediate.png) | +| After second 45-degree rotation (artifacts visible) | ![2nd Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final_Artifacts.png) | -Instead of using a single rotation of 90 degrees, if the user has a need to instead apply several rotations that still add up to 90 degrees, for example a pair of 45 degree rotations, potential unwanted artifacts can occur due to the intermediate regridding for each rotation. - -| Description | Image | -|-------------|----------------------| -| Input Image | ![Input Image](Images/ApplyTransformation_ImageGeom.png) | -| After 1st Rotation of 45 Degrees around the <001> axis | ![1st Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Intermediate.png) | -| After 2nd Rotation of 45 Degrees around the <001> axis | ![2nd Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final_Artifacts.png) | - -Why does this happen? Let's overlay the centers of each cell on top of the original image geometry. +The problem is that after the first 45-degree rotation, the cell centers no longer align with the new grid cells -- the re-gridding has shifted them. On the second rotation, those misalignments compound. | Description | Image | |-------------|----------------------| | Input Image | ![Input Image](Images/ApplyTransformation_ImageGeom_WithVertices.png) | -| After 1st Rotation of 45 Degrees around the <001> axis | ![1st Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Intermediate_WithVertices.png) | - -The green vertices refer to the center of each image geometry cell. As you can see, after the first 45 degree rotation, the image geometry is re-gridded and now the transformed green vertices are no longer in the center of each cell. - -On the 2nd and final 45 degree rotation, the image geometry is going to double in size because the algorithm doesn't know the final image geometry's exact size and doubles its size to account for the worst case scenario. +| After 1st 45-degree rotation (cell centers in green) | ![1st Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Intermediate_WithVertices.png) | -Let's see how the transformed green vertices overlay on the intermediate image geometry when the field of vertices has doubled in size but the image geometry hasn't actually been transformed a 2nd time yet. +To avoid these artifacts, **combine all transformations into a single 4x4 matrix first** using [Combine Transformation Matrices](CombineTransformationMatricesFilter.md), then apply that combined matrix as a single transformation: | Description | Image | |-------------|----------------------| -| After 1st Rotation of 45 Degrees around the <001> axis | ![1st Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Intermediate_WithVertices2.png) | +| Combined 90-degree rotation applied once | ![Combined Rotation of 90 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final.png) | -The cell circled in purple has two green vertices inside it. This means that once the 2nd 45 degree transformation is completed, the final image geometry will have that orange color shifted outside where we would expect it to be. And sure enough: +This caveat only applies to Image Geometries. Node-based geometries can have any number of transformations chained without issue. -| Description | Image | -|-------------|----------------------| -| After 2nd Rotation of 45 Degrees around the <001> axis | ![2nd Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final_Artifacts2.png) | +### Example Transformations (Image Geometry) -To avoid this problem, it is considered best practice to use the *[Combine Transformation Matrices](CombineTransformationMatricesFilter.md)* filter to combine all transforms together into one transform before applying the transform to an image geometry. - -| Description | Image | +| Description | Example Output Image | |-------------|----------------------| -| After combining both 45 degree rotations and applying around the <001> axis | ![Rotation of 90 Degrees around the <0,0,1> axis](Images/ApplyTransformation_ImageGeom_Final.png) | - -## NOTE: - -This caveat is ONLY for image geometries. Multiple transformations can be applied in succession to any of the "Node" based geometries without any issues. Those are: - -- Vertex -- Edge -- Triangle -- Quad -- Tetrahedral -- Hexahedral - -## Transformation Information +| Input Image | ![Input Image](Images/ApplyTransformation_AsRead.png) | +| 45-degree rotation around <001> | ![Rotation of 45 Degrees around the <0,0,1> axis](Images/ApplyTransformation_Rotated.png) | +| 2x scale in X and Y | ![Scaled by 2x in the X and Y axis.](Images/ApplyTransformation_Scaled.png) | ### Transformation Type -The *Transformation Type* parameter provides the following choices: - -- **No Transform [0]**: Applies an identity transformation; the geometry is unchanged. -- **Pre-Computed Transformation Matrix (4x4) [1]**: Uses a 4x4 transformation matrix supplied as an Attribute Array in row major order. -- **Manual Transformation Matrix [2]**: Uses a manually entered 4x4 transformation matrix. -- **Rotation [3]**: Rotates about a supplied axis-angle with the angle specified in degrees. -- **Translation [4]**: Translates the geometry by the supplied (x, y, z) values. -- **Scale [5]**: Scales the geometry by the supplied (x, y, z) values. +The *Transformation Type* parameter selects how the transformation is specified: -The user may select from a variety of options for the type of transformation to apply: +| Value | Type | Description | +|---|---|---| +| 0 | No Transform | Identity (geometry unchanged). | +| 1 | Pre-Computed Transformation Matrix (4x4) | A 4x4 matrix supplied as a 16-element float32 Attribute Array in row-major order. | +| 2 | Manual Transformation Matrix | A 4x4 matrix typed in directly. | +| 3 | Rotation | Axis-angle: a unit vector (x, y, z) and an angle in **degrees**. | +| 4 | Translation | A (dx, dy, dz) translation vector in the geometry's physical units. | +| 5 | Scale | A (sx, sy, sz) scaling vector (dimensionless multipliers). | -| Enum Value | Transformation Type | Representation | -|------------|------------------------------------|--------------------------------------------------------------------------------------| -| 0 | No Transformation | Identity transformation | -| 1 | Pre-Computed Transformation Matrix | A 4x4 transformation matrix, supplied by an **Attribute Array** in *row major* order | -| 2 | Manual Transformation Matrix | Manually entered 4x4 transformation matrix | -| 3 | Rotation | Rotation about the supplied axis-angle (Angle in Degrees). | -| 4 | Translation | Translation by the supplied (x, y, z) values | -| 5 | Scale | Scaling by the supplied (x, y, z) values | +The linear / bi-linear / tri-linear interpolation math is adapted from [Purdue CS530 slides, page 36](https://www.cs.purdue.edu/homes/cs530/slides/04.DataStructure.pdf). -The **Translate Geometry To Global Origin Before Transformation** option must be selected if the user wants to translate their volume to (0, 0, 0), apply the transform, and then translate the volume back to its original location. +If *Translate Geometry To Global Origin Before Transformation* is enabled, the geometry is shifted so its centroid sits at (0, 0, 0) before the transformation is applied, then translated back. Use this to rotate about the geometry's center rather than the world origin. -### Resampling or Interpolation (Image Geometry Only) +### Interpolation Method (Image Geometry Only) -When transforming an **Image Geometry**, the *Resampling or Interpolation* parameter controls how cell data values are assigned in the newly created grid: +- **Nearest Neighbor [0]** -- each output cell takes the value of the nearest input cell. Fast; preserves sharp boundaries; blocky. +- **Linear (trilinear in 3D) [1]** -- each output cell value is interpolated from surrounding input cells. Smoother; may blur sharp features. +- **No Interpolation [2]** -- no resampling. Use only when the transformation does not change the grid topology (e.g., integer translations that align exactly with the existing grid). -- **Nearest Neighbor Resampling [0]**: Each output cell takes the value of the nearest input cell. This is fast and preserves sharp boundaries, but may produce a blocky appearance. -- **Linear Interpolation [1]**: Each output cell value is computed using trilinear interpolation from the surrounding input cells. This produces smoother results but may blur sharp features. -- **No Interpolation [2]**: The transformation is applied without any resampling of cell data. Use this option when the transformation does not change the grid topology (e.g., integer translations that align exactly with the existing grid). +### Saving the Final Transformation Matrix -## Saving the final transformation Matrix. - -There is an option to save the final transformation matrix into its own array. The format of the output DataArray is a -flattened array 16 elements in size that represents a 4x4 matrix. The elements are encoded in a ROW MAJOR array, i.e., +Optionally, the final 4x4 transformation matrix can be saved as an Attribute Array. The output is a 16-element float32 array in **row-major** order: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 -represents the following 4x4 Matrix +represents the 4x4 matrix: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +### Required Input Sources + +- **Geometry** -- any supported geometry; for Image Geometry workflows, typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. +- **Pre-Computed Transformation Matrix** (only for Transformation Type 1) -- typically produced by [Combine Transformation Matrices](CombineTransformationMatricesFilter.md). +- **Cell Attribute Matrix** (Image Geometry only) -- the cell-level data to be re-gridded. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ApproximatePointCloudHullFilter.md b/src/Plugins/SimplnxCore/docs/ApproximatePointCloudHullFilter.md index 573882d2b4..ce9eb94b30 100644 --- a/src/Plugins/SimplnxCore/docs/ApproximatePointCloudHullFilter.md +++ b/src/Plugins/SimplnxCore/docs/ApproximatePointCloudHullFilter.md @@ -6,24 +6,33 @@ Point Cloud (Geometry) ## Description -This **Filter** determines a set of points that approximates the surface (or *hull*) or a 3D point cloud represented by a **Vertex Geometry**. The hull is approximate in that the surface points are not guaranteed to hve belonged to the original point cloud; instead, the determined set of points is meant to represent a sampling of where the 3D point cloud surface occurs. To following steps are used to approximate the hull: +This **Filter** determines a set of points that approximates the surface (or *hull*) of a 3D point cloud represented by a **Vertex Geometry**. The hull is approximate in that the surface points are not guaranteed to have belonged to the original point cloud; instead, the determined set of points is meant to represent a sampling of where the 3D point cloud surface occurs. The following steps are used to approximate the hull: -1. A structured rectilinear grid with user-defined resolution is overlaid on the point cloud. +1. A structured rectilinear grid with user-defined resolution is overlaid on the point cloud. 2. Each point is mapped to the voxel it occupies in the sampling grid. 3. For each voxel in the sampling grid: 1. Each of its 26 neighbors is inspected to see if that neighbor contains any points. 2. If the number of empty neighbors exceeds a user-defined threshold, the voxel is flagged as a "surface voxel". 4. For each voxel flagged as a "surface voxel", the coordinates of the points in that voxel are averaged to produce a new point that is inserted into the hull. -The above algorithm is significantly faster that other geometric approaches for determining a point cloud surface, but yields only an approximate solution. Note that this approach is able of handling concavities in the point cloud, assuming the grid resolution is small enough to resolve any concavities. In general, a grid resolution should be chosen small enough to resolve any surface features of interest. The algorithm is also sensitive to the minimum number of empty neighbors parameter: consider modifying this parameter if the resulting hull is unsatisfactory. +The above algorithm is significantly faster than other geometric approaches for determining a point cloud surface, but yields only an approximate solution. Note that this approach is capable of handling concavities in the point cloud, assuming the grid resolution is small enough to resolve any concavities. In general, a grid resolution should be chosen small enough to resolve any surface features of interest. The algorithm is also sensitive to the minimum number of empty neighbors parameter: consider modifying this parameter if the resulting hull is unsatisfactory. + +### Parameter Guidance + +- **Grid Resolution** -- the X, Y, and Z edge lengths of the sampling grid voxels, expressed in the same coordinate units as the input point cloud's vertex coordinates. +- **Minimum Number of Empty Neighbors** -- a dimensionless count in the range 0 to 26 (a voxel has 26 neighbors in a 3D grid). A voxel is flagged as a surface voxel when its number of empty neighbors exceeds this value. Larger values flag fewer voxels (only those more exposed on the surface). Note that the resulting hull geometry does not inherit any **Attribute Arrays** from the original point cloud. +### Required Input Sources + +- **Vertex Geometry** -- the input 3D point cloud, typically created by an import step or by a filter that produces a **Vertex Geometry**. + % Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ArrayCalculatorFilter.md b/src/Plugins/SimplnxCore/docs/ArrayCalculatorFilter.md index bc12de72e2..bd119f7a2e 100644 --- a/src/Plugins/SimplnxCore/docs/ArrayCalculatorFilter.md +++ b/src/Plugins/SimplnxCore/docs/ArrayCalculatorFilter.md @@ -135,6 +135,11 @@ This equation takes the cube root of *8* and stores the result in an array with This equation raises *3* to the power of the value stored in every component of every tuple in *Array1*. The resulting array has the same tuple and component size of *Array1*. +### Required Input Sources + +- **Source Attribute Matrix** -- the Attribute Matrix that contains the input arrays referenced in the *Infix Expression*. +- **Output Attribute Matrix** -- an existing Attribute Matrix with the matching tuple count (or with exactly one tuple, when the expression contains no arrays). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ChangeAngleRepresentationFilter.md b/src/Plugins/SimplnxCore/docs/ChangeAngleRepresentationFilter.md index 0071c9233d..d8e35bf9f3 100644 --- a/src/Plugins/SimplnxCore/docs/ChangeAngleRepresentationFilter.md +++ b/src/Plugins/SimplnxCore/docs/ChangeAngleRepresentationFilter.md @@ -23,6 +23,10 @@ Generally, all **Filters** within DREAM3D-NX use radians as a default unit, but If the wrong conversion is selected (e.g., the user chooses *degrees to radians*, but their data is already in radians), the **Filter** will apply the conversion anyway and will result in erroneous data being used for the rest of the pipeline. If unsure about the units, check with the software supplier. +### Required Input Sources + +- An angle **Attribute Array** (e.g., Euler angles), typically read from EBSD data via [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), [Read CTF Data](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read ANG Data](../OrientationAnalysis/ReadAngDataFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/CombineAttributeArraysFilter.md b/src/Plugins/SimplnxCore/docs/CombineAttributeArraysFilter.md index 7284e2f57c..4b1925d925 100644 --- a/src/Plugins/SimplnxCore/docs/CombineAttributeArraysFilter.md +++ b/src/Plugins/SimplnxCore/docs/CombineAttributeArraysFilter.md @@ -32,6 +32,12 @@ The user may also select to normalize the resulting combined array. The normaliz **NOTE:** If you are wanting to instead concatenate/append data arrays together into a longer array, please see the [Concatenate Data Arrays](ConcatenateDataArraysFilter.md) filter. +A typical use case is building a multi-component coordinate or quaternion array from three or four separate single-component scalar arrays (e.g., combining `X_Coord`, `Y_Coord`, `Z_Coord` into a single 3-component `Vertices` array before passing to [Create Geometry](CreateGeometryFilter.md)). + +### Required Input Sources + +- **Input Attribute Arrays** -- two or more arrays of the same primitive type and tuple count, in the order you want their components to appear in the combined array. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/CombineNodeBasedGeometriesFilter.md b/src/Plugins/SimplnxCore/docs/CombineNodeBasedGeometriesFilter.md index 84f7150520..63a0273899 100644 --- a/src/Plugins/SimplnxCore/docs/CombineNodeBasedGeometriesFilter.md +++ b/src/Plugins/SimplnxCore/docs/CombineNodeBasedGeometriesFilter.md @@ -2,15 +2,19 @@ ## Group (Subgroup) -Core +Core (Combining) ## Description -This **Filter** will combine any node-based geometries together into one node-based geometry. The algorithm is governed by several rules: +This **Filter** merges two or more **node-based geometries** into a single combined geometry. A **node-based geometry** is any geometry built from a shared list of vertices (nodes) plus a connectivity that defines its elements: a **Vertex Geometry** (points only), an **Edge Geometry** (line segments), a **Triangle** or **Quadrilateral Geometry** (surface faces), or a **Tetrahedral** or **Hexahedral Geometry** (solid cells). -1. All input geometries must have the same geometry type. For example, inputting all Triangle geometries will output a combined Triangle geometry, all Edge geometries will output a combined Edge geometry, etc. -2. All input geometries must contain vertex and node data that have the exact same names, types, and component dimensions. For example, if one input geometry has an edges array with edges data arrays, all input geometries must have an edges array with edges data arrays that have the exact same names, types, and component dimensions. If one input geometry has vertex data arrays, then all input geometries must have vertex data arrays that all have the exact same names, types, and component dimensions. -3. Higher order input geometries can include lower order node data. For example, an input tetrahedral geometry can include edge data (as long as all input tetrahedral geometries contain edge data with the same names, types, and component dimensions). +When combining, the filter concatenates the vertex lists of all inputs into one list and then renumbers the connectivity. The element (cell) indices from each input geometry are shifted by the running total number of vertices contributed by all preceding geometries, so that every element continues to reference the correct vertices in the merged vertex list. **Duplicate or coincident vertices are *not* detected or merged** — if two inputs contain a vertex at the same physical location, both copies appear in the output. + +The algorithm is governed by several rules: + +1. All input geometries must have the same geometry type. For example, combining only **Triangle Geometries** produces a combined **Triangle Geometry**, and combining only **Edge Geometries** produces a combined **Edge Geometry**. +2. All input geometries must contain vertex and element data arrays with the exact same names, types, and component dimensions. For example, if one input has an edge data array, every input must have an edge data array with a matching name, type, and component dimension; the same requirement applies to vertex data arrays. +3. A **higher-order** geometry (one whose elements are built from more vertices, such as a **Tetrahedral Geometry**) may also carry the data of its **lower-order** elements. For example, a tetrahedral geometry may include edge data, as long as every input tetrahedral geometry includes matching edge data. *NOTE:* Any additional groups, attribute matrices, or arrays that are not one of the following: @@ -19,11 +23,13 @@ This **Filter** will combine any node-based geometries together into one node-ba 3. Face arrays or face data 4. Polyhedra arrays or polyhedra data -WILL BE ignored and will not exist in the geometry outputted by this filter. +will be ignored and will not appear in the geometry produced by this filter. -% Auto generated parameter table will be inserted here +### Required Input Sources -## Example Pipelines +- **Input Geometries** -- two or more **node-based geometries** of the *same* type. Surface meshes are typically produced by [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md); edge geometries by [Slice Triangle Geometry](SliceTriangleGeometryFilter.md) or [Create AM Scan Paths](CreateAMScanPathsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/CombineStlFilesFilter.md b/src/Plugins/SimplnxCore/docs/CombineStlFilesFilter.md index a951a6ef42..d8180d4bce 100644 --- a/src/Plugins/SimplnxCore/docs/CombineStlFilesFilter.md +++ b/src/Plugins/SimplnxCore/docs/CombineStlFilesFilter.md @@ -6,10 +6,10 @@ Reader/Input ## Description -This **Filter** combines all of the STL files from a given directory into a single triangle geometry. This filter will make use of the **Import STL File Filter** to read in each stl file in the given directory and then will proceed to combine each of the imported files into a single triangle geometry. +This **Filter** combines all of the STL files from a given directory into a single triangle geometry. STL (STereoLithography) is a common 3D surface-mesh file format that describes a geometry as an unstructured collection of triangular facets. This filter will make use of the [Read STL File](ReadStlFileFilter.md) filter to read in each STL file in the given directory and then will proceed to combine each of the imported files into a single triangle geometry. There is an option to label the faces and vertices with a "Part Number" that represents the index into the list of files that was used as the input. This would be based on the lexographical index and starts from 1. This allows for the immediate "segmentation" of the resulting triangle geometry or just as a convenience to "color by" in the visualization widget. This can -also be used in the "Write STL Files from Triangle Geometry" Filter if the selection for +also be used in the [Write STL Files from Triangle Geometry](WriteStlFileFilter.md) filter if the selection for the "File Grouping Type" is set to "Part Index" in the UI. Then use the "Part Number" array that is created in this filter for the "Part Index". diff --git a/src/Plugins/SimplnxCore/docs/CombineTransformationMatricesFilter.md b/src/Plugins/SimplnxCore/docs/CombineTransformationMatricesFilter.md index f053420f05..42932532e5 100644 --- a/src/Plugins/SimplnxCore/docs/CombineTransformationMatricesFilter.md +++ b/src/Plugins/SimplnxCore/docs/CombineTransformationMatricesFilter.md @@ -6,24 +6,41 @@ Core ## Description -The **Combine Transformation Matrices** filter merges multiple 4×4 transformation matrices into a single composite transformation. +This **Filter** multiplies multiple 4x4 transformation matrices together to produce a single composite 4x4 matrix. Use it when you have a sequence of transformations (rotations, translations, scales, etc.) that need to be combined before applying them to an Image Geometry. -Each input matrix must be provided as a 16-element float32 DataArray in row-major order, representing operations such as translation, rotation, scaling, or shear. During the preflight phase, the filter verifies that at least two matrices are selected, each contains exactly 16 elements (4 tuples × 4 components OR 16 tuples x 1 component OR 1 tuple x 16 components, etc), and all input arrays share the same tuple and component layout. +### When to Use This Filter -## Saving the Output Transformation Matrix. +[Apply Transformation to Geometry](ApplyTransformationToGeometryFilter.md) re-grids cell data each time it runs. Applying multiple transformations one at a time to an Image Geometry compounds re-gridding artifacts. The correct approach is to combine all the transformations into a single 4x4 matrix first using this filter, then apply that combined matrix as a single transformation. See the *Image Geometry Caveat* section in [Apply Transformation to Geometry](ApplyTransformationToGeometryFilter.md) for the visual demonstration. -The format of the output DataArray is a flattened array 16 elements in size that represents a 4x4 matrix. -The elements are encoded in ROW MAJOR order, i.e., +For node-based geometries (Vertex, Edge, Triangle, Quad, Tet, Hex), there is no re-gridding step, so successive transformations are safe and this filter is not strictly needed -- but combining is still slightly more efficient than chaining. + +### Input Format + +Each input matrix must be a 16-element float32 **Attribute Array** in **row-major** order: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 -represents the following 4x4 Matrix +represents the 4x4 matrix: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +The component shape can be any layout that yields 16 total elements (4×4, 16×1, or 1×16). All input matrices must share the same tuple and component layout. + +### Multiplication Order + +The matrices are multiplied in the order listed in the parameter. The result represents applying the **first** matrix first, then the second, and so on. In matrix algebra, this means: + + M_combined = M_last * M_(last-1) * ... * M_2 * M_1 + +which corresponds to applying M_1 first to a vector v: `v' = M_combined * v = M_last * ... * M_2 * M_1 * v`. + +### Required Input Sources + +- **Transformation Matrices** -- at least two 4x4 float32 matrices, typically authored by hand or produced by an earlier [Apply Transformation to Geometry](ApplyTransformationToGeometryFilter.md) run with the *Saving the Final Transformation Matrix* option enabled. + % Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramByFeatureFilter.md b/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramByFeatureFilter.md index f487c7d610..7b2ff75c19 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramByFeatureFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramByFeatureFilter.md @@ -2,7 +2,7 @@ ## Description -This **Filter** accepts one or more numeric **DataArray** inputs and computes feature-specific histograms. For each selected array, values are grouped by feature, then divided into equal-width bins—using either automatically derived or user-defined minimum/maximum bounds—and counted per bin. +This **Filter** accepts one or more numeric **DataArray** inputs and computes per-**Feature** histograms. A **Feature** is a connected region of **Cells** that share the same **Feature Id** (the integer label assigned by a segmentation filter). For each selected array, the per-Cell values are grouped according to their owning **Feature Id**, then divided into equal-width bins—using either automatically derived or user-defined minimum/maximum bounds—and counted per bin. Optionally, a mask **DataArray** can be provided to include only specific elements in the histogram computation. @@ -16,9 +16,11 @@ Outputs include: - **Modal Bin Ranges INeighborList** (optional): One NeighborList that contains one list per feature specifying inclusive lower bound and exclusive upper bound containing the feature's mode(s). Because there can be multiple modes, each list may include more than 2 entries. - *Example*: list 5 contains `[0.5, 10.2, 41.3, 54.1]` if feature 5 has two mode values and they fall between 0.5 and 10.2 and between 41.3 and 54.1. -% Auto generated parameter table will be inserted here +### Required Input Sources + +- **Cell Feature Ids** -- the per-Cell **Feature** label array, typically produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or another segmentation filter. -## Example Pipelines +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramFilter.md b/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramFilter.md index 5ae0d38023..ab03a75adb 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeArrayHistogramFilter.md @@ -6,15 +6,20 @@ This **Filter** accepts one or more numeric **DataArray** inputs and generates c Optionally, a mask **DataArray** can be provided to include only specific elements in the histogram computation. -Outputs include: +The created histogram arrays are written into the target **DataGroup**. For each input array the following arrays are produced: + - **Counts DataArray**: A tuple for each bin representing the number of elements in that bin. -- **Bin Ranges DataArray**: A two-component tuple per bin defining the inclusive lower bound and exclusive upper bound. +- **Bin Ranges DataArray**: A two-component tuple per bin defining the inclusive lower bound and exclusive upper bound. The bin bounds carry the same units as the input array (for example, if the input array is in micrometers, the bin bounds are in micrometers). - **Most Populated Bin DataArray**: Reports the index of the bin that has the most values. -- **Modal Bin Ranges NeighborList** (optional): Specifies the inclusive lower and exclusive upper bound bin indices containing the input data’s mode(s). Because there can be multiple modes, this list may include more than two entries. +- **Modal Bin Ranges NeighborList** (optional): Specifies the inclusive lower and exclusive upper bound bin indices containing the input data's *mode(s)*. The *mode* is the value (or values) that occurs most frequently in the data. Because there can be multiple modes, this list may include more than two entries. + +### Required Input Sources + +None -- this filter operates on any generic numeric **DataArray** regardless of how it was produced. ## Example Data -Using some data about the "Old Faithful" geyser in the United States from the [R site](http://www.r-tutor.com/elementary-statistics/quantitative-data/frequency-distribution-quantitative-data), here is the top few lines of data: +Using the "Old Faithful" geyser data set from the [R site](http://www.r-tutor.com/elementary-statistics/quantitative-data/frequency-distribution-quantitative-data) (272 eruptions; the full data set is not reproduced here), the first few rows of the *Duration* and *Wait Time* columns are: Duration, Wait Time {3.6,79}, @@ -61,281 +66,3 @@ Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. - -### Example Data (Raw) - -```text - Index, Duration, Wait Time - {1,3.6,79}, - {2,1.8,54}, - {3,3.333,74}, - {4,2.283,62}, - {5,4.533,85}, - {6,2.883,55}, - {7,4.7,88}, - {8,3.6,85}, - {9,1.95,51}, - {10,4.35,85}, - {11,1.833,54}, - {12,3.917,84}, - {13,4.2,78}, - {14,1.75,47}, - {15,4.7,83}, - {16,2.167,52}, - {17,1.75,62}, - {18,4.8,84}, - {19,1.6,52}, - {20,4.25,79}, - {21,1.8,51}, - {22,1.75,47}, - {23,3.45,78}, - {24,3.067,69}, - {25,4.533,74}, - {26,3.6,83}, - {27,1.967,55}, - {28,4.083,76}, - {29,3.85,78}, - {30,4.433,79}, - {31,4.3,73}, - {32,4.467,77}, - {33,3.367,66}, - {34,4.033,80}, - {35,3.833,74}, - {36,2.017,52}, - {37,1.867,48}, - {38,4.833,80}, - {39,1.833,59}, - {40,4.783,90}, - {41,4.35,80}, - {42,1.883,58}, - {43,4.567,84}, - {44,1.75,58}, - {45,4.533,73}, - {46,3.317,83}, - {47,3.833,64}, - {48,2.1,53}, - {49,4.633,82}, - {50,2,59}, - {51,4.8,75}, - {52,4.716,90}, - {53,1.833,54}, - {54,4.833,80}, - {55,1.733,54}, - {56,4.883,83}, - {57,3.717,71}, - {58,1.667,64}, - {59,4.567,77}, - {60,4.317,81}, - {61,2.233,59}, - {62,4.5,84}, - {63,1.75,48}, - {64,4.8,82}, - {65,1.817,60}, - {66,4.4,92}, - {67,4.167,78}, - {68,4.7,78}, - {69,2.067,65}, - {70,4.7,73}, - {71,4.033,82}, - {72,1.967,56}, - {73,4.5,79}, - {74,4,71}, - {75,1.983,62}, - {76,5.067,76}, - {77,2.017,60}, - {78,4.567,78}, - {79,3.883,76}, - {80,3.6,83}, - {81,4.133,75}, - {82,4.333,82}, - {83,4.1,70}, - {84,2.633,65}, - {85,4.067,73}, - {86,4.933,88}, - {87,3.95,76}, - {88,4.517,80}, - {89,2.167,48}, - {90,4,86}, - {91,2.2,60}, - {92,4.333,90}, - {93,1.867,50}, - {94,4.817,78}, - {95,1.833,63}, - {96,4.3,72}, - {97,4.667,84}, - {98,3.75,75}, - {99,1.867,51}, - {100,4.9,82}, - {101,2.483,62}, - {102,4.367,88}, - {103,2.1,49}, - {104,4.5,83}, - {105,4.05,81}, - {106,1.867,47}, - {107,4.7,84}, - {108,1.783,52}, - {109,4.85,86}, - {110,3.683,81}, - {111,4.733,75}, - {112,2.3,59}, - {113,4.9,89}, - {114,4.417,79}, - {115,1.7,59}, - {116,4.633,81}, - {117,2.317,50}, - {118,4.6,85}, - {119,1.817,59}, - {120,4.417,87}, - {121,2.617,53}, - {122,4.067,69}, - {123,4.25,77}, - {124,1.967,56}, - {125,4.6,88}, - {126,3.767,81}, - {127,1.917,45}, - {128,4.5,82}, - {129,2.267,55}, - {130,4.65,90}, - {131,1.867,45}, - {132,4.167,83}, - {133,2.8,56}, - {134,4.333,89}, - {135,1.833,46}, - {136,4.383,82}, - {137,1.883,51}, - {138,4.933,86}, - {139,2.033,53}, - {140,3.733,79}, - {141,4.233,81}, - {142,2.233,60}, - {143,4.533,82}, - {144,4.817,77}, - {145,4.333,76}, - {146,1.983,59}, - {147,4.633,80}, - {148,2.017,49}, - {149,5.1,96}, - {150,1.8,53}, - {151,5.033,77}, - {152,4,77}, - {153,2.4,65}, - {154,4.6,81}, - {155,3.567,71}, - {156,4,70}, - {157,4.5,81}, - {158,4.083,93}, - {159,1.8,53}, - {160,3.967,89}, - {161,2.2,45}, - {162,4.15,86}, - {163,2,58}, - {164,3.833,78}, - {165,3.5,66}, - {166,4.583,76}, - {167,2.367,63}, - {168,5,88}, - {169,1.933,52}, - {170,4.617,93}, - {171,1.917,49}, - {172,2.083,57}, - {173,4.583,77}, - {174,3.333,68}, - {175,4.167,81}, - {176,4.333,81}, - {177,4.5,73}, - {178,2.417,50}, - {179,4,85}, - {180,4.167,74}, - {181,1.883,55}, - {182,4.583,77}, - {183,4.25,83}, - {184,3.767,83}, - {185,2.033,51}, - {186,4.433,78}, - {187,4.083,84}, - {188,1.833,46}, - {189,4.417,83}, - {190,2.183,55}, - {191,4.8,81}, - {192,1.833,57}, - {193,4.8,76}, - {194,4.1,84}, - {195,3.966,77}, - {196,4.233,81}, - {197,3.5,87}, - {198,4.366,77}, - {199,2.25,51}, - {200,4.667,78}, - {201,2.1,60}, - {202,4.35,82}, - {203,4.133,91}, - {204,1.867,53}, - {205,4.6,78}, - {206,1.783,46}, - {207,4.367,77}, - {208,3.85,84}, - {209,1.933,49}, - {210,4.5,83}, - {211,2.383,71}, - {212,4.7,80}, - {213,1.867,49}, - {214,3.833,75}, - {215,3.417,64}, - {216,4.233,76}, - {217,2.4,53}, - {218,4.8,94}, - {219,2,55}, - {220,4.15,76}, - {221,1.867,50}, - {222,4.267,82}, - {223,1.75,54}, - {224,4.483,75}, - {225,4,78}, - {226,4.117,79}, - {227,4.083,78}, - {228,4.267,78}, - {229,3.917,70}, - {230,4.55,79}, - {231,4.083,70}, - {232,2.417,54}, - {233,4.183,86}, - {234,2.217,50}, - {235,4.45,90}, - {236,1.883,54}, - {237,1.85,54}, - {238,4.283,77}, - {239,3.95,79}, - {240,2.333,64}, - {241,4.15,75}, - {242,2.35,47}, - {243,4.933,86}, - {244,2.9,63}, - {245,4.583,85}, - {246,3.833,82}, - {247,2.083,57}, - {248,4.367,82}, - {249,2.133,67}, - {250,4.35,74}, - {251,2.2,54}, - {252,4.45,83}, - {253,3.567,73}, - {254,4.5,73}, - {255,4.15,88}, - {256,3.817,80}, - {257,3.917,71}, - {258,4.45,83}, - {259,2,56}, - {260,4.283,79}, - {261,4.767,78}, - {262,4.533,84}, - {263,1.85,58}, - {264,4.25,83}, - {265,1.983,43}, - {266,2.25,60}, - {267,4.75,75}, - {268,4.117,81}, - {269,2.15,46}, - {270,4.417,90}, - {271,1.817,46}, - {272,4.467,74}} -``` diff --git a/src/Plugins/SimplnxCore/docs/ComputeArrayStatisticsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeArrayStatisticsFilter.md index ee5ab4158c..bd3be225cc 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeArrayStatisticsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeArrayStatisticsFilter.md @@ -2,13 +2,13 @@ ## Group (Subgroup) -DREAM3D Review (Statistics) +Statistics ## Description ***WARNING: The Histogram functionality has been moved to a new filter.*** -This **Filter** computes a variety of statistics for a given scalar array. The currently available statistics are array length, minimum, maximum, (arithmetic) mean, median, mode, standard deviation, and summation; any combination of these statistics may be computed by this **Filter**. Any scalar array, of any primitive type, may be used as input. The type of the output arrays depends on the kind of statistic computed: +This filter computes a variety of statistics for a given scalar array. The currently available statistics are array length, minimum, maximum, (arithmetic) mean, median, mode, standard deviation, and summation; any combination of these statistics may be computed. Any scalar array, of any primitive type, may be used as input. The type of each output array depends on the kind of statistic computed: | Statistic | Primitive Type | |-------------------------|-------------------------------------| @@ -23,64 +23,41 @@ This **Filter** computes a variety of statistics for a given scalar array. The c | Standardized | 32-bit float | | Number of Unique Values | signed 32-bit integer | -The user may optionally use a mask to specify points to be ignored when computing the statistics; only points where the supplied mask is *true* will be considered when computing statistics. Additionally, the user may select to have the statistics computed per **Feature** or **Ensemble** by supplying an Ids array. For example, if the user opts to compute statistics per **Feature** and selects an array that has 10 unique **Feature** Ids, then this **Filter** will compute 10 sets of statistics (e.g., find the mean of the supplied array for each **Feature**, find the total number of points in each **Feature** (the length), etc.). +A **Feature** is a contiguous region of the data (such as a grain) identified by a unique integer **Feature** Id; an **Ensemble** is a higher-level grouping of **Features** (such as a phase). The filter can compute statistics over the whole array, or per **Feature**/**Ensemble** when a **Feature** Ids array is supplied. -The input array may also be *standardized*, meaning that the array values will be adjusted such that they have a mean of 0 and unit variance. This *Standardize Data* option requires the selection of both the *Find Mean* and *Find Standard Deviation* options. The standardized data will be saved as a new array object stored in the same **Attribute Matrix** as the input array. Note that if the *Standardize Data* option is selected, the mean and standard deviation values created by this **Filter** reflect the mean and standard deviation of the *original* array; the new standardized array has a mean of 0 and unit variance. The standardized array will be computed in double precision. If the statistics are being computed per **Feature** or **Ensemble**, then the array values are standardized according to the mean and standard deviation *for each **Feature/Ensemble***. For example, if 5 unique **Features** were being analyzed and *Standardize Data* was selected, then the array values for **Feature** 1 would be standardized according to the mean and standard deviation for **Feature** 1, then the array values for **Feature** 2 would be standardized according to the mean and standard deviation for **Feature** 2, and so on for the remaining **Features**. +The user may optionally use a mask to specify points to be ignored when computing the statistics; only points where the supplied mask is *true* are considered. Additionally, the user may compute the statistics per **Feature** or **Ensemble** by supplying a **Feature** Ids array. For example, if the user computes statistics per **Feature** and selects an array that has 10 unique **Feature** Ids, then the filter computes 10 sets of statistics (the mean of the supplied array for each **Feature**, the total number of points in each **Feature** (the length), and so on). -Special operations occur for certain statistics if the supplied array is of type *bool* (for example, a mask array produced from threshold filters). The *length*, *minimum*, *maximum*, *median*, *mode*, and *summation* are computed as normal (although the resulting values may be platform dependent). The *mean* and *standard deviation* for a boolean array will be true if there are more instances of true in the array than false. If *Standardize Data* is chosen for a boolean array, no actual modifications will be made to the input. These operations for boolean inputs are chosen as a basic convention, and are not intended be representative of true boolean logic. +The input array may also be *standardized*, meaning that the array values are adjusted so that they have a mean of 0 and unit variance. This *Standardize Data* option requires that both *Find Mean* and *Find Standard Deviation* are also selected. The standardized data is saved as a new array stored in the same **Attribute Matrix** as the input array. When *Standardize Data* is selected, the mean and standard deviation values created by this filter reflect the mean and standard deviation of the *original* array; the new standardized array has a mean of 0 and unit variance. The standardized array is computed in double precision. If statistics are computed per **Feature** or **Ensemble**, then the array values are standardized according to the mean and standard deviation *for each **Feature**/**Ensemble***. For example, with 5 unique **Features** and *Standardize Data* selected, the values for **Feature** 1 are standardized using the mean and standard deviation of **Feature** 1, the values for **Feature** 2 are standardized using those of **Feature** 2, and so on. -## Destination Attribute Matrix +Special operations occur for certain statistics if the supplied array is of type *bool* (for example, a mask array produced from threshold filters). The *length*, *minimum*, *maximum*, *median*, *mode*, and *summation* are computed as normal (although the resulting values may be platform dependent). The *mean* and *standard deviation* for a boolean array are *true* if there are more instances of *true* in the array than *false*. If *Standardize Data* is chosen for a boolean array, no modifications are made to the input. These operations for boolean inputs are chosen as a basic convention, and are not intended to be representative of true boolean logic. -The user must create a destination **Attribute Matrix** in which the computed statistics will be stored. DREAM3D-NX enforces a rule where any Attribute Matrix cannot contain another Attribute Matrix. With this in mind, the user should select a destination that is not itself an Attribute Matrix, such as the top level of a Geometry or the top level of the Data Structure itself. The user could have also created a group (using a previous filter) and use that group as the destination. +## Destination Attribute Matrix + +The user must create a destination **Attribute Matrix** in which the computed statistics are stored. DREAM3D-NX enforces a rule that an **Attribute Matrix** cannot contain another **Attribute Matrix**. With this in mind, the user should select a destination that is not itself an **Attribute Matrix**, such as the top level of a **Geometry** or the top level of the Data Structure itself. The user could also have created a group (using a previous filter) and use that group as the destination. ![Images/Compute_Array_Statistics_1.png](Images/Compute_Array_Statistics_1.png) -The user is creating the destination Attribute Matrix inside the `DataContainer` geometry. +The user is creating the destination **Attribute Matrix** inside the `DataContainer` geometry. ![Images/Compute_Array_Statistics_2.png](Images/Compute_Array_Statistics_2.png) -The user is creating the destination Attribute Matrix inside the `Statistics` group which was created by filter #2 in the pipeline. +The user is creating the destination **Attribute Matrix** inside the `Statistics` group which was created by filter #2 in the pipeline. ### Feature Range Type -The *Feature Range Type* parameter provides the following choices: - -- **None [0]**: No feature-based range is applied; statistics are computed over the entire array without range constraints. -- **Ignore Feature 0 [1]**: Excludes Feature Id 0 (the invalid/background feature) from statistics calculations. -- **Shrink To Fit [2]**: Automatically determines the minimum and maximum Feature Ids present and uses that as the range, removing empty entries. -- **Padded Custom Range [3]**: Uses a user-specified range and pads with generated/filled values for Feature Ids below the minimum and above the maximum actually present in the data. -- **Minimum Size in Custom Range [4]**: Uses a user-specified range but clamps to the actual min/max Feature Ids if the specified bounds exceed them, avoiding padding. - -## Ranges Breakdown - -The ranges feature was added to primarily offer the following functionality: - -1. option to output an array that has the Feature id in it. (Feature Ids Indexing Array) -2. option to set the "Feature Id" range. - -- Allow the user to "pad out the feature ids" to a specific range -- Allow the user to only compute stats for specific feature Ids - -3. option to Ignore Feature Id Zero. -4. remove empty spaces for feature ids that start above 1 - -All of these can be achieved with the new functionality, here's how: - -### Option 1 - -For option 1, this array (Feature Ids Indexing Array) is automatically created for any Range selection other than `None`. The nuance here is that if your range or `Shrink To Fit` contains all the features this array will be redundant and can be removed, however, this is a very niche occurance and users are encouraged to just select `None` if they know this to be the case. - -### Option 2 - -For option 2, this is provided with both the `Padded Custom Range` and `Minimum Size in Custom Range`. The latter is intended for users who are trying to cut down size without aproiri knowledge of the number of features. It will chop anything outside the upper bound or take the max feature if the custom upper bound exceeds it. The same is true for the lower bound in that it will take the higher of the two between provided range and the min Feature Id. `Padded Custom Range` will fill generate/fill extra values for values below and above the minimum and maximum Feature Id respectively. See the bonus section for additional range features. +When computing per-**Feature** statistics, the *Feature Range Type* parameter controls which **Feature** Ids are included and how the output is indexed (these are all dimensionless integer **Feature** Id selections): -### Option 3 +- **None [0]**: No feature-based range is applied; statistics are computed for every **Feature** Id present. +- **Ignore Feature 0 [1]**: Excludes **Feature** Id 0 (the invalid/background feature) from the calculations. +- **Shrink To Fit [2]**: Automatically determines the minimum and maximum **Feature** Ids present and uses that as the range, removing empty entries. +- **Padded Custom Range [3]**: Uses the user-specified *Feature Ids Min Max Range* and generates filled values for **Feature** Ids below the minimum and above the maximum actually present in the data. +- **Minimum Size in Custom Range [4]**: Uses the user-specified range but clamps to the actual min/max **Feature** Ids if the specified bounds exceed them, avoiding padding. -For option 3, the ability to ignore Feature Id Zero (the invalid Feature Id) is provided directly in the form of `Ignore Feature 0` and indirectly through ranges. +For any range selection other than *None*, the filter also creates a *Feature Ids Indexing Array* that records the **Feature** Id each row of statistics corresponds to. If the selected range already contains every **Feature**, this indexing array is redundant and may be removed; in that niche case selecting *None* is simpler. -### Option 4 +*Tip: If the maximum **Feature** Id in a custom range is unknown, supplying `-1` for the upper bound causes the filter to determine the maximum **Feature** Id at run time and use it as the upper bound.* -For option 4, the most direct feature to address this is the `Shrink to Fit` range option, however it can also be achived with `Minimum Size in Custom Range`. +### Required Input Sources -*Bonus: If you are unsure of the max feature id in your range, supplying a `-1` will determine the maximum feature id and use it as the upper bound in execution.* +- **Cell Feature Ids** -- required only when computing statistics per **Feature**/**Ensemble**; produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here @@ -88,7 +65,7 @@ For option 4, the most direct feature to address this is the `Shrink to Fit` ran ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeBiasedFeaturesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeBiasedFeaturesFilter.md index 14bfa04e6f..1820b1f91c 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeBiasedFeaturesFilter.md +++ b/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 diff --git a/src/Plugins/SimplnxCore/docs/ComputeBoundaryCellsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeBoundaryCellsFilter.md index 9f3a965755..5c6332366b 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeBoundaryCellsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeBoundaryCellsFilter.md @@ -17,6 +17,12 @@ This **Filter** determines, for each **Cell**, the number of neighboring **Cells |--|--| | ![Feature Ids](Images/ComputeBoundaryCellsInput.png) | ![Boundary Cells](Images/ComputeBoundaryCellsOutput.png) | +The output is a per-**Cell** count ranging from **0** (an interior cell whose six neighbors all belong to the same **Feature**) to **6** (an isolated cell differing from all six neighbors). Cells on the outer edge of the volume have fewer than six in-bounds neighbors, so their count reflects only the neighbors that exist. + +### Required Input Sources + +- **Feature Ids** -- a per-**Cell** integer label array produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeBoundaryElementFractionsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeBoundaryElementFractionsFilter.md index 776055835c..de3b5a8aa8 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeBoundaryElementFractionsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeBoundaryElementFractionsFilter.md @@ -6,11 +6,20 @@ Statistics (Morphological) ## Description -This **Filter** calculates the fraction of **Elements** of each **Feature** that are on the "surface" of that **Feature**. The **Filter** simply iterates through all **Elements** asking for the **Feature** that owns them and if the **Element** is a "surface" **Element**. Each **Feature** counts the total number of **Elements** it owns and the number of those **Elements** that are "surface" **Elements**. The fraction is then stored for each **Feature**. +This **Filter** calculates, for each **Feature**, the fraction of its **Elements** that lie on the boundary ("surface") of that **Feature**. A **Feature** is a contiguous region of like-segmented cells (for example a grain), and an **Element** is a single cell of the geometry. An **Element** is considered a *surface* (boundary) **Element** when at least one of its neighboring **Elements** belongs to a different **Feature**. This boundary flag is not computed here; it is supplied through the *Surface Elements* input array, where any value greater than zero (the count of differing neighbors) marks the **Element** as a boundary **Element**. -% Auto generated parameter table will be inserted here +The **Filter** iterates through every **Element**, asking which **Feature** owns it and whether it is a boundary **Element**. Each **Feature** accumulates the total number of **Elements** it owns and the number of those that are boundary **Elements**. The output for each **Feature** is the ratio: + +> boundary Elements / total Elements + +This is a dimensionless fraction in the range [0, 1]. A value near 0 means the **Feature** is large and compact relative to its surface; a value near 1 means nearly all of the **Feature**'s **Elements** touch a neighbor of a different **Feature** (a thin or small **Feature**). -## Example Pipelines +### Required Input Sources + +- **Cell Feature Ids** -- the Feature that owns each Element, produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). +- **Surface Elements** -- the per-Element count of neighbors belonging to a different Feature, produced by [Compute Boundary Cells (Image)](ComputeBoundaryCellsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ComputeBoundingBoxStatsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeBoundingBoxStatsFilter.md index 7c20b22428..165565b97c 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeBoundingBoxStatsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeBoundingBoxStatsFilter.md @@ -6,9 +6,9 @@ Statistics ## Description -***NOTE:* This filter is intended to allow each cell value to map to 0 or more bounding boxes (1 to Many architecture). This comes with the caveat that the option `Standardize Data` offered by `Compute Array Statistics` cannot be included as functionality in this filter.** +***NOTE:* This filter allows each **Cell** value to contribute to 0 or more bounding boxes (a 1-to-many architecture). This comes with the caveat that the *Standardize Data* option offered by [Compute Attribute Array Statistics](ComputeArrayStatisticsFilter.md) cannot be included as functionality in this filter.** -This **Filter** computes a variety of statistics for a given scalar array. The currently available statistics are array length, minimum, maximum, (arithmetic) mean, median, mode, standard deviation, summation, and Number of Unique values; any combination of these statistics may be computed by this **Filter**. Any scalar array, of any primitive type, may be used as input. The type of the output arrays depends on the kind of statistic computed: +This filter computes a variety of statistics for a given scalar array, restricted to the **Cells** that fall inside each supplied bounding box. Because boxes may overlap (or leave gaps), a single **Cell** may be counted toward several boxes, exactly one box, or none. The currently available statistics are array length, minimum, maximum, (arithmetic) mean, median, mode, standard deviation, summation, and number of unique values; any combination of these statistics may be computed. Any scalar array, of any primitive type, may be used as input. The type of each output array depends on the kind of statistic computed: | Statistic | Primitive Type | |-------------------------|-------------------------------------| @@ -22,11 +22,15 @@ This **Filter** computes a variety of statistics for a given scalar array. The c | Summation | 32-bit float | | Number of Unique Values | signed 32-bit integer | -The *Unified Bounds Array* is a 6 component **DataArray** that contains the lower XYZ bound and upper XYZ bound for the bounding box. The component ordering is expected as follows `{Min-X, Min-Y, Min-Z, Max-X, Max-Y, Max-Z}`. This ordering is provided so the user knows how to format imported external data. The *Compute Feature Bounds* filter's `Unified Array` option puts out a correctly formatted array for input to this filter. +The *Unified Bounds Array* is a 6-component **DataArray** that contains the lower XYZ bound and upper XYZ bound for each bounding box. The component ordering is `{Min-X, Min-Y, Min-Z, Max-X, Max-Y, Max-Z}`. These bounds are expressed in the **Geometry**'s physical coordinate units (the same length units as the geometry's origin and spacing, typically microns). This ordering is provided so the user knows how to format imported external data. The [Compute Feature Bounding Boxes](ComputeFeatureBoundsFilter.md) filter's *Unified Array* option produces a correctly formatted array for input to this filter. -The user must select or create a destination **Attribute Matrix** in which the computed statistics will be stored. If selecting an exisitng **Attribute Matrix**, then a reasonable selection for this array is the **Attribute Matrix** that the *Unified Bounds Array* comes from. However, the only requirement is that the number of columns in the selected destination **Attribute Matrix** match the number of tuples in the *Unified Bounds Array*. This requirement is enforced during preflight. If the option to create an Attribute Matrix is selected, it will be created in the supplied geometry sized appropriately. +The user must select or create a destination **Attribute Matrix** in which the computed statistics are stored. When selecting an existing **Attribute Matrix**, a reasonable choice is the **Attribute Matrix** that the *Unified Bounds Array* comes from. However, the only requirement is that the number of tuples in the selected destination **Attribute Matrix** match the number of tuples (boxes) in the *Unified Bounds Array*. This requirement is enforced during preflight. If the option to create a new **Attribute Matrix** is selected, it is created in the supplied **Geometry**, sized appropriately. -Special operations occur for certain statistics if the supplied array is of type *bool* (for example, a mask array produced [when thresholding](@ref multithresholdobjects)). The length, minimum, maximum, median, mode, and summation are computed as normal (although the resulting values may be platform dependent). The mean and standard deviation for a boolean array will be true if there are more instances of true in the array than false. These operations for boolean inputs are chosen as a basic convention, and are not intended be representative of true boolean logic. +Special operations occur for certain statistics if the supplied array is of type *bool* (for example, a mask array produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md)). The length, minimum, maximum, median, mode, and summation are computed as normal (although the resulting values may be platform dependent). The mean and standard deviation for a boolean array are *true* if there are more instances of *true* in the array than *false*. These operations for boolean inputs are chosen as a basic convention, and are not intended to be representative of true boolean logic. + +### Required Input Sources + +- **Unified Bounds Array** -- a 6-component bounds array produced by the *Unified Array* output option of [Compute Feature Bounding Boxes](ComputeFeatureBoundsFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeCoordinateThresholdFilter.md b/src/Plugins/SimplnxCore/docs/ComputeCoordinateThresholdFilter.md index 5e98fa94d2..50c14140f5 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeCoordinateThresholdFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeCoordinateThresholdFilter.md @@ -6,7 +6,9 @@ Geometry ## Description -This filter produces a mask that marks cells that fall inside or outside a given bounding shape within a supplied geometry. The filter outputs a mask to provide the greatest flexibility, while leveraging existing algorithms. This filter doesn't modify the input geometry in any way if you wish to modify the data within the bounding box, consider using one of the cleanup filters on the marked values. See *Remove Flagged Vertices/Edges/Triangles* for an example of a potential followup filter. +This filter produces a mask that marks cells that fall inside or outside a given bounding shape within a supplied geometry. The filter outputs a mask to provide the greatest flexibility, while leveraging existing algorithms. This filter doesn't modify the input geometry in any way; if you wish to modify the data within the bounding box, consider using one of the cleanup filters on the marked values. See [Remove Flagged Vertices](RemoveFlaggedVerticesFilter.md), [Remove Flagged Edges](RemoveFlaggedEdgesFilter.md), or [Remove Flagged Triangles](RemoveFlaggedTrianglesFilter.md) for examples of potential followup filters. + +All threshold bounds (the rectangle minimum/maximum coordinates and the sphere center/radius) are specified in **physical coordinates** — the same length units as the input geometry's vertex positions (or, for an **Image Geometry**, its origin and spacing) — not in cell/voxel indices. ### Coordinate Container Shape @@ -33,6 +35,8 @@ The way a point is determined to be in the sphere uses the following calculation `(p_x - c_x)^2 + (p_y - c_y)^2 + (p_z - c_z)^2 <= r^2` +The center `c` (first 3 values of *Sphere Info*) and radius `r` (4th value) are both given in **physical coordinate** units matching the geometry. + ### Inverting the Mask This is primarily a convenience option provided to the user. If toggled on the values will be true (`1`) by default and values withing the bounds will be marked false (`0`). This doesn't modify anything other than switching what value is set for bounds that fall inside or outside respectively. diff --git a/src/Plugins/SimplnxCore/docs/ComputeCoordinatesImageGeomFilter.md b/src/Plugins/SimplnxCore/docs/ComputeCoordinatesImageGeomFilter.md index 1f457470c2..f7a4201f64 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeCoordinatesImageGeomFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeCoordinatesImageGeomFilter.md @@ -6,19 +6,25 @@ Statistics ## Description -This **Filter** produces one or two arrays that stores implicit image information (indices and physical coordinates of each point) as explicit cell level data. The produced arrays are in XYZ component format and stored as X by Y by Z, starting from the origin. The intention behind this filter is primarily for output compatibility and readability. +This **Filter** writes the per-cell coordinates and/or grid indices of an **Image Geometry** into regular cell-level **Attribute Arrays**. In an Image Geometry, each cell's (i, j, k) index and (x, y, z) physical position are implicit -- derivable from the geometry's dimensions, origin, and spacing. This filter makes them explicit so they can be exported to CSV/text, used as inputs to downstream math filters, or visualized directly. + +### When to Use This Filter + +Most commonly used as a preparation step before exporting cell data to CSV or other text formats that need explicit coordinate columns. Also useful when a downstream filter needs the (x, y, z) of each cell as a regular array (e.g., for distance calculations). ### Output Array(s) Type -The *Output Array(s) Type* parameter controls which arrays are produced by the filter: +- **Physical Coordinates [0]**: produces a single 3-component float array containing the (x, y, z) physical coordinates of the center of each cell, computed from the geometry's origin and spacing. +- **Indices [1]**: produces a single 3-component integer array containing the (i, j, k) grid indices of each cell. Indices are **0-based**. +- **Both [2]**: produces both arrays. -- **Physical Coordinates [0]**: Outputs a single 3-component array containing the physical (spatial) XYZ coordinates of the center of each cell, computed from the geometry's origin and spacing. -- **Indices [1]**: Outputs a single 3-component array containing the integer ijk grid indices of each cell. -- **Both [2]**: Outputs both the physical coordinates array and the indices array. +### Cell Order -The arrays follow the following cell parsing scheme: `0,0,0 -> 1,0,0 -> 2,0,0 -> ... n,0,0 -> 0,1,0 -> 1,1,0 -> 2,1,0 -> ... n,n,0 -> 0,0,1 -> 1,0,1 -> 2,0,1 -> ... n,n,n`. +The arrays are stored in the geometry's default cell raster order: X varies fastest, then Y, then Z. -The printed output will look something like this: + (0,0,0) → (1,0,0) → (2,0,0) → ... (n,0,0) → (0,1,0) → (1,1,0) → ... (n,n,0) → (0,0,1) → ... + +A sample of the output for a 9-column slice (showing both indices and physical coordinates): ```console Image Indices_0,Image Indices_1,Image Indices_2,Image Physical Coordinates_0,Image Physical Coordinates_1,Image Physical Coordinates_2 @@ -33,6 +39,15 @@ Image Indices_0,Image Indices_1,Image Indices_2,Image Physical Coordinates_0,Ima 8,0,0,-45.125,0.125,-0.37500411 ``` +### Units + +- **Physical coordinates** are in the geometry's physical units (microns, millimeters, etc.). +- **Indices** are dimensionless integers (0-based cell indices along each axis). + +### Required Input Sources + +- **Input Image Geometry** -- the geometry whose per-cell coordinates/indices will be made explicit. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeDifferencesMapFilter.md b/src/Plugins/SimplnxCore/docs/ComputeDifferencesMapFilter.md index 065ea70601..5d6bee7e7e 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeDifferencesMapFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeDifferencesMapFilter.md @@ -18,9 +18,13 @@ Note that in the above algorithm, the difference is taken as the *first selected **WARNING: The resulting difference values *may be negative* if the values of the first array are smaller than those in the second array. Therefore, if the two arrays are *unsigned integers*, it may be possible to underflow the resulting difference map values if the first array is sufficiently smaller than the second array. "Underflow" means that what should be a negative value will end up being a potentially very large value!** -% Auto generated parameter table will be inserted here +The output Difference Map is created at the user-specified path and inherits the primitive type, component shape, and number of tuples of the two input arrays. + +### Required Input Sources -## Example Pipelines +None -- this filter operates on any two generic **Attribute Arrays** that share the same primitive type, component dimensions, and number of tuples, regardless of how they were produced. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ComputeEuclideanDistMapFilter.md b/src/Plugins/SimplnxCore/docs/ComputeEuclideanDistMapFilter.md index c96875a13a..d5fb24a214 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeEuclideanDistMapFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeEuclideanDistMapFilter.md @@ -6,19 +6,29 @@ Statistics (Morphological) ## Description -This **Filter** calculates the distance of each **Cell** from the nearest **Feature** boundary, **triple line** and/or **quadruple point**. The following algorithm explains the process: +This **Filter** calculates, for every **Cell**, how far that **Cell** is from the nearest **Feature** boundary, **triple line**, and/or **quadruple point**. A **Feature** is a contiguous region of like-segmented cells (for example a grain). These three terms describe the interfaces between **Features**: -1. Find the **Feature** that owns each **Cell** and its six face-face neighbors of each **Cell** -2. For all **Cells** that have *at least 2* different neighbors, set their *GBEuclideanDistance* to *0*. For all **Cells** that have *at least 3* different neighbors, set their *TJEuclideanDistance* to *0*. For all **Cells** that have *at least 4* different neighbors, set their *QPEuclideanDistance* to *0* -3. For each of the three *EuclideanDistace* maps, iteratively "grow" out from the **Cells** identified to have a distance of *0* by the following sub-steps: +- A **Feature boundary** (abbreviated **GB**, grain boundary) is the interface where two different **Features** meet. +- A **triple line** (abbreviated **TJ**, triple junction) is where three different **Features** meet. +- A **quadruple point** (abbreviated **QP**) is where four different **Features** meet. -- Determine the **Cells** that neighbor a **Cell** of distance *0* in the current map. -- Assign a distance of *1* to those **Cells** and track the *0* **Cell** neighbor internally as their *nearest neighbor* -- Repeat previous two sub-steps, increasing the distances by *1* each iteration, until no **Cells** remain without a distance assigned. +The following algorithm explains the process: - *Note:* the distances calculated at this point are "city-block" distances and not "shortest distance" distances. The nearest neighbor information is used internally by the algorithm but is not saved as an output array. +1. Find the **Feature** that owns each **Cell** and the **Features** that own each of its six face-sharing neighbors. +2. For all **Cells** that have *at least 2* different neighboring **Features**, set their *GB* distance to *0*. For all **Cells** that have *at least 3*, set their *TJ* distance to *0*. For all **Cells** that have *at least 4*, set their *QP* distance to *0*. +3. For each of the three distance maps, iteratively "grow" outward from the **Cells** identified as distance *0* using the following sub-steps: -4. If the option *Calculate Manhattan Distance* is *false*, then the "city-block" distances are overwritten with the *Euclidean Distance* from the **Cell** to its internally tracked *nearest neighbor* **Cell** and stored in a *float* array instead of an *integer* array. + - Determine the **Cells** that neighbor a **Cell** of distance *0* in the current map. + - Assign a distance of *1* to those **Cells** and internally track the distance-*0* **Cell** as their *nearest neighbor*. + - Repeat the previous two sub-steps, increasing the distance by *1* each iteration, until every **Cell** has a distance assigned. + + *Note:* the distances calculated at this point are integer "city-block" (Manhattan) distances, expressed as a count of **Cells** (voxels), not shortest straight-line distances. The nearest-neighbor information is used internally and is not saved as an output array. + +4. If *Output arrays are Manhattan distance* is *false*, then the integer city-block distances are overwritten with the true straight-line (Euclidean) distance from each **Cell** to its internally tracked nearest-neighbor **Cell**. This Euclidean result is a physical distance expressed in the **Image Geometry** length units (for example microns) and is stored in a *float32* array instead of an *int32* array. + +### Required Input Sources + +- **Cell Feature Ids** -- the Feature that owns each Cell, produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeatureBoundsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeatureBoundsFilter.md index 09dd010efc..2d76baf40a 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeatureBoundsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeatureBoundsFilter.md @@ -8,7 +8,9 @@ Geometry **Warning**: *Potential Runtime Error* - It is expected that the max feature id plus one (`max_feature_id_value` + 1) is equal to or less than the number of tuples in the supplied feature Attribute Matrix. This cannot be checked in preflight and will terminate the pipeline if encountered. -This filter calculates the bounding boxes for each feature given Feature Ids and Geometry (refer to table below for supported geometry types and their corresponding feature id sizing). _**This filter does output `NaN`s for empty features**_, cases where a point can not be associated to a feature. The bounding boxes are defined and stored as two points in space, a lower and upper point. The optimal storage solution is use case defined, and as such there are two options provided `split` and `unified`. +This filter calculates the bounding boxes for each **Feature** given Feature Ids and Geometry (refer to table below for supported geometry types and their corresponding feature id sizing). A **Feature** is a contiguous region of cells (voxels, vertices, edges, or faces) that share the same Feature Id; a **Cell** is the smallest addressable element of the geometry. _**This filter does output `NaN`s for empty features**_, cases where a point can not be associated to a feature. The bounding boxes are defined and stored as two points in space, a lower and upper point. The optimal storage solution is use case defined, and as such there are two options provided `split` and `unified`. + +The bounding box values are stored in **physical coordinates** (the same length units as the geometry's origin and spacing), not cell/voxel indices. For an **Image Geometry** each coordinate is computed as `origin + index * spacing`; for node-based geometries (Vertex, Edge, Triangle, Quad) the vertex coordinates are used directly. ### Output Array(s) Type @@ -19,9 +21,9 @@ The *Output Array(s) Type* parameter controls how the bounding box data is store | Geometry Type | Expected Feature ID Length| |---------------|---------------------------| -| Image | Equal to Image Dimesions; typically equivalent to the `Cell Data` Attribute Matrix | +| Image | Equal to the Image Dimensions; typically equivalent to the `Cell Data` Attribute Matrix | | Vertex | Equal to the Number of Vertices/Points; typically equivalent to the `Vertex Data` Attribute Matrix | -| Edge | Equal to the Number of Edges; ; typically equivalent to the `Edge Data` Attribute Matrix | +| Edge | Equal to the Number of Edges; typically equivalent to the `Edge Data` Attribute Matrix | | Triangle | Equal to the Number of Triangles/Faces; typically equivalent to the `Face Data` Attribute Matrix | | Quad | Equal to the Number of Quads/Faces; typically equivalent to the `Face Data` Attribute Matrix | @@ -86,6 +88,10 @@ The edges for each bounding box are 12 in number and constructed in following or Since edges are the cell level data in edge geometries, the feature ids map to the edges. This means that the feature ids array will always contain 11 more consecutive instances of the same feature from when it first appears (12 total). To know the number of features in the edge geom, just divide the number of edges by 12. +### Required Input Sources + +This filter requires a **Cell Feature Ids** array, typically produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or one of the misorientation-based segmentation filters in the OrientationAnalysis plugin. The selected **Feature Data Attribute Matrix** is where the output bounds arrays are created. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeatureClusteringFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeatureClusteringFilter.md index 018999d1aa..63a980551f 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeatureClusteringFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeatureClusteringFilter.md @@ -6,15 +6,26 @@ Statistics (Morphological) ## Description -This Filter determines the radial distribution function (RDF), as a histogram, of a given set of **Features**. Currently, the **Features** need to be of the same **Ensemble** (specified by the user), and the resulting RDF is stored as **Ensemble** data. This Filter also returns the clustering list (the list of all the inter-**Feature** distances) and the minimum and maximum separation distances. The algorithm proceeds as follows: +This **Filter** computes the **radial distribution function (RDF)** of a set of **Features**. A **Feature** is a contiguous region of like-segmented cells (for example a grain or particle). An **RDF** is a histogram that describes how the **Features** are spatially distributed relative to each other: for each distance bin, it counts how many other **Feature** centroids lie at that separation distance, then normalizes that count against the count expected if the same number of **Features** were scattered randomly in the same volume. Values above 1.0 at a given distance indicate the **Features** are more likely to be found at that separation than random (clustering or ordering); values below 1.0 indicate they are less likely (exclusion). Use this **Filter** to detect and quantify clustering, ordering, or repulsion in a population of **Features**. -1. Find the Euclidean distance from the current **Feature** centroid to all other **Feature** centroids of the same specified phase -2. Put all caclulated distances in a clustering list -3. Repeat 1-2 for all **Features** -4. Sort the data into the specified number of bins, all equally sized in distance from the minimum distance to the maximum distance between **Features**. For example, if the user chooses 10 bins, and the minimum distance between **Features** is 10 units and the maximum distance is 80 units, each bin will be 8 units -5. Normalize the RDF by the probability of finding the **Features** if distributed randomly in the given box +An **Ensemble** is a group of **Features** that share a common phase (a distinct material or crystal structure). This **Filter** operates on a single **Ensemble** at a time, specified by the *Phase Index* parameter, and the resulting **RDF** is stored as **Ensemble** data. -*Note:* Because the algorithm iterates over all the **Features**, each distance will be double counted. For example, the distance from **Feature** 1 to **Feature** 2 will be counted along with the distance from **Feature** 2 to **Feature** 1, which will be identical. +All distances in this **Filter** are physical lengths expressed in the same length units as the **Image Geometry** spacing (for example microns). The algorithm proceeds as follows: + +1. Find the straight-line (Euclidean) distance from the current **Feature** centroid to every other **Feature** centroid of the selected phase. +2. Put all calculated distances in a clustering list. +3. Repeat steps 1-2 for all **Features**. +4. Sort the distances into the specified number of bins, all equally sized in distance from the minimum separation to the maximum separation. For example, if the user chooses 10 bins, the minimum separation is 10 microns, and the maximum separation is 80 microns, each bin spans 7 microns. +5. Normalize the **RDF** by the probability of finding the **Features** at that distance if they were distributed randomly in the bounding box. + +The **Filter** also outputs the clustering list (every inter-**Feature** distance) and the minimum and maximum separation distances (both in physical length units). + +*Note:* Because the algorithm iterates over all **Features**, each distance is double-counted. For example, the distance from **Feature** 1 to **Feature** 2 is counted along with the identical distance from **Feature** 2 to **Feature** 1. + +### Required Input Sources + +- **Centroids** -- the X, Y, Z coordinates of each Feature's center of mass, produced by [Compute Feature Centroids](ComputeFeatureCentroidsFilter.md). +- **Phases** -- the phase (Ensemble) that each Feature belongs to, produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeatureNeighborsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeatureNeighborsFilter.md index fd976848ab..5cfde8a531 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeatureNeighborsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeatureNeighborsFilter.md @@ -6,14 +6,33 @@ Statistics (Morphological) ## Description -This **Filter** determines, for each **Feature**, the number of other **Features** that are in contact with it. The algorithm for determining the number of "contiguous" neighbors of each **Feature** is as follows: +This **Filter** determines, for each **Feature**, which other **Features** it is in direct contact with and how much boundary they share. The result is a set of feature-level arrays that many downstream filters depend on -- neighbor misorientation statistics, GBCD, twin merging, boundary strength analysis, and more. -1. Identify the **Feature** to which a **Cell** belongs -2. Identify the **Features** to which each of the current **Cell**'s six (6) face-face neighboring **Cells** (front, back, left, right, up, down) belong -3. If a neighboring **Cell** belongs to a different **Feature** than the current **Cell**, then that **Feature** (owner of the neighboring **Cell**) is added to the list of contiguous neighbors of the **Feature** that owns the current **Cell** -4. Repeat 1-3 for all **Cells** +### How This Filter Works -While performing the above steps, the number of neighboring **Cells** with a different **Feature** owner than a given **Cell** is stored, which identifies whether a **Cell** lies on the surface/edge/corner of a **Feature** (i.e. the **Feature** boundary). Additionally, the surface area shared between each set of contiguous **Features** is calculated by tracking the number of times two neighboring **Cells** correspond to a contiguous **Feature** pair. The **Filter** also notes which **Features** touch the outer surface of the sample (this is obtained for "free" while performing the above algorithm). The **Filter** gives the user the option whether or not they want to store this additional information. +The filter walks every cell in the input **Image Geometry** and compares each cell's *Feature Id* to the *Feature Ids* of its six face-sharing neighbors (front, back, left, right, up, down): + +1. Identify the **Feature** the current cell belongs to. +2. For each of the cell's six face-neighbors, check whether the neighbor cell belongs to a different feature. +3. If so, record that neighbor feature in the current feature's *contiguous neighbor* list and increment the count of shared cell-faces between the two features. +4. While iterating, the filter also tracks which cells lie on a feature boundary (any cell with at least one differently-labeled neighbor) and which features touch the outer geometry boundary (any cell whose neighbor is outside the volume). + +### What This Filter Produces + +The main feature-level outputs are: + +- **Neighbor List** -- for each feature, the list of *Feature Ids* of the features it touches. +- **Number of Neighbors** -- for each feature, the integer count of its contiguous neighbors. Equivalent to the length of each *Neighbor List* entry. +- **Shared Surface Area List** -- for each pair of neighboring features, the number of cell-faces they share. This is in **cell-face units** (a dimensionless count), not physical area. To convert to physical area, multiply by the area of one cell face (which depends on the cell spacing and the orientation of the shared face). + +Two optional outputs can also be stored: + +- **Boundary Cells** (enable *Store Boundary Cells Array*) -- a cell-level array marking which cells sit on any feature boundary. Useful for visualization and for flagging the cells that contribute to grain-boundary statistics. +- **Surface Features** (enable *Store Surface Features Array*) -- a feature-level boolean marking which features touch the outer volume bounds. Downstream statistical filters often exclude surface features from distributions because they are biased by sample truncation (see [Compute Biased Features](ComputeBiasedFeaturesFilter.md)). + +### 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). This filter handles Image Geometries of all dimensions (0D/1D/2D/3D). Thus, it is up to the user to ensure spacing is set inline with intended behavior, specifically for Shared Surface Area List calculation. For more details see the Image Geometry section of the Geometry documentation (currently in the python docs). @@ -26,7 +45,6 @@ This filter handles Image Geometries of all dimensions (0D/1D/2D/3D). Thus, it i + (02) Single Hexagonal Phase Equiaxed + (03) Single Cubic Phase Rolled + (05) Composite - + (01) Single Cubic Phase Equiaxed + (04) Two Phase Cubic Hexagonal Particles Equiaxed + (06) SmallIN100 Synthetic diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesBinaryFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesBinaryFilter.md index 586ac80ffd..b47c738721 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesBinaryFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesBinaryFilter.md @@ -6,11 +6,15 @@ Generic (Misc) ## Description -This **Filter** assigns an **Ensemble** Id number to binary data. The *true* **Cells** will be **Ensemble** 1, and *false* **Cells** will be **Ensemble** 0. This **Filter** is generally useful when the **Cell Ensembles** were not known ahead of time. For example, if an image is segmented into precipitates and non-precipitates, this **Filter** will assign the precipitates to **Ensemble** 1, and the non-precipitates to **Ensemble** 0. +This **Filter** assigns a binary **Ensemble** Id number to each **Cell** based on a boolean (true/false) mask. A **Cell** is a single voxel of an **Image Geometry**, and an **Ensemble** is a group of **Cells** that share a common phase or classification. The input is a single-component boolean mask array; the output is a single-component **Ensemble** array in which every *true* **Cell** is assigned **Ensemble** 1 and every *false* **Cell** is assigned **Ensemble** 0. -% Auto generated parameter table will be inserted here +This **Filter** is generally useful any time data has already been reduced to a two-class (binary) distinction and you need an integer **Ensemble** label for downstream processing — for example separating "selected" from "unselected", "inside" from "outside", or any pass/fail criterion. A common materials-science example is an image segmented into precipitates and non-precipitates: the precipitates (mask *true*) are assigned to **Ensemble** 1 and the non-precipitates (mask *false*) to **Ensemble** 0. + +### Required Input Sources -## Example Pipelines +- **Mask** -- the per-**Cell** boolean mask array, typically produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesFilter.md index 10d0166308..b4601ee91c 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeaturePhasesFilter.md @@ -6,7 +6,14 @@ Generic (Misc) ## Description -This **Filter** determines the **Ensemble** of each **Feature** by querying the **Ensemble** of the **Elements** that belong to the **Feature**. Note that it is assumed that all **Elements** belonging to a **Feature** are of the same **Feature**, and thus any **Element** can be used to determine the **Ensemble** of the **Feature** that owns that **Element**. +This **Filter** determines the **Ensemble** (phase) of each **Feature** by querying the **Ensemble** of the **Elements** that belong to the **Feature**. A **Feature** is a connected region of **Elements** sharing the same **Feature Id**; an **Element** is a single member of a geometry (for an **Image Geometry** this is a **Cell**, i.e. a voxel); and an **Ensemble** is a group of **Features** that share a common phase. Note that it is assumed that all **Elements** belonging to a **Feature** are of the same phase, and thus any **Element** can be used to determine the **Ensemble** of the **Feature** that owns that **Element**. + +The output is a single-component, per-**Feature** phase array: tuple *i* holds the **Ensemble** (phase) Id of **Feature** *i*. + +### Required Input Sources + +- **Cell Feature Ids** -- the per-**Element** **Feature** label array, typically produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or another segmentation filter. +- **Cell Phases** -- the per-**Element** phase array, typically read from EBSD data via [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), [Read CTF Data](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read ANG Data](../OrientationAnalysis/ReadAngDataFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeatureRectFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeatureRectFilter.md index f023cd356c..81adf9338f 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeatureRectFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeatureRectFilter.md @@ -6,7 +6,9 @@ Reconstruction (Reconstruction) ## Description -This **Filter** computes the XYZ minimum and maximum coordinates for each **Feature** in a segmentation. This data can be important for finding the smallest encompassing volume. This values are given in **Pixel** coordinates. +This **Filter** computes the XYZ minimum and maximum coordinates for each **Feature** in a segmentation. A **Feature** is a contiguous group of **Cells** (voxels) that share the same Feature Id; a **Cell** is a single voxel. This data can be important for finding the smallest encompassing volume. These values are given in **Pixel** coordinates (zero-based voxel indices), not physical length units. + +If you instead need the bounding box corners in physical coordinates, see [Compute Feature Bounding Boxes](ComputeFeatureBoundsFilter.md). | | 0 | 1 | 2 | 3 | 4 | |-------|---|---|---|---|---| @@ -26,6 +28,10 @@ If the example matrix above which represents a single feature where the feature Y Max = 3 Z Max = 0 +### Required Input Sources + +This filter requires a **Cell Feature Ids** array, typically produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or one of the misorientation-based segmentation filters in the OrientationAnalysis plugin. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeFeatureSizesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeFeatureSizesFilter.md index f0eb4e4b54..4b8cb364d0 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeFeatureSizesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeFeatureSizesFilter.md @@ -12,6 +12,8 @@ This **Filter** calculates the sizes, volumes/areas, and equivalent diameters of To do so, the **Filter** simply iterates through all **Elements** querying for the **Feature** that owns them and keeping a tally for each **Feature**. The tally is then stored as *NumElements* and the *Volume* and *EquivalentDiameter* are also calculated (and stored) by knowing the volume of each **Element**. +![Fig. 1: The Equivalent (Spherical) Diameter of a feature is the diameter of the sphere whose volume equals the feature's volume (number of cells × voxel volume).](Images/ComputeFeatureSizes_EquivalentDiameter.png) + Note here that **Image Geometry** will always be faster than its equivalent **Rectilinear Grid Geometry** because we leverage the uniformity of voxel sizes to perform volume/area calculations at the feature level rather than the cell level. During the computation of the **Feature** sizes, the size of each individual **Element** is computed and stored in the corresponding **Geometry**. By default, these sizes are deleted after executing the **Filter** to save memory. If you wish to store the **Element** sizes, select the *Generate Missing Element Sizes* option. The sizes will be stored within the **Geometry** definition itself, not as a separate **Attribute Array**. @@ -25,6 +27,10 @@ it will be turned into a 2D calculation instead. This means **Areas instead of V To illustrate why this is think about an image geometry with the dimensions of `1x1x5 (XYZ)`. There is no way to tell whether a `Z * X` or `Z * Y` scaling would be appropriate for the area calculation, given the current information accessible in the algorithm. +### Required Input Sources + +- **Feature Ids** -- a per-**Cell** integer label array produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeGroupingDensityFilter.md b/src/Plugins/SimplnxCore/docs/ComputeGroupingDensityFilter.md index 4a1d1bc84b..629139e952 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeGroupingDensityFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeGroupingDensityFilter.md @@ -36,7 +36,7 @@ The **Feature Volumes** and **Parent Volumes** are typically expressed as a coun #### Use Non-Contiguous Neighbors -When enabled, the filter also queries the **Non-Contiguous Neighbor List** for each child **Feature** in addition to the standard **Contiguous Neighbor List**. This expands the set of checked **Features** to include neighbors that are nearby but do not share a direct face/edge/vertex with the child **Feature**. Enable this option if non-contiguous neighbors were used during the original grouping step. Typically the [Compute Feature Neighborhoods](ComputeNeighborhoodsFilter.md) filter is used to generate the **Non-Contiguous Neighbor List**. The *Multiples of Average Diameter* parameter on that filter has a large effect on the final **Grouping Density** value that is computed. +When enabled, the filter also queries the **Non-Contiguous Neighbor List** for each child **Feature** in addition to the standard **Contiguous Neighbor List**. This expands the set of checked **Features** to include neighbors that are nearby but do not share a direct face/edge/vertex with the child **Feature**. Enable this option if non-contiguous neighbors were used during the original grouping step. Typically the [Compute Feature Neighborhoods](ComputeNeighborhoodsFilter.md) filter is used to generate the non-contiguous neighbor lists. That filter's *Multiples of Average Diameter* parameter can have a large effect on the final Grouping Density value that is computed. #### Find Checked Features @@ -90,6 +90,12 @@ Note that both densities are less than 1.0 because each parent's children have n | Non-Contiguous Neighbor List | (optional, only when "Use Non-Contiguous Neighbors" is enabled)* -- produced by [Compute Feature Neighborhoods](ComputeNeighborhoodsFilter.md). See the "Use Non-Contiguous Neighbors" parameter guidance above for notes on how the upstream *Multiples of Average Diameter* parameter affects results.| +### Required Input Sources + +- **Parent IDs** -- produced by a hierarchical grouping/merge filter (for example a twin- or parent-grain merge step). +- **Contiguous Neighbor List** (and optionally the **Non-Contiguous Neighbor List**) -- produced by [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) / [Compute Feature Neighborhoods](ComputeNeighborhoodsFilter.md). +- **Feature Volumes** -- produced by [Compute Feature Sizes](ComputeFeatureSizesFilter.md). + % Auto generated parameter table will be inserted here ## References diff --git a/src/Plugins/SimplnxCore/docs/ComputeKMeansFilter.md b/src/Plugins/SimplnxCore/docs/ComputeKMeansFilter.md index 9f4924be10..b9beaf1f90 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeKMeansFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeKMeansFilter.md @@ -6,9 +6,11 @@ DREAM3D Review (Clustering) ## Description -***Warning:* The randomnes in this filter is not currently consistent between operating systems even if the same seed is used. Specifically between Unix and Windows. This does not affect the results, but the IDs will not correspond. For example if the Cluster Identifier at index one on Linux is 1 it could be 2 on Windows, the overarching clusters will be the same, but their IDs will be different.** +***Warning:* The randomness in this filter is not currently consistent between operating systems even if the same seed is used. Specifically between Unix and Windows. This does not affect the results, but the IDs will not correspond. For example if the Cluster Identifier at index one on Linux is 1 it could be 2 on Windows, the overarching clusters will be the same, but their IDs will be different.** -This **Filter** applies the k means algorithm to an **Attribute Array**. K means is a *clustering algorithm* that assigns to each point of the **Attribute Array** a *cluster Id*. The user must specify the number of clusters in which to partition the array. Specifically, a k means partitioning is a *Voronoi tesselation*; an optimal solution to the k means problem is such that each point in the data set is associated with the cluster that has the closest mean. This partitioning is the one that minimizes the within cluster variance (i.e., minimizes the within cluster sum of squares differences). The user may select from several distance metrics: *Euclidean*, *Squared Euclidean*, *Manhattan*, *Cosine*, *Pearson*, and *Squared Pearson*. +This **Filter** applies the k means algorithm to an **Attribute Array**. K means is a *clustering algorithm* that assigns each point (each tuple) of the **Attribute Array** to a *cluster Id*. A **cluster** is a group of data points that are more similar to each other than to points in other groups. The user must specify the number of clusters (a dimensionless count, *k*) in which to partition the array. + +Each cluster is summarized by its **centroid**, which is the arithmetic mean (the average position) of all the points assigned to that cluster. A k means partitioning is a *Voronoi tessellation*: every point is assigned to the cluster whose centroid is closest to it, so the data space is carved into regions where each region contains all the points nearer to one centroid than to any other. An optimal solution to the k means problem is one in which each point is associated with the cluster that has the closest mean. This partitioning minimizes the **within-cluster variance**, that is, the sum over all clusters of the squared distances from each point to its cluster centroid; minimizing it makes the points within each cluster as tightly grouped as possible. The user may select from several distance metrics: *Euclidean*, *Squared Euclidean*, *Manhattan*, *Cosine*, *Pearson*, and *Squared Pearson*. ### Distance Metric @@ -27,13 +29,13 @@ Optimal solutions to the k means partitioning problem are computationally diffic 2. Until convergence, repeat the following steps: - Associate each point with the closest mean, where "closest" is determined by the selected distance metric -- Recompute the means based on the new tesselation +- Recompute the means based on the new tessellation Convergence is defined as when the computed means change very little (precisely, when the differences are within machine epsilon). Since Lloyd's algorithm is iterative, it only serves as an approximation, and may result in different classifications on each execution with the same input data. The user may opt to use a mask to ignore certain points; where the mask is *false*, the points will be placed in cluster 0. Note: In SIMPLNX there is no explicit positional subtyping for Attribute Matrix, so the next section should be treated as a high-level understanding of what is being created. Naming the Attribute Matrix to include the type listed on the respective line in the 'Attribute Matrix Created' column is encouraged to help with readability and comprehension. -A clustering algorithm can be considered a kind of segmentation; this implementation of k means does not rely on the **Geometry** on which the data lie, only the *topology* of the space that the array itself forms. Therefore, this **Filter** has the effect of creating either **Features** or **Ensembles** depending on the kind of array passed to it for clustering. If an **Element** array (e.g., voxel-level **Cell** data) is passed to the **Filter**, then **Features** are created (in the previous example, a **Cell Feature Attribute Matrix** will be created). If a **Feature** array is passed to the **Filter**, then an Ensemble Attribute Matrix** is created. The following table shows what type of **Attribute Matrix** is created based on what sort of array is used for clustering: +A clustering algorithm can be considered a kind of segmentation; this implementation of k means does not rely on the **Geometry** on which the data lie, only on the arrangement of the values within the array itself (the *topology* of the space that the array forms). Therefore, this **Filter** has the effect of creating either **Features** or **Ensembles** depending on the kind of array passed to it for clustering. If an **Element** array (e.g., voxel-level **Cell** data) is passed to the **Filter**, then **Features** are created (in the previous example, a **Cell Feature Attribute Matrix** will be created). If a **Feature** array is passed to the **Filter**, then an **Ensemble Attribute Matrix** is created. The following table shows what type of **Attribute Matrix** is created based on what sort of array is used for clustering: | Attribute Matrix Source | Attribute Matrix Created | |------------------|--------------------| @@ -51,7 +53,17 @@ A clustering algorithm can be considered a kind of segmentation; this implementa | Face Ensemble | Face Ensemble | | Cell Ensemble | Cell Ensemble| -This **Filter** will store the means for the final clusters within the created **Attribute Matrix**. +The filter creates a *cluster Ids* array (one dimensionless integer cluster label per input point) alongside the input array, and stores the final cluster means (one mean vector per cluster, in the units of the input array) within the created **Attribute Matrix**. + +### Related Filters + +- [Compute K Medoids](ComputeKMedoidsFilter.md) uses representative data points (medoids) instead of means as the cluster centers. +- [DBSCAN](DBSCANFilter.md) is a density-based clustering algorithm that does not require the number of clusters to be specified in advance. +- [Silhouette](SilhouetteFilter.md) evaluates the quality of a clustering produced by this filter. + +### Required Input Sources + +- **Clustered Attribute Array** -- any **Attribute Array** (cell-level, feature-level, or generic) whose tuples are to be partitioned into clusters. This is typically an output of an earlier computation or import step. % Auto generated parameter table will be inserted here @@ -63,7 +75,7 @@ This **Filter** will store the means for the final clusters within the created * ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeKMedoidsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeKMedoidsFilter.md index 2f3f4f931c..c7a6c8862e 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeKMedoidsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeKMedoidsFilter.md @@ -6,9 +6,9 @@ DREAM3D Review (Clustering) ## Description -***Warning:* The randomnes in this filter is not currently consistent between operating systems even if the same seed is used. Specifically between Unix and Windows. This does not affect the results, but the IDs will not correspond. For example if the Cluster Identifier at index one on Linux is 1 it could be 2 on Windows, the overarching clusters will be the same, but their IDs will be different.** +***Warning:* The randomness in this filter is not currently consistent between operating systems even if the same seed is used. Specifically between Unix and Windows. This does not affect the results, but the IDs will not correspond. For example if the Cluster Identifier at index one on Linux is 1 it could be 2 on Windows, the overarching clusters will be the same, but their IDs will be different.** -This **Filter** applies the k medoids algorithm to an **Attribute Array**. K medoids is a *clustering algorithm* that assigns to each point of the **Attribute Array** a *cluster Id*. The user must specify the number of clusters in which to partition the array. Specifically, a k medoids partitioning is such that each point in the data set is associated with the cluster that minimizes the sum of the pair-wise distances between the data points and their associated cluster centers (medoids). This approach is analogous to k means, but uses actual data points (the medoids) as the cluster exemplars instead of the means. Medoids in this context refer to the data point in each cluster that is most like all other data points, i.e., that data point whose average distance to all other data points in the cluster is smallest. Unlike k means, since pair-wise distances are minimized instead of variance, any arbirtary concept of "distance" may be used; this **Filter** allows for the selection of a variety of distance metrics. +This **Filter** applies the k medoids algorithm to an **Attribute Array**. K medoids is a *clustering algorithm* that assigns each point (each tuple) of the **Attribute Array** to a *cluster Id*. A **cluster** is a group of data points that are more similar to each other than to points in other groups. The user must specify the number of clusters (a dimensionless count, *k*) in which to partition the array. Specifically, a k medoids partitioning is such that each point in the data set is associated with the cluster that minimizes the sum of the pair-wise distances between the data points and their associated cluster centers (medoids). This approach is analogous to k means, but uses actual data points (the medoids) as the cluster exemplars instead of the means. Medoids in this context refer to the data point in each cluster that is most like all other data points, i.e., that data point whose average distance to all other data points in the cluster is smallest. Unlike k means, since pair-wise distances are minimized instead of variance, any arbitrary concept of "distance" may be used; this **Filter** allows for the selection of a variety of distance metrics. ### Distance Metric @@ -21,7 +21,7 @@ The *Distance Metric* parameter determines how distances between data points are - **Pearson [4]**: One minus the Pearson correlation coefficient. Measures the linear correlation between two points, normalized by their standard deviations. - **Squared Pearson [5]**: The square of the Pearson distance metric. -This **Filter** uses the *Voronoi iteration* algorithm to produce the clustering. The algorithm is iterative and proceeds as follows: +This **Filter** uses the *Voronoi iteration* algorithm to produce the clustering. A **Voronoi** partitioning assigns every point to the cluster whose center (here, the medoid) is closest, carving the data space into regions where each region holds all the points nearer to one medoid than to any other. The algorithm is iterative and proceeds as follows: 1. Choose k points at random to serve as the initial cluster medoids 2. Associate each point to the closest medoid @@ -34,7 +34,7 @@ Convergence is defined as when the medoids no longer change position. Since the Note: In SIMPLNX there is no explicit positional subtyping for Attribute Matrix, so the next section should be treated as a high-level understanding of what is being created. Naming the Attribute Matrix to include the type listed on the respective line in the 'Attribute Matrix Created' column is encouraged to help with readability and comprehension. -A clustering algorithm can be considered a kind of segmentation; this implementation of k medoids does not rely on the **Geometry** on which the data lie, only the *topology* of the space that the array itself forms. Therefore, this **Filter** has the effect of creating either **Features** or **Ensembles** depending on the kind of array passed to it for clustering. If an **Element** array (e.g., voxel-level **Cell** data) is passed to the **Filter**, then **Features** are created (in the previous example, a **Cell Feature Attribute Matrix** will be created). If a **Feature** array is passed to the **Filter**, then an Ensemble Attribute Matrix** is created. The following table shows what type of **Attribute Matrix** is created based on what sort of array is used for clustering: +A clustering algorithm can be considered a kind of segmentation; this implementation of k medoids does not rely on the **Geometry** on which the data lie, only on the arrangement of the values within the array itself (the *topology* of the space that the array forms). Therefore, this **Filter** has the effect of creating either **Features** or **Ensembles** depending on the kind of array passed to it for clustering. If an **Element** array (e.g., voxel-level **Cell** data) is passed to the **Filter**, then **Features** are created (in the previous example, a **Cell Feature Attribute Matrix** will be created). If a **Feature** array is passed to the **Filter**, then an **Ensemble Attribute Matrix** is created. The following table shows what type of **Attribute Matrix** is created based on what sort of array is used for clustering: | Attribute Matrix Source | Attribute Matrix Created | |------------------|--------------------| @@ -52,7 +52,17 @@ A clustering algorithm can be considered a kind of segmentation; this implementa | Face Ensemble | Face Ensemble | | Cell Ensemble | Cell Ensemble| -This **Filter** will store the medoids for the final clusters within the created **Attribute Matrix**. +The filter creates a *cluster Ids* array (one dimensionless integer cluster label per input point) alongside the input array, and stores the final cluster medoids (one medoid vector per cluster, in the units of the input array) within the created **Attribute Matrix**. + +### Related Filters + +- [Compute K Means](ComputeKMeansFilter.md) uses the arithmetic mean of each cluster as its center instead of a representative data point. +- [DBSCAN](DBSCANFilter.md) is a density-based clustering algorithm that does not require the number of clusters to be specified in advance. +- [Silhouette](SilhouetteFilter.md) evaluates the quality of a clustering produced by this filter. + +### Required Input Sources + +- **Clustered Attribute Array** -- any **Attribute Array** (cell-level, feature-level, or generic) whose tuples are to be partitioned into clusters. This is typically an output of an earlier computation or import step. % Auto generated parameter table will be inserted here @@ -64,7 +74,7 @@ This **Filter** will store the medoids for the final clusters within the created ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeLargestCrossSectionsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeLargestCrossSectionsFilter.md index ffe68cfff2..cd33942a50 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeLargestCrossSectionsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeLargestCrossSectionsFilter.md @@ -6,7 +6,9 @@ Statistics (Morphological) ## Description -This **Filter** calculates the largest cross-sectional area on a user-defined plane for all **Features**. The **Filter** simply iterates through all **Cells** (on each section) asking for **Feature** that owns them. On each section, the count of **Cells** for each **Feature** is then converted to an area and stored as the *LargestCrossSection* if the area for the current section is larger than the existing *LargestCrossSection* for that **Feature**. +This **Filter** calculates the largest cross-sectional area on a user-defined plane for all **Features**. A **Feature** is a contiguous group of **Cells** (voxels) that share the same Feature Id; a **Cell** is a single voxel. The **Filter** simply iterates through all **Cells** (on each section) asking for the **Feature** that owns them. On each section, the count of **Cells** for each **Feature** is then converted to an area and stored as the *LargestCrossSection* if the area for the current section is larger than the existing *LargestCrossSection* for that **Feature**. + +The area is reported in **square physical units**, not a raw cell count. For each section the per-**Feature** **Cell** count is multiplied by the in-plane voxel area (the product of the two **Image Geometry** spacing values that lie in the chosen plane, e.g. `spacing-X * spacing-Y` for the XY plane). The output `LargestCrossSections` array is a single-component `float32` array created in the **Cell Feature Attribute Matrix**, holding the largest cross-sectional area found for each **Feature**. ### Plane of Interest @@ -16,6 +18,10 @@ The *Plane of Interest* parameter selects the plane along which cross-sections a - **XZ [1]**: Cross-sections are taken on planes perpendicular to the Y axis. Each Y slice is one cross-section. - **YZ [2]**: Cross-sections are taken on planes perpendicular to the X axis. Each X slice is one cross-section. +### Required Input Sources + +This filter requires a **Cell Feature Ids** array, typically produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or one of the misorientation-based segmentation filters in the OrientationAnalysis plugin. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeMomentInvariants2DFilter.md b/src/Plugins/SimplnxCore/docs/ComputeMomentInvariants2DFilter.md index 2782d328a6..6b7d675774 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeMomentInvariants2DFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeMomentInvariants2DFilter.md @@ -6,13 +6,24 @@ Statistics (Statistics) ## Description -This **Filter** computes the 2D Omega-1 and Omega 2 values from the *Central Moments* matrix and optionally will normalize the values to a unit circle and also optionally save the *Central Moments* matrix as a DataArray to the *Cell Feature Attribute Matrix*. Based off the paper by MacSleyne et. al [1], the algorithm will calculate the 2D central moments for each feature starting at *feature id = 1*. Because *feature id 0* is of special significance and typically is a matrix or background it is ignored in this filter. If any feature id has a Z Delta of > 1, the feature will be skipped. This algorithm works strictly in the XY plane and is meant to be applied to a 2D image. Using the research from the cited paper certain shapes can be detected using the Omega-1 and Omega-2 values. An example usage is finding elliptical shapes in an image: +This **Filter** computes the 2D **moment invariants** Omega-1 and Omega-2 for each **Feature** in a 2D image. A **Feature** is a contiguous region of like-segmented cells (for example a particle). **Moment invariants** are scalar shape descriptors derived from the *Central Moments* of a **Feature**: the **Filter** treats each **Feature** as a flat 2D shape, measures how its area is distributed about its own centroid, and condenses that distribution into two numbers that do not change when the shape is translated, rotated, or (after normalization) scaled. Omega-1 and Omega-2 are therefore dimensionless values that describe the *shape* of a **Feature**, independent of its position, orientation, or size. -See below figure from [1] that can help the user classify objects. +In practice these values measure how elongated or irregular a **Feature** is. A perfect circle gives the smallest possible Omega values; the more a **Feature** deviates toward an elongated ellipse or an irregular shape, the larger the Omega values become. By thresholding Omega-1 and Omega-2, you can classify **Features** by shape, for example separating round particles from elongated or irregular ones. -![Example appllication of filter to identify elliptical particales (red) which are differentiated from non-elliptical particals (purple)](Images/ComputeMomentInvariants_Fig1.png) +Based on the paper by MacSleyne et al. [1], the algorithm calculates the 2D central moments for each **Feature** starting at *feature id = 1*. Because *feature id 0* is of special significance and is typically a matrix or background, it is ignored. If any **Feature** has a Z extent (Z Delta) greater than 1 cell, that **Feature** is skipped. The algorithm works strictly in the XY plane and is meant to be applied to a 2D image. -![Example appllication of filter to identify elliptical particales (red) which are differentiated from non-elliptical particals (purple)](Images/ComputeMomentInvariants2D.png) +The **Filter** can optionally normalize the values to a unit circle (the *Normalize Moment Invariants* parameter) and can optionally save the full 3x3 *Central Moments* matrix as a Data Array in the *Feature Attribute Matrix*. + +The figures below, from [1], can help classify objects by their Omega values. An example usage is finding elliptical shapes (red) and differentiating them from non-elliptical shapes (purple): + +![Example application of the filter to identify elliptical particles (red), differentiated from non-elliptical particles (purple)](Images/ComputeMomentInvariants_Fig1.png) + +![Example application of the filter to identify elliptical particles (red), differentiated from non-elliptical particles (purple)](Images/ComputeMomentInvariants2D.png) + +### Required Input Sources + +- **Cell Feature Ids** -- the Feature that owns each Cell, produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). +- **Feature Rect** -- the min/max XY pixel coordinates (bounding corners) of each Feature, produced by [Compute Feature Corners](ComputeFeatureRectFilter.md). % Auto generated parameter table will be inserted here @@ -24,11 +35,10 @@ See below figure from [1] that can help the user classify objects. # Acknowledgements The authors would like to thank Dr. Marc De Graef from Carnegie Mellon University for enlightening discussions and a concrete implementation from which to start this filter. -## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeNeighborListStatisticsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeNeighborListStatisticsFilter.md index c05c009cc0..098209f9fa 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeNeighborListStatisticsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeNeighborListStatisticsFilter.md @@ -6,15 +6,27 @@ Statistics (Misc Filters) ## Description -This **Filter** computes the selected statistics for each list contained in a NeighborList container. Each of those statistics are reported back as new Attribute Arrays. The user selectable statistics are: - -+ Length of each list -+ Minimum value from each list -+ Maximum value from each list -+ Mean of each list -+ Median of each list -+ Standard Deviation of each list -+ Summation of each list +This **Filter** reduces a **NeighborList** -- a per-feature list of values, one entry per neighbor -- into per-feature scalar summary statistics. Each chosen statistic becomes its own output **Attribute Array** at the feature level. + +A typical use is summarizing per-feature neighbor misorientations: [Compute Feature Neighbor Misorientations](../OrientationAnalysis/ComputeFeatureNeighborMisorientationsFilter.md) produces a NeighborList containing the misorientation between a feature and each of its neighbors; this filter reduces that list to "average misorientation per feature" or "max neighbor misorientation per feature" so the result can be plotted or thresholded. + +### Available Statistics + +The user can independently enable any combination of: + +- **Length** -- the number of entries in the list (i.e., the number of neighbors). +- **Minimum** -- smallest value in the list. +- **Maximum** -- largest value in the list. +- **Mean** -- arithmetic mean of the list. +- **Median** -- median of the list. +- **Standard Deviation** -- sample standard deviation of the list. +- **Summation** -- sum of all values in the list. + +Output statistics inherit the units of the input list (e.g., degrees for a misorientation list, dimensionless count for a neighbor count list). + +### Required Input Sources + +- **Input NeighborList** -- a feature-level list-of-lists. Common producers include [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) (shared surface area), [Compute Feature Neighbor Misorientations](../OrientationAnalysis/ComputeFeatureNeighborMisorientationsFilter.md) (misorientation per neighbor), [Compute Feature Neighbor C-Axis Misalignments](../OrientationAnalysis/ComputeFeatureNeighborCAxisMisalignmentsFilter.md), or [Compute Slip Transmission Metrics](../OrientationAnalysis/ComputeSlipTransmissionMetricsFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeNeighborhoodsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeNeighborhoodsFilter.md index 59e660f25f..1d9f0a2c73 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeNeighborhoodsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeNeighborhoodsFilter.md @@ -34,11 +34,20 @@ The figure below shows a single target feature and how progressively larger mult ![Search sphere around a feature at 1x, 2x, and 3x its own diameter](Images/ComputeFeatureNeighborhoods_SearchSphere.png) -## Output Notes +### Multiplier -There are 2 outputs from this filter: -- The "Number of Neighbors" for each feature -- The list of "neighbor" features for each neighbor +The *Multiplier* parameter is **dimensionless** -- a multiple of the average ESD. Common values: + +- **1.0** -- search sphere is the same size as the average grain. Catches a feature's immediate neighbors and slightly beyond. +- **2.0-3.0** -- second-nearest-neighbor analysis. +- **5.0+** -- broader clustering / long-range arrangement studies. + +### Required Input Sources + +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md). +- **Feature Centroids** -- produced by [Compute Feature Centroids](ComputeFeatureCentroidsFilter.md). +- **Feature Equivalent Diameters** -- produced by [Compute Feature Sizes](ComputeFeatureSizesFilter.md). +- **Feature Phases** -- produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeNumFeaturesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeNumFeaturesFilter.md index aecdb6ab33..6cf8a38bfa 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeNumFeaturesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeNumFeaturesFilter.md @@ -6,7 +6,13 @@ Statistics (Morphological) ## Description -This **Filter** determines the number of **Features** in each **Ensemble** by summing the total number of rows in the feature attribute matrix belonging to each phase. +This **Filter** determines the number of **Features** in each **Ensemble** by counting the **Features** assigned to each **Ensemble**. An **Ensemble** is a group of **Features** that share common characteristics — most commonly a *phase* (a distinct material or crystallographic constituent in the sample). The filter reads the per-**Feature** phase array and tallies how many **Features** belong to each phase. + +The output is a single-component count array indexed by **Ensemble** (phase) Id: tuple *i* holds the number of **Features** belonging to **Ensemble** *i*. + +### Required Input Sources + +- **Feature Phases** -- the per-**Feature** phase (**Ensemble** Id) array, produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeSurfaceAreaToVolumeFilter.md b/src/Plugins/SimplnxCore/docs/ComputeSurfaceAreaToVolumeFilter.md index 52117bd1fb..efe9c63b12 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeSurfaceAreaToVolumeFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeSurfaceAreaToVolumeFilter.md @@ -6,9 +6,9 @@ Statistics (Morphological) ## Description -This **Filter** calculates the ratio of surface area to volume for each **Feature** in an **Image Geometry**. +This **Filter** calculates the ratio of surface area to volume for each **Feature** in an **Image Geometry**. A **Feature** is a connected region of **Cells** that share the same **Feature Id**. Because surface area has units of length squared and volume has units of length cubed, the resulting ratio has units of *1/length* (the reciprocal of the **Image Geometry** spacing units; for example, if the spacing is in micrometers the ratio is in 1/micrometers). -This filter also optionally calculate the [Sphericity](https://en.wikipedia.org/wiki/Sphericity) of each feature. +This filter also optionally calculates the [Sphericity](https://en.wikipedia.org/wiki/Sphericity) of each feature. Sphericity is a *dimensionless* (unitless) measure of how closely a **Feature**'s shape approaches that of a perfect sphere. ![Equation for Sphericity used in the filter](Images/Sphericity_Equation.png) @@ -17,15 +17,19 @@ This **Filter** determines whether a **Feature** touches an outer *Surface* of t + Any cell location is xmin, xmax, ymin, ymax, zmin or zmax + Any cell has **Feature ID = 0** as a neighbor. +### Required Input Sources + +- **Cell Feature Ids** -- the per-**Cell** **Feature** label array, typically produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md) or another segmentation filter. + ## Algorithm Details -- First, all the boundary **Cells** are found for each **Feature**. +- First, all the boundary **Cells** are found for each **Feature** (see also [Compute Boundary Cells (Image)](ComputeBoundaryCellsFilter.md)). - Next, the surface area for each face that is in contact with a different **Feature** is totalled as long as that neighboring *featureId* is > 0. - This number is divided by the volume of each **Feature**, calculated by taking the number of **Cells** of each **Feature** and multiplying by the volume of a **Cell**. ### WARNING - Aliasing -The surface area will be the surface area of the **Cells** in contact with the neighboring **Feature** and will be influenced by the aliasing of the structure. As a result, the surface area to volume will likely be over-estimated with respect to the *real* **Feature**. +The surface area will be the surface area of the **Cells** in contact with the neighboring **Feature** and will be influenced by the *aliasing* of the structure — the jagged, stair-stepped approximation of a smooth surface that results from representing it on a discrete voxel grid. As a result, the surface area to volume will likely be over-estimated with respect to the *real* **Feature**. ### WARNING - Skewed Results for features touching the surface diff --git a/src/Plugins/SimplnxCore/docs/ComputeSurfaceFeaturesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeSurfaceFeaturesFilter.md index 395152e694..985aa69f56 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeSurfaceFeaturesFilter.md +++ b/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 xmin, xmax, ymin, ymax, zmin or zmax -+ 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 xmin, xmax, ymin, ymax, zmin, or zmax. +- 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 diff --git a/src/Plugins/SimplnxCore/docs/ComputeTriangleAreasFilter.md b/src/Plugins/SimplnxCore/docs/ComputeTriangleAreasFilter.md index ced548ef84..d5c97ab7e4 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeTriangleAreasFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeTriangleAreasFilter.md @@ -6,11 +6,25 @@ Surface Meshing (Misc) ## Description -This **Filter** computes the area of each **Triangle** in a **Triangle Geometry** by calculating the following: +This filter computes the surface area of every **Triangle** in a **Triangle Geometry** (a surface mesh built from triangles) and stores the result as a per-triangle **Face Data** array. - 1/2*|AB||AC|sin(O) +### What This Measures and Why -where *O* is the angle between |AB| and |AC|. +Each triangle is defined by three corner **vertices** (nodes). The filter computes the area enclosed by those three vertices using + + Area = 1/2 * |AB| * |AC| * sin(O) + +where *AB* and *AC* are two edge vectors of the triangle and *O* is the angle between them. + +Per-triangle area is a basic mesh-quality and statistics input. It is used to weight other per-triangle quantities (for example, area-weighting triangle normals or curvature when computing feature-level averages) so that large triangles contribute proportionally more than small ones, and it can be summed to report the total surface area of a **Feature** or boundary. + +### Units + +The output area is reported in **squared geometry length units** (length^2). The value uses whatever length unit the **Triangle Geometry** vertices are stored in (for example, micrometers^2 if the mesh coordinates are in micrometers). + +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomCentroidsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomCentroidsFilter.md index 8928f755cb..b6918b20af 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomCentroidsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomCentroidsFilter.md @@ -6,21 +6,34 @@ Statistics (Morphological) ## Description -This **Filter** determines the centroids of each **Feature** in a **Triangle Geometry**. The centroids are determined -using the following algorithm: +This filter computes the centroid (the average position of the bounding nodes) of each **Feature** in a **Triangle Geometry** (a surface mesh built from triangles). -1. Query each triangle within the **Triangle Geometry** to determine its two owners -2. Add the 3 nodes of that triangle to the set of nodes bounding those two owners (*Note that a set will only allow each - node to be entered once for a given owner*) -3. For each **Feature**, find the average (x,y,z) coordinate from the set of nodes that bound it +In a surface mesh, each triangle carries a **Face Labels** value: a pair of **Feature** Ids naming the two features that meet at that triangle. These two features are the triangle's "owners". A **Feature** is the volume of material enclosed by the triangles that reference its Id. The corner points of each triangle are its **nodes** (also called vertices). -% Auto generated parameter table will be inserted here +The centroid of each feature is determined as follows: + +1. For each triangle, read its two owners from the **Face Labels** array. +2. Add the 3 nodes of that triangle to the set of nodes bounding each of those two owners. A set stores each node only once per owner, so shared nodes are not double-counted. +3. For each **Feature**, average the (x, y, z) coordinates of the set of nodes that bound it to obtain the centroid. + +### Boundary / Exterior Label + +A **Face Labels** value of -1 indicates the exterior of the sample (the triangle faces open space rather than another feature). Feature Id -1 is the exterior and is not a real feature; its accumulated "centroid" entry is therefore not physically meaningful and should be ignored. + +### Units -## Example Pipelines +Centroid coordinates are reported in the **geometry length units** of the **Triangle Geometry** vertices (for example, micrometers if the mesh coordinates are stored in micrometers). + +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** -- the per-triangle pair of **Feature** Ids, produced alongside the mesh by [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) or [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomVolumesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomVolumesFilter.md index 5085e66723..b3912c7ae7 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomVolumesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeTriangleGeomVolumesFilter.md @@ -6,25 +6,36 @@ Statistics (Morphological) ## Description -This **Filter** computes the enclosed volume of each **Feature** in a **Triangle Geometry**. The result is the volume of -each surface meshed **Feature**, or alternatively the volume of each unique polyhedron defined by the given _Face -Labels_ array. The volume of any generic polyhedron can be computed using the following algorithm: - -1. Triangulate each face of the polyhedron (in this case, each face is already a triangle within the **Triangle - Geometry**) -2. For each triangular face, ensure the normals are all consistent (this **Filter** uses the convention where normals - point inwards; note that the actual winding of the **Triangle Geometry** is not modified) -3. For each triangular face, create a tetrahedron where the fourth vertex is the origin -4. Compute the signed volume of each tetrahedron -5. Sum the signed tetrahedra volumes to obtain the volume of the enclosing polyhedron +This filter computes the enclosed volume of each **Feature** in a **Triangle Geometry** (a surface mesh built from triangles). The result is the volume of each surface-meshed **Feature**, equivalently the volume of each unique closed polyhedron defined by the **Face Labels** array. -% Auto generated parameter table will be inserted here +In a surface mesh, each triangle carries a **Face Labels** value: a pair of **Feature** Ids naming the two features on either side of that triangle. The set of triangles that reference a given **Feature** Id forms the closed shell of that feature. The **winding** of a triangle is the order in which its three corner vertices are listed; that order defines which way the triangle's surface normal points (inward vs. outward). + +The volume of any generic closed polyhedron is computed as follows: + +1. Triangulate each face of the polyhedron (here, each face is already a triangle in the **Triangle Geometry**). +2. Make the triangle normals consistent. This filter uses the convention where normals point inward. The actual winding stored in the **Triangle Geometry** is not modified. +3. For each triangular face, form a tetrahedron whose fourth vertex is the coordinate-system origin. +4. Compute the signed volume of each tetrahedron. +5. Sum the signed tetrahedra volumes to obtain the volume enclosed by the polyhedron. + +### Watertight Requirement + +This method only yields a correct value for a **watertight** (closed, gap-free) surface. The signed-tetrahedron sum relies on the feature's triangles forming a complete enclosing shell; if the surface has holes or is otherwise open, the computed volume is not meaningful. Surfaces produced by the standard surface-meshing filters are closed per feature and satisfy this requirement. -## Example Pipelines +### Units + +Volume is reported in **cubed geometry length units** (length^3), using whatever length unit the **Triangle Geometry** vertices are stored in (for example, micrometers^3 if the mesh coordinates are in micrometers). + +### Required Input Sources + +- **Triangle Geometry** -- a closed (watertight) surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** -- the per-triangle pair of **Feature** Ids, produced alongside the mesh by [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) or [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ComputeVectorColorsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeVectorColorsFilter.md index 1d036e9314..a20d3b26c9 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeVectorColorsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeVectorColorsFilter.md @@ -6,10 +6,16 @@ Generic (Coloring) ## Description -This **Filter** generates a color for each **Element** based on the vector assigned to that **Element** in the input vector data. The color scheme assigns a unique color to all points on the unit hemisphere using a HSV-like scheme. The color space is approximately represented by the following legend. +This filter generates an RGB color for each **Cell** based on the vector assigned to that **Cell** in the input vector data. The input is a 3-component (float32) vector **Cell** array, and the output is a 3-component unsigned 8-bit (uint8) RGB array with values in the range 0-255. Each input vector is normalized to unit length before its direction is mapped to a color, so only the *direction* of the vector affects the color; its magnitude is ignored. The color scheme assigns a unique color to every direction on the unit hemisphere using an HSV-like scheme. The color space is approximately represented by the following legend. ![Images/VectorColors](Images/VectorColors.png) +When *Apply to Good Voxels Only* is enabled, the supplied boolean or uint8 **Mask** array marks which **Cells** are valid; **Cells** flagged as bad are left black (RGB 0,0,0) instead of being colored. + +### Required Input Sources + +- **Vector Attribute Array** -- a 3-component float32 per-**Cell** vector array. This may come from any filter that produces a per-**Cell** vector field (for example, a dipole, gradient, or orientation-derived vector array). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ComputeVertexToTriangleDistancesFilter.md b/src/Plugins/SimplnxCore/docs/ComputeVertexToTriangleDistancesFilter.md index 8129b68d76..57788f5734 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeVertexToTriangleDistancesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeVertexToTriangleDistancesFilter.md @@ -6,7 +6,17 @@ Sampling (Spatial) ## Description -This **Filter** computes distances between points in a **Vertex Geoemtry** and triangles in a **Triangle Geoemtry**. Specifically, for each point in the **Vertex Geometry**, the Euclidean distance to the closest triangle in the **Triangle Geoemtry** is stored. This distance is *signed*: if the point lies on the side of the triangle to which the triangle normal points, then the distance is positive; otherwise, the distance is negative. Additionally, the ID the closest triangle is stored for each point. +This **Filter** computes distances between points in a **Vertex Geometry** and triangles in a **Triangle Geometry**. Specifically, for each point in the **Vertex Geometry**, the Euclidean distance to the closest triangle in the **Triangle Geometry** is stored. This distance is *signed*: if the point lies on the side of the triangle to which the triangle normal points, then the distance is positive; otherwise, the distance is negative. Additionally, the ID of the closest triangle is stored for each point. + +The computed distance is reported in the same length unit as the coordinates of the two input geometries (e.g., microns, millimeters); both geometries must share the same unit system for the result to be meaningful. + +The sign of each distance depends on the **Triangle Normals**. For the sign to be correct, the normals must be present and consistently oriented across the mesh (all pointing to the same "outside"). Inconsistent or flipped normals will produce sign errors even when the distance magnitude is correct. + +### Required Input Sources + +- **Vertex Geometry** -- the point cloud whose distances are measured. +- **Triangle Geometry** -- the surface mesh measured against, typically produced by a surface-meshing filter such as [Quick Surface Mesh](QuickSurfaceMeshFilter.md) or read from a CAD mesh via [Read STL File](ReadStlFileFilter.md). +- **Triangle Normals** -- per-face normals on the **Triangle Geometry**, produced by [Compute Triangle Normals](TriangleNormalFilter.md); required for correct distance signs. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ComputeVolumeFractionsFilter.md b/src/Plugins/SimplnxCore/docs/ComputeVolumeFractionsFilter.md index 919b4cb0bb..27b6a57297 100644 --- a/src/Plugins/SimplnxCore/docs/ComputeVolumeFractionsFilter.md +++ b/src/Plugins/SimplnxCore/docs/ComputeVolumeFractionsFilter.md @@ -6,11 +6,17 @@ Statistics (Morphological) ## Description -This **Filter** determines the volume fraction of each **Ensemble**. The **Filter** counts the number of **Cells** belonging to each **Ensemble** and stores the number fraction. +This filter determines the volume fraction of each **Ensemble**. An **Ensemble** is a grouping of **Features** that share a common characteristic, such as a crystallographic phase. The filter counts the number of **Cells** belonging to each **Ensemble** and divides by the total number of **Cells**. -% Auto generated parameter table will be inserted here +On an **Image Geometry** every **Cell** has the same volume, so this count fraction is identical to the true volume fraction: dividing each **Ensemble**'s **Cell** count by the total **Cell** count gives the same result as dividing each **Ensemble**'s summed **Cell** volume by the total volume. The output is therefore a per-**Ensemble**, dimensionless volume fraction in the range [0, 1], where all of the fractions sum to 1. + +The result is written to the *Volume Fractions* array in the selected **Ensemble Attribute Matrix**. + +### Required Input Sources -## Example Pipelines +- **Cell Phases** -- a per-**Cell** integer array specifying which **Ensemble** each **Cell** belongs to. This array is typically read directly from EBSD data; the related feature-level array is produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ConcatenateDataArraysFilter.md b/src/Plugins/SimplnxCore/docs/ConcatenateDataArraysFilter.md index edabd3f966..f509fd2b79 100644 --- a/src/Plugins/SimplnxCore/docs/ConcatenateDataArraysFilter.md +++ b/src/Plugins/SimplnxCore/docs/ConcatenateDataArraysFilter.md @@ -14,6 +14,12 @@ This filter is designed to handle arrays of matching array types and component d **NOTE:** If you are wanting to instead combine data arrays into a multi-component array, please see the [Combine Attribute Arrays](CombineAttributeArraysFilter.md) filter. +For example, given two 3-component float arrays of 5 and 7 tuples respectively, the output is a 3-component float array of 12 tuples whose first 5 tuples are the first input and last 7 tuples are the second input. + +### Required Input Sources + +- **Input Data Arrays** -- two or more arrays sharing the same primitive type and the same component dimensions. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ConditionalSetValueFilter.md b/src/Plugins/SimplnxCore/docs/ConditionalSetValueFilter.md index d7ecf3ce78..f2fc44f8a7 100644 --- a/src/Plugins/SimplnxCore/docs/ConditionalSetValueFilter.md +++ b/src/Plugins/SimplnxCore/docs/ConditionalSetValueFilter.md @@ -6,23 +6,42 @@ Core (Misc) ## Description -This **Filter** replaces values in a user specified **Attribute Array** with a user specified value a second boolean **Attribute Array** specifies, but only when **Use Conditional Mask** is *true*. For example, if the user entered a *Replace Value* of *5.5*, then for every occurence of *true* in the conditional boolean array, the selected **Attribute Array** would be changed to 5.5. If **Use Conditional Mask** is *false*, then **Value to Replace** will be searched for in the provided **Attribute Array** and all instances will be replaced. Below are the ranges for the values that can be entered for the different primitive types of arrays (for user reference). The selected **Attribute Array** must be a scalar array. - -### Primitive Data Types - -| Type | Size | Range | -|------------------|------|--------------------| -| Signed Integer | 8 bit |-128 to 127| -| Unsigned Integer | 8 bit |0 to 255| -| Signed Integer | 16 bit |-32,768 to 32,767| -| Unsigned Integer | 16 bit |0 to 65,535| -| Signed Integer | 32 bit |-2,147,483,648 to 2,147,483,647| -| Unsigned Integer | 32 bit |0 to 4,294,967,295| -| Signed Integer | 64 bit | 9,223,372,036,854,775,808 to 9,223,372,036,854,775,807| -| Unsigned Integer | 64 bit |0 to 18,446,744,073,709,551,615| -| Float | 32 bit | -3.4e+38 to -1.1e-38, 0.0, 1.1e-38 to 3.4e+38 (7 digits)| -| Double | 64 bit | -1.7e+308 to -2.2e-308, 0.0, 2.2e-308 to 1.7e+308 (15 digits)| -| Boolean | 8 bit |0 = false and any other value will be forced to 1 = true| +This **Filter** replaces selected values in a scalar **Attribute Array** with a user-specified value. The filter operates in one of two modes selected by the *Use Conditional Mask* parameter. + +### Mode 1 -- Conditional Mask (Use Conditional Mask = ON) + +A second boolean array (the *Conditional Mask*) of the same length picks which tuples to overwrite. Every tuple where the mask is *true* has its scalar value set to *Replace Value*; tuples where the mask is *false* are unchanged. + +Typical use case: replace cell values flagged by an upstream threshold (e.g., set all "bad" cells to 0). + +### Mode 2 -- Value Match (Use Conditional Mask = OFF) + +Every occurrence of *Value to Replace* in the target array is replaced with *Replace Value*. The Conditional Mask parameter is ignored. + +Typical use case: remap a specific sentinel value (e.g., turn every -1 into 0). + +### Numeric Type Compatibility + +The target array must be a **scalar** (single-component) array. *Replace Value* (and *Value to Replace* in Mode 2) are reinterpreted as the array's data type. The valid range for each primitive type: + +| Type | Size | Range | +|------|------|-------| +| Signed Integer | 8 bit | -128 to 127 | +| Unsigned Integer | 8 bit | 0 to 255 | +| Signed Integer | 16 bit | -32,768 to 32,767 | +| Unsigned Integer | 16 bit | 0 to 65,535 | +| Signed Integer | 32 bit | -2,147,483,648 to 2,147,483,647 | +| Unsigned Integer | 32 bit | 0 to 4,294,967,295 | +| Signed Integer | 64 bit | -9.2e18 to 9.2e18 | +| Unsigned Integer | 64 bit | 0 to 1.8e19 | +| Float | 32 bit | ±1.1e-38 to ±3.4e+38 (7 digits) | +| Double | 64 bit | ±2.2e-308 to ±1.7e+308 (15 digits) | +| Boolean | 8 bit | 0 = false, non-zero = true | + +### Required Input Sources + +- **Target Array** -- the scalar cell-level (or other tuple-level) array whose values will be overwritten. +- **Conditional Mask** (only when *Use Conditional Mask* is enabled) -- a boolean array with the same number of tuples; typically produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ConvertColorToGrayScaleFilter.md b/src/Plugins/SimplnxCore/docs/ConvertColorToGrayScaleFilter.md index 6f9a905448..1b218367df 100644 --- a/src/Plugins/SimplnxCore/docs/ConvertColorToGrayScaleFilter.md +++ b/src/Plugins/SimplnxCore/docs/ConvertColorToGrayScaleFilter.md @@ -6,25 +6,34 @@ Processing (Image) ## Description -This **Filter** allows the user to select a *flattening* method for turning an array of RGB or RGBa values into grayscale values. +This **Filter** converts one or more color image arrays (3-component RGB or 4-component RGBA, uint8) into single-component grayscale image arrays using one of four standard flattening algorithms. Use this filter as a preprocessing step before any image-processing filter that expects single-channel intensity data. ### Conversion Algorithm -The *Conversion Algorithm* parameter provides the following choices: +The *Conversion Algorithm* parameter selects how the three (or four) color channels are combined into a single value: -- **Luminosity [0]**: A weighted average of RGB channels that accounts for human perception (more sensitive to green). Uses the BT709 formula by default: Red: 0.2125, Green: 0.7154, Blue: 0.0721. The user can set custom weightings. -- **Average [1]**: Computes a simple arithmetic average of R, G, and B channel values: (R + G + B) / 3. -- **Lightness [2]**: Averages the maximum and minimum channel values: (max(R, G, B) + min(R, G, B)) / 2. -- **SingleChannel [3]**: The user selects a specific R, G, or B channel to use directly as the grayscale values. +- **Luminosity [0]**: weighted average accounting for human perception (more sensitive to green). Default weights are the BT.709 standard: R=0.2125, G=0.7154, B=0.0721. The user may supply custom weights. +- **Average [1]**: simple arithmetic mean of the three channels: (R + G + B) / 3. +- **Lightness [2]**: average of the maximum and minimum channel values: (max(R, G, B) + min(R, G, B)) / 2. +- **SingleChannel [3]**: the user picks one channel (R, G, or B) and that channel's value is used directly. -The user can select 1 or more image data arrays which are assumed to be multi-component arrays of unsigned 8 bit values. The user can create a new AttributeMatrix if they want to store all the newly created arrays in a separate AttributeMatrix. +### Additional Standard Weights -### Additional GrayScale Conversions +Other widely-used weighting schemes (not built-in, but easy to supply as custom Luminosity weights): -The following are some additional accepted grayscale conversions +- **RMY Greyscale**: R=0.500, G=0.419, B=0.081 +- **YIQ / NTSC**: R=0.299, G=0.587, B=0.114 -+ RMY Greyscale: Red: 0.5 Green: 0.419 Blue: 0.081 -+ (YIQ/NTSC): Red: 0.299 Green: 0.587 Blue: 0.114 +### Input/Output Format + +- **Input arrays** must be uint8 with 3 components (RGB) or 4 components (RGBA). With RGBA input, the alpha channel is ignored. +- **Output arrays** are single-component uint8. + +Multiple input arrays can be processed in one filter pass; each produces its own output array. If *Output to New Attribute Matrix* is enabled, the new arrays are placed in a separate Attribute Matrix to keep them organized; otherwise they live alongside the originals. + +### Required Input Sources + +- **Input Image Arrays** -- 3- or 4-component uint8 arrays, typically produced by [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md) or another color-image reader. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ConvertDataFilter.md b/src/Plugins/SimplnxCore/docs/ConvertDataFilter.md index ac99b56623..be86bac737 100644 --- a/src/Plugins/SimplnxCore/docs/ConvertDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/ConvertDataFilter.md @@ -40,6 +40,15 @@ Down casting can have undefined behavior depending on the primitive types involv When converting data from signed values to unsigned values or vice-versa, there can also be undefined behavior. For example, if the user were to convert a signed 4 byte integer array to an unsigned 4 byte integer array and the input array has negative values, then the conversion rules are undefined and may differ from operating system to operating system. +### Related Filters + +- [Reshape Data Array](ReshapeDataArrayFilter.md) -- changes the tuple-dimensions interpretation of an array without converting its underlying data type. Use Reshape (not Convert) when you want to interpret existing bytes under a different shape. +- [Create Data Array](CreateDataArrayFilter.md) -- create a fresh array of the desired type and copy values into it manually. + +### Required Input Sources + +- **Input Array** -- the **Data Array** whose values will be cast to the new type. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/CopyDataObjectFilter.md b/src/Plugins/SimplnxCore/docs/CopyDataObjectFilter.md index 5e94261624..9a4f24e8af 100644 --- a/src/Plugins/SimplnxCore/docs/CopyDataObjectFilter.md +++ b/src/Plugins/SimplnxCore/docs/CopyDataObjectFilter.md @@ -19,7 +19,12 @@ Commonly used _BaseGroup_ children: See the DataStructure section of the reference manual for a complete hierarchy. -When the _Copy to New Parent_ is toggled true a new parameter will appear. This parameter, _Copied Parent Group_, allows for the selected arrays to all be copied into whatever data container you place here. +When *Copy to New Parent* is toggled on, a new parameter appears. This parameter, *Copied Parent Group*, lets the selected objects be copied into a different parent **DataGroup**, **Attribute Matrix**, or **Geometry** rather than alongside their originals. + +### Required Input Sources + +- **Objects to Copy** -- one or more existing **DataObjects** in the Data Structure. +- **Copied Parent Group** (only when *Copy to New Parent* is enabled) -- an existing parent container where the copies will be placed. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CopyFeatureArrayToElementArrayFilter.md b/src/Plugins/SimplnxCore/docs/CopyFeatureArrayToElementArrayFilter.md index fa5affa7dd..ff840386b0 100644 --- a/src/Plugins/SimplnxCore/docs/CopyFeatureArrayToElementArrayFilter.md +++ b/src/Plugins/SimplnxCore/docs/CopyFeatureArrayToElementArrayFilter.md @@ -6,7 +6,19 @@ Core (Memory/Management) ## Description -This **Filter** copies the values associated with a **Feature** to all the **Elements** that belong to that **Feature**. Xmdf visualization files write only the **Element** attributes, so if the user wants to display a spatial map of a **Feature** level attribute, this **Filter** will transfer that information down to the **Element** level. +This **Filter** broadcasts a per-**Feature** value to every **Cell** (element) that belongs to that Feature, producing a new cell-level **Data Array** that has the same length as the Feature Ids array. Each cell receives the value of the Feature it belongs to. + +### When to Use This Filter + +- **Visualization.** Most exporters (Xdmf, VTK, ParaView state files) treat Cell-level arrays as the natural per-voxel scalar to render. Broadcasting a per-grain statistic (size, average misorientation, Schmid factor, biased flag, etc.) down to the Cell level produces a colorable map of that quantity. +- **Downstream filtering on cells.** When you want to threshold cells based on a Feature-level criterion (e.g., "keep cells whose parent grain is unbiased"), it is simpler to broadcast the Feature flag to all cells and then apply a cell-level threshold. + +The output is always the same data type and component shape as the source Feature array. + +### Required Input Sources + +- **Feature Array to Copy** -- any feature-level array; common sources include [Compute Feature Sizes](ComputeFeatureSizesFilter.md), [Compute Average Orientations](../OrientationAnalysis/ComputeAvgOrientationsFilter.md), [Compute Schmid Factors](../OrientationAnalysis/ComputeSchmidsFilter.md), or a custom flag from [Compute Biased Features](ComputeBiasedFeaturesFilter.md) / [Compute Surface Features](ComputeSurfaceFeaturesFilter.md). +- **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 diff --git a/src/Plugins/SimplnxCore/docs/CreateAMScanPathsFilter.md b/src/Plugins/SimplnxCore/docs/CreateAMScanPathsFilter.md index 0046971cc4..09e4283984 100644 --- a/src/Plugins/SimplnxCore/docs/CreateAMScanPathsFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateAMScanPathsFilter.md @@ -6,7 +6,16 @@ Core (Geometry/Processing) ## Description -Given an input **Edge Geometry**, hatch spacing, hatch length, and hatch rotation angle, this **Filter** will generate an **Edge Geometry** representing the additive manufacturing scan paths along with arrays containing region ids and slice ids for each scan path. The "SliceTriangleGeometry" filter is typically used before this filter to generate the proper edge geometry. +Given an input **Edge Geometry**, hatch spacing, hatch length, and hatch rotation angle, this **Filter** will generate an **Edge Geometry** representing the additive manufacturing scan paths along with arrays containing region ids and slice ids for each scan path. + +### Units + +- **Hatch Spacing** and **Hatch Length** are lengths expressed in the same coordinate units as the input **Edge Geometry** (e.g., millimeters if the slicing was done in millimeters). They are not dimensionless and not pixels. +- **Hatch Rotation Angle** is specified in **degrees**. It is the per-slice rotation applied to the hatch direction. + +### Required Input Sources + +- An input **Edge Geometry** together with its per-edge **Slice Ids** and **Region Ids** arrays. These are typically produced by the [Slice Triangle Geometry](SliceTriangleGeometryFilter.md) filter, which slices a surface-mesh **Triangle Geometry** into the edge geometry consumed here. ![](Images/CreateAMScanVectors_5.png) diff --git a/src/Plugins/SimplnxCore/docs/CreateAttributeMatrixFilter.md b/src/Plugins/SimplnxCore/docs/CreateAttributeMatrixFilter.md index a4a3ac885f..3298120e1e 100644 --- a/src/Plugins/SimplnxCore/docs/CreateAttributeMatrixFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateAttributeMatrixFilter.md @@ -6,11 +6,29 @@ Core (Generation) ## Description -This **Filter** creates a new **Attribute Matrix**. +This **Filter** creates a new empty **Attribute Matrix** at a user-specified location in the **Data Structure**. The matrix is created with a user-specified set of *tuple dimensions* but contains no arrays initially; subsequent filters can add arrays to it. -### Example Usage +### What is an Attribute Matrix? -If you wanted to create an **Attribute Matrix** to represent a 3D volume where the dimensions of the 3 orthogonal axesare X=3, y=4 and Z=5, then the *Tuple Dimensions* would have a value of (3, 4, 5). +An **Attribute Matrix** is a container for **Data Arrays** that share the same *number of tuples* and the same *tuple shape*. All arrays inside one Attribute Matrix represent values "at the same set of points" -- for example, all per-cell arrays of an Image Geometry live in a single Cell Attribute Matrix, all per-feature arrays for a segmented dataset live in a single Feature Attribute Matrix, and all per-ensemble (phase) arrays live in an Ensemble Attribute Matrix. + +This shared-tuple-shape contract is enforced: any array added to an existing Attribute Matrix must match the matrix's tuple dimensions. Use an Attribute Matrix when the values you are grouping are all parallel arrays over the same domain. + +### When to Use This Filter + +- Pre-building the destination for a future filter that creates new feature-level or ensemble-level arrays. +- Creating a custom Attribute Matrix for organizational purposes (e.g., grouping all "computed" arrays separately from the "raw" arrays in the same Cell-level domain). +- Restructuring imported data so that arrays sharing a common dimension end up in the same matrix. + +For containers that hold heterogeneous data (arrays of different sizes, geometries, sub-groups), use [Create Data Group](CreateDataGroupFilter.md) instead. + +### Tuple Dimensions + +For a 3D volume with axes X=3, Y=4, Z=5, the *Tuple Dimensions* are (3, 4, 5). For a 1D feature-list with 100 features, the tuple dimensions are (100). The product of all dimensions equals the total number of tuples that any array added to this matrix must have. + +### Required Input Sources + +- **Parent Data Object Path** -- an existing **DataGroup** or **Geometry** under which the new Attribute Matrix will be created. Typically the output of [Create Image Geometry](CreateImageGeometryFilter.md), [Create Geometry](CreateGeometryFilter.md), or [Create Data Group](CreateDataGroupFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateColorMapFilter.md b/src/Plugins/SimplnxCore/docs/CreateColorMapFilter.md index 65469ab752..70cf8f46e5 100644 --- a/src/Plugins/SimplnxCore/docs/CreateColorMapFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateColorMapFilter.md @@ -1,5 +1,9 @@ # Create Color Map +## Group (Subgroup) + +Core (Image) + ## Description This **Filter** generates a color table array for a given 1-component input array. Each element of the input array @@ -8,9 +12,14 @@ is normalized and converted to a color based on where the value falls in the spe The user can apply an optional data mask and then set the RGB values (0-255) that will be used if the data mask has a FALSE value. +### Required Input Sources + +- A single-component (scalar) **Data Array** to colorize. This can be any scalar array already present in the **DataStructure**, for example a Confidence Index or Image Quality array read by an EBSD reader, a Feature ID array, or any computed scalar metric. +- (Optional) A **Mask Array** (boolean or uint8) used to flag elements as good/bad; flagged-FALSE elements receive the user-specified RGB color. + ## Preset Values -These are the valid preset strings that can be used. +These are the valid preset strings that can be used. This table is maintained by hand and lists the presets shipped with DREAM3D-NX along with a swatch of each color scheme. | Preset Name | Color Space | Example | |-------------|-------------|---------| @@ -135,11 +144,9 @@ These are the valid preset strings that can be used. % Auto generated parameter table will be inserted here -## Example Pipelines - ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/CreateDataArrayAdvancedFilter.md b/src/Plugins/SimplnxCore/docs/CreateDataArrayAdvancedFilter.md index 48a0ee1553..1d00a19811 100644 --- a/src/Plugins/SimplnxCore/docs/CreateDataArrayAdvancedFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateDataArrayAdvancedFilter.md @@ -68,7 +68,13 @@ If the parent is **NOT an Attribute Matrix**, then the user ***MUST*** set the t | Double | 64 bit | -1.7e+308 to -2.2e-308, 0.0, 2.2e-308 to 1.7e+308 (15 digits)| | Boolean | 8 bit |0 = false and any other value will be forced to 1 = true| -The component dimensions should multiply together into a total number of components equal to at least 1. Examples of *Component Dimensions* would be [3] for an RGB Image, [1] for a gray scale image, [1] for a scalar array, [4] for a quaternions array, [10x5] for an array with 10x5 grids at each tuple, etc. All values of the array will be initialized using the chosen initialization option. +The component dimensions should multiply together into a total number of components of at least 1. Examples of *Component Dimensions* would be [3] for an RGB image, [1] for a grayscale image or scalar array, [4] for a quaternions array, [3, 3] for a 3×3 tensor at each tuple, etc. All values of the array are initialized using the chosen initialization option. + +For the simpler case of a single-component-dimension array (most data), use [Create Data Array](CreateDataArrayFilter.md). This advanced version is required only when the component shape itself has more than one dimension. + +### Required Input Sources + +None. The array is created from user-supplied parameters; when the parent is an Attribute Matrix, the tuple dimensions are inherited from it. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateDataArrayFilter.md b/src/Plugins/SimplnxCore/docs/CreateDataArrayFilter.md index 05150bfd51..967cbbeb27 100644 --- a/src/Plugins/SimplnxCore/docs/CreateDataArrayFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateDataArrayFilter.md @@ -52,8 +52,13 @@ If the parent is **NOT an Attribute Matrix**, then the user ***MUST*** set the t | Double | 64 bit | -1.7e+308 to -2.2e-308, 0.0, 2.2e-308 to 1.7e+308 (15 digits)| | Boolean | 8 bit |0 = false and any other value will be forced to 1 = true| -The number of components should be at least 1. Examples of *Number of Components* would be 3 for an RGB Image, 1 for a gray scale image, 1 for a scalar array, 4 for a quaternions array, etc. All values of the array will be initialized to the user set value. The initialization value text box -must have a user entry or the default value *0* will be used. +The number of components should be at least 1. Examples of *Number of Components* would be 3 for an RGB image, 1 for a grayscale image or scalar array, 4 for a quaternions array, etc. All values of the array are initialized to the user-set value. The initialization value text box must have a user entry or the default value *0* will be used. + +This filter creates an array with a **single component dimension** (e.g., (1), (3), (4)). For arrays with multi-dimensional component shapes such as a 3×3 stiffness tensor, use [Create Data Array (Advanced)](CreateDataArrayAdvancedFilter.md) instead. + +### Required Input Sources + +None. The array is created from user-supplied parameters; when the parent is an Attribute Matrix, the tuple dimensions are inherited from it. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateDataGroupFilter.md b/src/Plugins/SimplnxCore/docs/CreateDataGroupFilter.md index 18cb01ed8e..552224a95a 100644 --- a/src/Plugins/SimplnxCore/docs/CreateDataGroupFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateDataGroupFilter.md @@ -6,9 +6,17 @@ Core (Generation) ## Description -This **Filter** creates a new **DataGroup**. +This **Filter** creates a new empty **DataGroup** at a user-specified location in the **Data Structure**. The new DataGroup contains nothing initially; subsequent filters can add child objects to it. -Unlike _AttributeMatrix_, _DataGroup_s are capable of holding any _DataObject_ of any size. +### What is a DataGroup? + +A **DataGroup** is a general-purpose container. Unlike an **Attribute Matrix**, a DataGroup can hold *any* DataObject of *any size* -- geometries, attribute matrices, arrays of varying sizes, even other DataGroups. There is no shared-tuple-shape contract. + +Use a DataGroup when you need to organize heterogeneous data, such as a logical grouping of unrelated arrays or geometries. Use [Create Attribute Matrix](CreateAttributeMatrixFilter.md) instead when all the arrays you are grouping share a common tuple shape and represent values over the same domain. + +### Required Input Sources + +- **Parent Data Object Path** -- an existing **DataGroup**, **Attribute Matrix**, or **Geometry** under which the new DataGroup will be created. The top-level of the Data Structure can also be selected. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateFeatureArrayFromElementArrayFilter.md b/src/Plugins/SimplnxCore/docs/CreateFeatureArrayFromElementArrayFilter.md index 096c27d794..77021730c0 100644 --- a/src/Plugins/SimplnxCore/docs/CreateFeatureArrayFromElementArrayFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateFeatureArrayFromElementArrayFilter.md @@ -6,7 +6,26 @@ Core (Memory/Management) ## Description -This **Filter** copies all the associated **Element** data of a selected **Element Array** to the **Feature** to which the **Elements** belong. The value stored for each **Feature** will be the value of the *last element copied*. +This **Filter** collapses a per-**Cell** (element) array down to a per-**Feature** array by storing one value per Feature. The value stored for each Feature is the **last cell value visited** during the scan -- not an average or majority vote. + +## WARNING: Lossy for Within-Feature Variation + +If the source cell array varies across cells *within* the same Feature, almost all of those values are discarded -- only the last cell scanned wins. **This filter is the correct choice only when every cell in a given Feature is guaranteed to hold the same value** (e.g., a cell-level phase array where every cell of a grain shares the same phase). + +For situations where you want a meaningful per-Feature summary (mean, max, min, median, etc.) of a cell-level array, use: + +- [Compute Array Statistics](ComputeArrayStatisticsFilter.md) -- computes mean, std dev, min, max, etc. per Feature. +- [Compute Average Orientations](../OrientationAnalysis/ComputeAvgOrientationsFilter.md) -- per-Feature average orientation specifically. + +### When This Filter Is Appropriate + +- Copying a uniform-within-feature cell-level array (cell phases, cell ensemble labels) to its Feature-level equivalent. +- Quick "any one example" extraction for diagnostic purposes. + +### Required Input Sources + +- **Cell Array to Copy** -- a cell-level array whose values are uniform within each Feature. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateGeometryFilter.md b/src/Plugins/SimplnxCore/docs/CreateGeometryFilter.md index e310c729e9..9e3a5debc2 100644 --- a/src/Plugins/SimplnxCore/docs/CreateGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateGeometryFilter.md @@ -6,141 +6,57 @@ DREAM3D Review (Geometry) ## Description -This **Filter** creates a **Geometry** object and the necessary **Element Attribute Matrices** on which to store **Attribute Arrays** and **Element Attribute Arrays** which define the geometry. The type of **Attribute Matrices** and **Attribute Arrays** created depends on the kind of **Geometry** being created: +This **Filter** creates a new **Geometry** object of one of eight supported types, together with the **Attribute Matrices** and **Attribute Arrays** needed to define its topology. Use this filter when you have raw coordinate/connectivity data (typically from an external file or an upstream filter) and need to wrap it in a DREAM3D-NX geometry object. -| Type | Attribute Matrices | Attribute Arrays | -|------------------|--------------------|-------------| -| Image | Cell | -| Rectilinear Grid | Cell | x, y, & z Bounds | -| Vertex | Vertex | Vertices | -| Edge | Vertex + Edge | Vertices + Edges | -| Triangle | Vertex + Face | Vertices + Faces | -| Quadrilateral | Vertex + Face | Vertices + Faces | -| Tetrahedral | Vertex + Cell | Vertices + Cells | -| Hexahedral | Vertex + Cell | Vertices + Cells | +For grid-type geometries (Image, Rectilinear Grid), the topology is defined entirely by numeric parameters (dimensions, spacing, origin, or bounds arrays). For mesh-type geometries (Vertex, Edge, Triangle, Quadrilateral, Tetrahedral, Hexahedral), the user supplies a *shared vertex list* and an *element connectivity list* as input arrays. -### Understanding Geometries +### Supported Geometry Types -This **Filter** requires the user to enter information that defines the topological information for the chosen **Geometry**. Choosing valid information for a given **Geometry** necessitates an understanding of how **DREAM3D-NX** stores and interprets this information. A general overview of the data model used in **DREAM3D-NX** may be found here. More specific information for **Geometry** objects is provided below. +| Type | Topology | Element Type | Required Inputs | +|---|---|---|---| +| Image | Regular voxel grid | Cell (voxel) | Dimensions + Spacing + Origin | +| Rectilinear Grid | Variable-spacing grid | Cell | x/y/z Bounds arrays | +| Vertex | Point cloud | Vertex | Vertex coordinates | +| Edge | Line mesh | Edge (2 vertices) | Vertex list + Edge list | +| Triangle | Surface mesh | Face (3 vertices) | Vertex list + Triangle list | +| Quadrilateral | Surface mesh | Face (4 vertices) | Vertex list + Quad list | +| Tetrahedral | Volume mesh | Cell (4 vertices) | Vertex list + Tet list | +| Hexahedral | Volume mesh | Cell (8 vertices) | Vertex list + Hex list | -#### Grid Geometries +![Fig. 1: The eight geometry types and the data that defines each.](Images/CreateGeometry_GeometryTypes.png) -##### Image +### Grid Geometries -An **Image Geometry** is a *grid-like* **Geometry**, and is the simplest and most widely used of the basic **Geometry** types. An **Image Geometry** is a *regular, rectilinear grid*; if the *dimenionality* of the image is *d*, then only *3*d* numbers are needed to completely define the **Geometry**: three *d*-vectors for the *dimensions*, *origin*, and *spacing*. +**Image Geometry** is a *regular, rectilinear grid* defined by three vectors of three numbers each: dimensions, spacing, and origin. -- Dimensions define the extents of the grid. Stored as unsigned 64 bit integers. The dimensions are also known as the **extents** and are *zero* based thus a dimension with a value of 10 has extents from 0-9. -- Spacing defines the physical distance between grid planes for each orthogonal direction (constant along a given direction). Stored as 32 bit floating point numbers. Spacing has been known in the past as *resolution* but this term is ambiguous so spacing is used. A value of "microns per pixel" is a good example of "Spacing" units. -- Origin defines the physical location of the *bottom left* grid point in *d*-dimensional space. Stored as 32 bit floating point numbers. +- **Dimensions** -- grid extents stored as unsigned 64-bit integers. Dimensions are **0-based**, so a dimension of 10 has extents 0-9. No dimension may be zero or negative. +- **Spacing** -- physical distance between grid planes along each axis, stored as 32-bit floats. Units match whatever the source data uses (e.g., microns per voxel). Spacing must be positive and non-zero. (Older docs called this *resolution*; *spacing* is preferred because *resolution* is ambiguous.) +- **Origin** -- physical location of the bottom-left grid point in the geometry's coordinate system. Stored as 32-bit floats. No value restriction. -All **Image Geometries** in **DREAM3D-NX** are defined as 3D images. A 2D image is assumed when one of the dimension values is exactly 1; the 2D image is then considered a plane. Most **DREAM3D-NX** **Filters** will properly take account for the **Image** dimension if it matters (for example, the Find Feature Shapes **Filter** accounts for whether the **Image** is 2D or 3D when computing values such as *aspect ratios* or *axis Euler angles*). No dimension may be negative or equal to 0. The spacing must be a positive, non-zero value. The Origin has no value restrictions. This **Filter** requires the user to enter the nine values for the dimenions, origin, and spacing. +All Image Geometries are stored as 3D; a 2D image is represented by setting one dimension to exactly 1, producing a plane. Downstream filters that care (e.g., *Compute Feature Shapes*) detect this automatically. -Since all **Image Geometries** are implicitly 3D (even when plane-like), the fundamental building-block of an image is a *voxel*, which is a 3D object; therefore, the basic **Element** type for an **Image Geometry** is **Cell**. **Attribute Arrays** associated with **Image Cells** are assumed to raster *x-y-z*, fastest to slowest. +**Rectilinear Grid Geometry** is similar to an Image Geometry but allows variable spacing along each axis. It is defined by three monotonically-increasing 32-bit float bounds arrays (x, y, z). The spacing between any two adjacent planes is the difference between consecutive entries in the bounds array. No origin is needed -- the bounds arrays explicitly encode position. -##### Rectilinear Grid +### Unstructured (Mesh) Geometries -A **Rectilinear Grid Geometry** is a *grid-like* **Geometry**. Similar to an **Image Geometry**, a **Rectilinear Grid Geometry** has grid extents (dimensions), but is allowed to have variable *spacing* along each orthogonal direction. The **Geometry** then requires a total of (xdim + 1) + (ydim + 1) + (zdim + 1) numbers to define the topology. The values are stored in three separate arrays termed the *x bounds*, *y bounds*, and *z bounds*. These bounds arrays store the spatial location of all the planes along a given orthogonal direction. The spacing for a given plane (equivalent to the spacing for an **Image Geometry**) is then the difference between two of these contiguous array values. An origin does not need to be defined for a **Rectilinear Grid Geometry**, since the grid's location in space is explicitly encoded in its bounds arrays. This **Filter** requires the user to select **Attribute Arrays** that define the three bounds arrays. These arrays must be *single component, 32-bit float* arrays. Additionally, the values for each of the bounds arrays must be *strictly increasing*, which guarantees that computing the spacing for a given plane yields a postive value. +Mesh geometries are defined by a **shared vertex list** (a 3-component float array of vertex coordinates) plus an **element connectivity list** (a multi-component unsigned 64-bit integer array, where each tuple is the list of vertex IDs that make up one element). -A **Rectilinear Grid Geometry** may be defined as 2D; the associated bounds array for the plane dimension is then exactly two. No bounds arrays may have less than two values. Since all **Rectilinear Grid Geometries** are implicitly 3D (even when plane-like), the fundamental building-block of an image is a *voxel*, which is a 3D object; therefore, the basic **Element** type for an **Image Geometry** is **Cell**. **Attribute Arrays** associated with **Rectilinear Grid Cells** are assumed to raster *x-y-z*, fastest to slowest. +**Shared vertex** means a vertex used by multiple elements appears only once in the vertex list. For example, two quadrilaterals sharing one edge have 6 unique vertices (not 8). Element IDs are always **0-based**. -#### Unstructured and Mesh-Like Geometries +**Element winding** matters for surface meshes. By convention, vertex order in each element tuple follows the **right-hand rule** -- when fingers curl in the order of the vertices, the thumb points in the direction of the element's surface normal. For tetrahedra, the first three vertices define the base; their winding by the right-hand rule defines a normal pointing toward the fourth vertex. Consistent winding makes tetrahedron volume *signed*, which lets downstream filters detect inverted elements. -##### Vertex - -A **Vertex Geometry** is an *unstructured* **Geometry**. An unstructured **Geometry** requires explicit definition of point coordinates. Sometimes referred to as a *point cloud*, a **Vertex Geometry** is simply a collection of points. Defining this topology requires a total number of values equal to *d* times the total number of points, where *d* is the dimensionality of the point cloud; within **DREAM3D-NX**, *d* is always taken to be three. The point coordinates are stored as *32-bit floats*; no other range restrictions are enforced. This **Filter** requires the user to select an **Attribute Array** that defines these point coordinates. The array must have *three components* and consist of *32-bit floats*. The number of *tuples* in the array defines the number of vertices in the resulting **Vertex Geometry**. - -The fundamental **Element** type of a **Vertex Geometry** is *vertices*. Data stored in a **Vertex Attribute Matrix** is ordered according to **Vertex** *Ids*. Therefore, the nth tuple in the supplied **Vertex** list corresponds to the data stored in the nth column of the **Vertex Attribute Matrix**. By convetion, **Vertex** Ids are *zero indexed*. - -##### Mesh-Like Geometries - -The following **Geometries** are considered *mesh-like*, and all share similar features concerning their storage and interpretation. A mesh-like **Geometry** is an unstructured **Geometry** that additionally requires explicit definition of the connectivity of its **Elements** and its **Vertices**. The **Element** type defines the kind of **Geometry** and the number of **Vertices** needed to define that **Element**: - -| Name | Element Type | Number of Vertices Per Element | -|------------------|--------------------|--------------------| -| Edge | line | 2 | -| Triangle | triangle | 3 | -| Quadrilateral | quadrilateral | 4 | -| Tetrahedral | tetrahedron | 4 | -| Hexahedral | hexahedron | 8 | - -The storage scheme adopted by **DREAM3D-NX** requires at least two arrays to define mesh-like **Geometries**: a list of **Vertices** (i.e., the vertex coordinates) and the **Element** connectivities (i.e., which vertices belong to a given **Element**). To maintain simplicity, flexibility, and small memory overhead, **DREAM3D-NX** uses the concept of *shared vertex lists*. In this paradigm, the vertex coordinates are stored only once per *unique* vertex. Consider a **Quadrilateral Geometry** that consists of just two squares that share one side. In this example, there are exactly *six* unique vertices. The **Attribute Array** that defines the coordinates of these **Vertices** would then have six *tuples*, with three values at each tuple (the x, y, and z positions of that **Vertex**). Writing each tuple on one line, the array could look like this: - - 0.0 0.0 0.0 // Vertex Id 0 - 1.0 0.0 0.0 // Vertex Id 1 - 0.0 1.0 0.0 // Vertex Id 2 - 1.0 1.0 0.0 // Vertex Id 3 - 2.0 0.0 0.0 // Vertex Id 4 - 2.0 1.0 0.0 // Vertex Id 5 - -**Element** connectivities are stored in **Attribute Arrays** that have a number of tuples equal to the total number of **Elements**, with a number of components at each tuple equal to the number of vertices per element. In this example, a quadrilateral list would have two tuples, with four values stored at each tuple (the four vertex Ids that define that quadrilateral). When defining **Elements**, the order in which the **Vertex** Ids are listed, called the *winding*, is important, since this ordering defines the direction of the normal. By convention, the *right hand rule* used. Thus, given the above vertex positions, the following list of **Vertex** Ids defines two quadrilaterals whose normals point along the positive z direction: - - 0 1 3 2 // Quad Id 0 - 1 4 5 3 // Quad Id 1 - -Creating any mesh-like **Geometry** requires the user to supply two arrays: one that defines the vertex coordinates (the *shared vertex list*), which is a three component array of floats; and one that defines the **Element** connectivities, which is a n-component array (where n is the number of vertices per element) of *unsigned 64-bit integers*. Note that any **Element** Id values (**Vertex** or otherwise) are *zero indexed*. - -The shared list schema for mesh storage has the benefit of being space efficient, time efficient when iterating in sequence over vertices or elements, and capable of storing *nonmanifold* meshes. An example of a nonmanifold mesh is a **Triangle Geometry** that has more than two triangles sharing the same edge. This specific example of nonmanifold meshes occurs frequently in **DREAM3D-NX** surface meshes of polycrystals, where many nonmanifold entities may exist (i.e., triple lines and quad points). A significant downside of shared lists is that computing adjacency information, such as the neighbors of a given element or the elements that share a vertex, requires iterating over the entire **Geometry**; other mesh data structures avoid this limitation. Additionally, since the lists are stored as **Attribute Arrays**, which hold information contiguously in memory, adding or removing vertices or elements is tedious and potentially slow. - -Note that although the default interpretation of lists that define mesh-like **Geometries** is shared, no undefined behavior should be observed if the information is not stored shared (i.e., if the same **Vertex** is stored more than once with a different Id). Additionally, not all **Vertices** are required to be associated with an **Element**. The primary requirement is that the largest **Vertex** Ids listed in the **Element** list must not be larger than the total number of **Vertices**. - -##### Edge - -An **Edge Geometry** is the simplest *mesh-like* **Geometry**, consisting of a collection of edges connecting two vertices. Creating an **Edge Geometry** requires supplying a shared **Vertex** list and an **Edge** list. - -##### Triangle - -A **Triangle Geometry** is a *mesh-like* **Geometry**, consisting of a collection of triangles connecting three vertices; it is a type of *surface mesh*. Creating a **Triangle Geometry** requires supplying a shared **Vertex** list and a **Triangle** list. - -##### Quadrilateral - -A **Quadrilateral Geometry** is a *mesh-like* **Geometry**, consisting of a collection of quadrilaterals connecting four vertices; it is a type of *surface mesh*. Creating a **Quadrilateral Geometry** requires supplying a shared **Vertex** list and a **Quadrilateral** list. - -##### Tetrahedral - -A **Tetrahedral Geometry** is a *mesh-like* **Geometry**, consisting of a collection of tetrahedra connecting four vertices; it is a type of *volume mesh*. Creating a **Tetrahedral Geometry** requires supplying a shared **Vertex** list and a **Tetrahedral** list. The winding that define tetrahedra require one additional convention to complement the right hand rule. By convention, the first three vertices define the tetrahedra *base*; the winding of these vertices by the right hand rule defines a normal that points *towards the fourth vertex*. This convention is useful since applying it consistently allows for the volume of the tetrahedra to be *signed*, which is important for determining if a tetrahedron is "inverted". - -##### Hexahedral - -A **Hexahedral Geometry** is a *mesh-like* **Geometry**, consisting of a collection of hexahedra connecting eight vertices; it is a type of *volume mesh*. Creating a **Hexahedral Geometry** requires supplying a shared **Vertex** list and a **Hexahedral** list. - -### Defining Geometries with Attribute Arrays - - For **Geometries** that require the selection of **Attribute Arrays** (all **Geometries** except **Image**), the arrays will be *copied* to create the new **Geometry**. Therefore, any operations on the original array will not affect the topology of the **Geometry**, and any geometric operations will not affect the original array. This behavior can be adjusted in the filter by using the *Array Handling* boolean. +The shared-list scheme is space-efficient and supports *nonmanifold* meshes (e.g., triangle meshes where more than two triangles share an edge, which occurs at triple lines and quadruple points in polycrystalline surface meshes). Its downside: computing adjacency (e.g., "what elements share this vertex?") requires iterating the whole mesh. ### Array Handling -The *Array Handling* parameter controls how the input **Attribute Arrays** (vertex list, element connectivity, etc.) are transferred to the new **Geometry**: - -- **Copy Attribute Arrays [0]**: The input arrays are copied into the new **Geometry**. The original arrays remain in the **Data Structure** and are unaffected by any subsequent geometric operations. -- **Move Attribute Arrays [1]**: The input arrays are moved into the new **Geometry**. The original array paths are removed from the **Data Structure**, reducing memory usage when the originals are no longer needed. - -This **Filter** will validate that the arrays selected to define a **Geometry** "make sense", given the above information for how **Geometries** are stored in **DREAM3D-NX** (for example, no dimension for an **Image** may be less than or equal to zero, no bounds arrays for a **Rectilinear Grid** may have less than two values, and no **Vertex** Ids stored in a shared **Element** list may be larger than the total number of **Vertices** in the shared **Vertex** list). The checks that require accessing the actual array values (as opposed to just descriptive information) will be performed at run time. By default, these checks will only produce warnings, allowing the **Pipeline** to continue; the user may opt to change these warnings to errors by selecting the *Treat Geometry Warnings as Errors* option. - -Generally, arrays used by this **Filter** to create **Geometries** must be supplied by the user. One method to import geometric information into **DREAM3D-NX** is to read the information in from a text file using the Import ASCII Data **Filter**. For example, imagine having an external simulation code that creates a tetrahedral volume mesh with two associated field values, one stored on the mesh vertices and one stored on the mesh tetrahedra. It is possible to import this mesh and corresponding information into **DREAM3D-NX** for further analysis. The user must supply at least two files: one that contains the vertex information and one that contains the tetrahedra information. The vertex file would contain, on each line, the three coordinates of the vertex and the value of the field array on that vertex. It may, for example, look like this: - - # Some header information - # Some more header information - x_pos y_pos z_pos value - 1.235 2.323 1.562 465.2 - -12.3 3.456 2.323 567.4 - 3.450 9.782 6.567 120.2 - ..... - -In this above example, the vertex information begins on line 4; thus, line 4 defines **Vertex** Id 0, line 5 defines **Vertex** Id 1, etc. Similarly, a file containing information about tetrahedra is needed: - - # Some header information - # Some more header information - vert_0 vert_1 vert_2 vert_3 value - 1 2 0 3 12.42 - 2 7 5 4 14.71 - 6 9 7 8 16.78 - ..... +The *Array Handling* parameter controls what happens to the input arrays passed to this filter: - Again, the real information begins on line 4, which defines the connectivity for **Tetrahedra** Id 0. These Id values refer to the **Vertex** Ids from the first file (for example, a **Vertex** Id of 0 corresponds to the information on line 4 of the first file). Remember to consider the *right hand rule* when dealing with mesh-like **Geometries**, as this will affect the **Vertex** ordering! +- **Copy Attribute Arrays [0]**: input arrays are copied into the new geometry. Originals are left in place. +- **Move Attribute Arrays [1]**: input arrays are moved into the new geometry and removed from their original location. Saves memory when the original copies are no longer needed. - Assuming it is possible to get the mesh into files similar to the above ones, it is straightforward to import the information into **DREAM3D-NX**. First, create an emtpy Data Container. Then, run the Import ASCII Data **Filter** for the vertex file. In the above example, line 3 could be used as headers to define the array names (remember that **Vertex** positions must be of type *float*!). Allow the reader wizard to create an **Attribute Matrix** in which to store the arrays. Repeat the process with another Import ASCII Data **Filter** to read the tetrahedra information (remember in this case that Id values must be of type *int64\_t*!). At this point, there will be two **Attribute Matrices** in the **Data Container**, one with 4 arrays (the **Vertex** information) and one with 5 arrays (the **Tetrahedra** information). The Create Geometry **Filter** wants the **Vertex** list as a three component array and the **Tetrahedra** list as a four component array. To combine the individual arrays into ones of the proper component dimension, run the Combine Attribute Arrays **Filter**. At this point, the Create Geometry **Filter** may be used to create a **Tetrahedral Geometry** using the combined arrays. After this **Filter**, the Move Data **Filter** may be used to move the arrays that represent the values stored on the **Vertices** and **Tetrahedra** into the created **Vertex** and **Cell Attribute Matrices**. +### Validation - When creating **Geometries**, remember to consider all the various rules for how a **Geometry** is stored and interpreted. In particular, remeber that **Element** Ids are always zero indexed, mesh-like **Geometries** obey the *right hand rule* for windings and normal directions, and **Element** lists are by default considered *shared*. Note that although the storage scheme used by **DREAM3D-NX** (shared lists) is highly generic, some **Filters** may assume that the **Geometry** is reasonably *well formed*. +The filter validates that the supplied arrays "make sense" for the chosen geometry type (e.g., bounds arrays for a Rectilinear Grid have at least 2 values; no vertex ID in a connectivity list exceeds the vertex count). Checks that require reading actual values run at execute time. By default these checks produce warnings; enable *Treat Geometry Warnings as Errors* to make them fail the pipeline. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreateImageGeometryFilter.md b/src/Plugins/SimplnxCore/docs/CreateImageGeometryFilter.md index 027f2d8d7b..3075cf5592 100644 --- a/src/Plugins/SimplnxCore/docs/CreateImageGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreateImageGeometryFilter.md @@ -1,30 +1,34 @@ # Create Geometry (Image) -## This filter should be considered deprecated. Use the "Create Geometry" filter instead - ## Group (Subgroup) Core (Generation) +> ⚠ **Deprecation Notice.** This filter is deprecated. Use the more general [Create Geometry](CreateGeometryFilter.md) filter instead. This filter is retained for compatibility with legacy pipelines. + ## Description -This **Filter** creates an **Image Geometry** specifically for the representation of a 3D rectilinear grid of voxels (3D) or pixels -(2D). Each axis can have its starting point (origin), resolution, and length defined for the **Geometry**. The **Data Container** in which to place the **Image Geometry** must be specified. +This **Filter** creates an **Image Geometry** -- a regular grid of voxels (3D) or pixels (2D). The user supplies the dimensions, spacing, and origin; the filter creates a new geometry object with no cell data attached. Use it before reading raw binary data into a grid, before creating synthetic data on a regular grid, or whenever you need a fresh empty Image Geometry. + +An Image Geometry is the simplest and most widely used DREAM3D-NX geometry type. For dimensionality *d*, only 3 × *d* numbers are needed to completely define it: three *d*-vectors for the dimensions, origin, and spacing. -An **Image Geometry** is a *grid-like* **Geometry**, and is the simplest and most widely used of the basic **Geometry** types. An **Image Geometry** is a *regular, rectilinear grid*; if the *dimenionality* of the image is *d*, then only *3*d* numbers are needed to completely define the **Geometry**: three *d*-vectors for the *dimensions*, *origin*, and *spacing*. +- **Dimensions** -- grid extents. Stored as unsigned 64-bit integers. Dimensions are **0-based**, so a dimension of 10 spans extents 0-9. No dimension may be zero or negative. +- **Spacing** -- physical distance between grid planes along each axis. Stored as 32-bit floats. Units match the source data (e.g., microns per voxel). Spacing must be positive and non-zero. (*Resolution* was the older name; *spacing* is preferred because *resolution* is ambiguous.) +- **Origin** -- physical location of the bottom-left grid point in the geometry's coordinate system. Stored as 32-bit floats. No value restriction. -- Dimensions define the extents of the grid. Stored as unsigned 64 bit integers. The dimensions are also known as the **extents** and are *zero* based thus a dimension with a value of 10 has extents from 0-9. -- Spacing defines the physical distance between grid planes for each orthogonal direction (constant along a given direction). Stored as 32 bit floating point numbers. Spacing has been known in the past as *resolution* but this term is ambiguous so spacing is used. A value of "microns per pixel" is a good example of "Spacing" units. -- Origin defines the physical location of the *bottom left* grid point in *d*-dimensional space. Stored as 32 bit floating point numbers. +All Image Geometries are stored as 3D; a 2D image is represented by setting one dimension to exactly 1, producing a plane. Downstream filters that care about dimensionality (e.g., *Compute Feature Shapes*) detect the 2D case automatically. -All **Image Geometries** in **DREAM3D-NX** are defined as 3D images. A 2D image is assumed when one of the dimension values is exactly 1; the 2D image is then considered a plane. Most **DREAM3D-NX** **Filters** will properly take account for the **Image** dimension if it matters (for example, the Find Feature Shapes **Filter** accounts for whether the **Image** is 2D or 3D when computing values such as *aspect ratios* or *axis Euler angles*). No dimension may be negative or equal to 0. The spacing must be a positive, non-zero value. The Origin has no value restrictions. This **Filter** requires the user to enter the nine values for the dimenions, origin, and spacing. +Since all Image Geometries are implicitly 3D, the building block is a *voxel*, which is a 3D object. The basic **Element** type for an Image Geometry is **Cell**. Attribute arrays associated with cells are stored in x-y-z raster order (fastest to slowest). -Since all **Image Geometries** are implicitly 3D (even when plane-like), the fundamental building-block of an image is a *voxel*, which is a 3D object; therefore, the basic **Element** type for an **Image Geometry** is **Cell**. **Attribute Arrays** associated with **Image Cells** are assumed to raster *x-y-z*, fastest to slowest. +![Fig. 1: An Image Geometry is defined by its dimensions (number of cells per axis), spacing (physical distance between grid planes per axis), and origin (the bottom-left grid point).](Images/CreateImageGeometry_OriginSpacingDimensions.png) ### Example Usage -If you are reading in raw binary data that represents data on a regular grid, the user will need to run this -filter first to create a description of the **Geometry**. +When importing raw binary data on a regular grid, run this filter first to create the geometry description; then attach data via subsequent reader filters. + +### Required Input Sources + +None. The geometry is created from user-supplied parameters. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CreatePythonSkeletonFilter.md b/src/Plugins/SimplnxCore/docs/CreatePythonSkeletonFilter.md index af0f56db77..ab03b78d5c 100644 --- a/src/Plugins/SimplnxCore/docs/CreatePythonSkeletonFilter.md +++ b/src/Plugins/SimplnxCore/docs/CreatePythonSkeletonFilter.md @@ -1,21 +1,16 @@ # Create Python Plugin and/or Filters -## Description +## Group (Subgroup) -The **Create Python Plugin and/or Filters** is a tool in the DREAM3D-NX environment that allows users to generate or update Python plugins and filter codes. This filter provides an interface for setting up and configuring Python filters within DREAM3D-NX pipelines, either by creating new plugins or by adding to existing ones. +Core (Generation) -## Usage +## Description -### Configuration +The **Create Python Plugin and/or Filters** is a tool in the DREAM3D-NX environment that allows users to generate or update Python plugins and filter codes. This filter provides an interface for setting up and configuring Python filters within DREAM3D-NX pipelines, either by creating new plugins or by adding to existing ones. -The filter requires several parameters to be set, which dictate whether a new plugin is created or an existing one is modified. Key parameters include: +The filter is driven entirely by its parameters (described in the auto-generated table below), which dictate whether a new plugin is created or an existing one is modified. -- `Use Existing Plugin`: A flag indicating whether to modify an existing plugin. -- `Name of Plugin`: The name of the plugin. -- `Human Name of Plugin`: A human-readable name for the plugin. -- `Existing Plugin Location`: The directory where the existing plugin is located (for updates). -- `Plugin Output Directory`: The directory where the new plugin will be stored. -- `Filter Names`: A list of filter names to be included in the plugin, separated by commas. +## Usage ### Generating a New Plugin @@ -44,9 +39,11 @@ If your plugin was not generated using the provided filter but was instead creat - In the `__init__.py` file, add to the `all` method. - In the `Plugin.py` file, add to the `get_filters` method. -## Example Pipelines +### Required Input Sources + +None -- this **Filter** generates source files on disk and does not consume any **DataStructure** objects. -None +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/CropEdgeGeometryFilter.md b/src/Plugins/SimplnxCore/docs/CropEdgeGeometryFilter.md index d1d76bc5e4..98398f34c2 100644 --- a/src/Plugins/SimplnxCore/docs/CropEdgeGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/CropEdgeGeometryFilter.md @@ -1,11 +1,17 @@ # Crop Geometry (Edge) +## Group (Subgroup) + +Core (Conversion) + ## Description -The **Crop Geometry (Edge) Filter** allows users to crop a region of interest (ROI) from an **Edge Geometry**. This filter is essential for isolating specific portions of edge-based data structures. +The **Crop Geometry (Edge) Filter** allows users to crop a region of interest (ROI) from an **Edge Geometry**. This filter is essential for isolating specific portions of edge-based data structures. For cropping voxel-based data instead, see [Crop Geometry (Image)](CropImageGeometryFilter.md). Users can selectively crop specific dimensions of the **Edge Geometry** by toggling **Crop X Dimension**, **Crop Y Dimension**, and **Crop Z Dimension** ON or OFF. Only dimensions that are turned ON will be cropped. +The **Min Coordinate** and **Max Coordinate** values define the ROI bounds and are specified in the **Edge Geometry's** physical coordinate units (the same units as the vertex positions), *not* as cell or vertex indices. + ### Boundary Intersection Behavior The *Boundary Intersection Behavior* parameter provides the following choices: @@ -89,8 +95,6 @@ As you can see, the edges that intersect the ROI boundary have been interpolated % Auto generated parameter table will be inserted here -## Example Pipelines - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/SimplnxCore/docs/CropImageGeometryFilter.md b/src/Plugins/SimplnxCore/docs/CropImageGeometryFilter.md index 06955dbc50..78bc0cffeb 100644 --- a/src/Plugins/SimplnxCore/docs/CropImageGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/CropImageGeometryFilter.md @@ -1,80 +1,86 @@ # Crop Geometry (Image) +## Group (Subgroup) + +Core (Spatial) + ## Description -This **Filter** allows the user to crop a region of interest (ROI) from an **Image Geometry**. The input parameters are in units of voxels or physical coordinates. +This **Filter** extracts a region of interest (ROI) from an **Image Geometry**, producing a new geometry that contains only the selected cells. Bounds can be specified either in cell indices (voxels) or in physical coordinates. Individual dimensions (X, Y, Z) can be cropped independently. -It is possible to also crop specific dimensions of the **Image Geometry** by toggling **Crop X Dimension**, **Crop Y Dimension**, and **Crop Z Dimension** ON and OFF. +This is the inverse of [Pad Image Geometry](PadImageGeometryFilter.md). Common uses are isolating a sample from its overscan border, focusing analysis on a single feature, or reducing data size for testing. -## WARNING: NeighborList Removal +### Bounds Mode + +The *Use Physical Bounds* parameter selects how the crop bounds are interpreted: + +- **Use Physical Bounds = false**: bounds are integer **cell indices** (0-based, **inclusive** on both ends). Xmin=50, Xmax=99 keeps cells 50 through 99 (the last 50 cells of a 100-cell volume). +- **Use Physical Bounds = true**: bounds are **physical coordinates** in the geometry's units. The filter computes which cells fall inside the box defined by those coordinates, taking the geometry's origin and spacing into account. + +If any bound exceeds the geometry's extent on that axis, the filter clamps to the geometry's actual extent. The filter fails in preflight only when **all** of the requested bounds fall outside the geometry. -If the option to "Renumber Features" is turn ON 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. +### Per-Axis Cropping +The *Crop X Dimension*, *Crop Y Dimension*, and *Crop Z Dimension* booleans toggle whether each axis is cropped at all. An axis with its flag OFF retains all of its cells regardless of the bounds setting. -## Examples +### Examples -In the following examples, the following image is being used. +In the following examples, the source image has: -- Origin: [0.0, 0.0, 0.0] -- Spacing: {0.5, 0.5, 1.0} -- Dimensions: {100, 100, 1} +- Origin: (0.0, 0.0, 0.0) +- Spacing: (0.5, 0.5, 1.0) +- Dimensions: (100, 100, 1) -So the bounds of the image is (0-50 micron, 0-50 micron, 0-1 micron) +So the physical bounds are (0-50 microns, 0-50 microns, 0-1 micron). ![Base image for examples](Images/CropImageGeometry_1.png) -### Example 1 +#### Example 1 -- Crop to the last 50 cells in X and Y -If the user wanted to crop the last 50 voxels in the X and Y axis then the user would use the following values: + Xmin = 50, Xmax = 99 + Ymin = 50, Ymax = 99 + Zmin = 0, Zmax = 0 + Use Physical Bounds = false - Xmin = 50, - Xmax = 99, - Ymin = 50, - Ymax = 99, - Zmin = 0, - Zmax = 0 +Result: ![Cropped image using voxels as the bounds](Images/CropImageGeometry_2.png) -**Note:** the units in the above image is in microns. +#### Example 2 -- Crop to the middle 50 cells -**Note:** The input parameters are *inclusive* and begin at *0*, so in the above example *50-99* will include the last 50 voxels. + Xmin = 25, Xmax = 74 + Ymin = 25, Ymax = 74 + Zmin = 0, Zmax = 0 + Use Physical Bounds = false -### Example 2 +Result: -If the user would like to crop out the `middle` 50 voxels from the image, these are the inputs: +![Cropped image using voxels as the bounds](Images/CropImageGeometry_3.png) - Xmin = 25, - Xmax = 74, - Ymin = 25, - Ymax = 74, - Zmin = 0, - Zmax = 0 +#### Example 3 -- Crop using physical coordinates, with one bound exceeding the volume -![Cropped image using voxels as the bounds](Images/CropImageGeometry_3.png) + Xmin = 30 microns, Xmax = 65 microns + Ymin = 30 microns, Ymax = 65 microns + Zmin = 0 microns, Zmax = 65 microns + Use Physical Bounds = true -### Example 3 +The Zmax of 65 microns exceeds the geometry's 1-micron Z extent and is silently clamped. The crop still succeeds because at least part of the requested box lies inside the geometry. -In this example the user is going to define the crop using physical coordinates and also selecting an upper bound that exceeds the actual bounds of the image. In this case, the filter will instead use the maximum bounds from that axis. +![Cropped image using voxels as the bounds](Images/CropImageGeometry_4.png) - Xmin = 30 microns, - Xmax = 65 microns, - Ymin = 30 microns, - Ymax = 65 microns, - Zmin = 0 microns, - Zmax = 65 microns +### Renumber Features -**Note:** This will work because at least some portion of the cropped image is within the original image. If **ALL** cropped values fall out side of the image bounds then the filter will error out in preflight. +Cropping can fully remove some **Features** from the volume, which leaves their Feature IDs unused and produces gaps. If *Renumber Features* is enabled, the Cell Feature Attribute Matrix is resized to drop empty features and remaining Features are renumbered to be contiguous starting from 1. Leave this off if you intend to compare the cropped output against the original larger volume by Feature ID. -![Cropped image using voxels as the bounds](Images/CropImageGeometry_4.png) +The user can save the cropped volume as a new **Data Container** or overwrite the current volume in place. -User may note that the way the bounds are determined are affected by the origin and spacing, so be sure to take these into account when supplying coordinate bounds for the crop. +## WARNING: NeighborList Removal -## Renumber Features +When *Renumber Features* is enabled and the Cell Feature Attribute Matrix contains any *NeighborList* arrays, those arrays are **removed** because they refer to the old Feature IDs. Re-run [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) afterward to rebuild them. -It is possible with this **Filter** to fully remove **Features** from the volume, possibly resulting in consistency errors if more **Filters** process the data in the pipeline. If the user selects to *Renumber Features* then the *Feature Ids* array will be adjusted so that all **Features** are continuously numbered starting from 1. The user should decide if they would like their **Features** renumbered or left alone (in the case where the cropped output is being compared to some larger volume). +### Required Input Sources -The user has the option to save the cropped volume as a new **Data Container** or overwrite the current volume. +- **Input Image Geometry** -- the geometry to crop. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/CropVertexGeometryFilter.md b/src/Plugins/SimplnxCore/docs/CropVertexGeometryFilter.md index 4e4bd5ca8a..aeedb254f1 100644 --- a/src/Plugins/SimplnxCore/docs/CropVertexGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/CropVertexGeometryFilter.md @@ -2,18 +2,33 @@ ## Group (Subgroup) -DREAM3D Review (Cropping/Cutting) +Geometry (Cropping/Cutting) ## Description -This **Filter** crops a **Vertex Geometry** by the given bounding box. Unlike the cropping of an Image, it is unknown until run time how the **Geometry** will be changed by the cropping operation. Therefore, this **Filter** requires that a new **Geometry** be created to contain the cropped **Vertex Geometry**. The user-selected **Vertex** data arrays will be copied, with tuples *removed* for any **Vertices** outside the bounding box. The user must supply a name for the cropped **Geometry**, but all other copied objects will retain the same names as the original source. +This **Filter** crops a **Vertex Geometry** (a point cloud) down to the points that lie inside a user-defined, axis-aligned bounding box. The box is specified by a *Min Pos* corner and a *Max Pos* corner. Both corners are given in **physical coordinate units** (the same length units as the vertex coordinates, e.g. microns), *not* in cell or index units. -*Note:* Since it cannot be known before run time how many **Vertices** will be removed during cropping, the new **Vertex Geometry** and all associated **Vertex** data to be copied will be initialized to have size 0. +A vertex is kept when its X, Y, and Z coordinates all fall within the box. The test is **inclusive** on every face of the box: a vertex is retained when its coordinate is greater than or equal to the corresponding *Min Pos* value and less than or equal to the corresponding *Max Pos* value. Vertices on the boundary planes are therefore kept, and vertices outside any face of the box are discarded. -% Auto generated parameter table will be inserted here +Unlike cropping an **Image Geometry**, it is not known until run time how many vertices will survive the crop. Therefore this **Filter** creates a new **Vertex Geometry** to hold the cropped result rather than modifying the input in place. The user-selected vertex data arrays are copied into the new geometry with the tuples for any discarded vertices removed. The user must supply a name for the cropped geometry; all other copied objects keep the same names as in the original source. + +*Note:* Because the number of surviving vertices cannot be known before run time, the new **Vertex Geometry** and all associated vertex data to be copied are initialized to size 0 and then grown to the final size during execution. + +### Related Filters + +- [Crop Geometry (Edge)](CropEdgeGeometryFilter.md) -- crops an **Edge Geometry** to a bounding box. +- [Crop Geometry (Image)](CropImageGeometryFilter.md) -- crops an **Image Geometry** by cell index ranges. + +### Required Input Sources -## Example Pipelines +- **Vertex Geometry to Crop** -- a **Vertex Geometry** (point cloud) to be cropped. + +% Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/DBSCANFilter.md b/src/Plugins/SimplnxCore/docs/DBSCANFilter.md index 968178fe47..2de5adfdd2 100644 --- a/src/Plugins/SimplnxCore/docs/DBSCANFilter.md +++ b/src/Plugins/SimplnxCore/docs/DBSCANFilter.md @@ -28,7 +28,11 @@ Points that are in sparse regions of the data space are considered "outliers"; t The user may select from a number of options to use as the distance metric. -An advantage of DBSCAN over other clustering approaches (e.g., k-means) is that the number of clusters is not defined *a priori*. Additionally, DBSCAN is capable of finding arbitrarily shaped, nonlinear clusters, and is robust to noise. +An advantage of DBSCAN over other clustering approaches (e.g., [Compute K Means](ComputeKMeansFilter.md)) is that the number of clusters is not defined *a priori*. Additionally, DBSCAN is capable of finding arbitrarily shaped, nonlinear clusters, and is robust to noise. + +### Required Input Sources + +- **Input Data Array** -- any 2D or 3D scalar/multi-component array (other than `bool`) to be clustered. This may already exist in your **DataStructure**, or be assembled from coordinate components using [Combine Attribute Arrays](CombineAttributeArraysFilter.md) (see the **Visualization Tips** section). ### Examples @@ -67,19 +71,19 @@ This filter is designed to be applicable to any 2D or 3D array (other than bool Take note of the name of your input array referred to as `input_array` from here on, and the cluster ids array name referred to as `cluster_array` from here on. **Step 2 (2D only): Create a 1 component array of 0s named `Z`** -This can be done with the *Create Data Array* filter. **It's important to ensure the created array has the same length and type as `input_array`** +This can be done with the [Create Data Array](CreateDataArrayFilter.md) filter. **It's important to ensure the created array has the same length and type as `input_array`** **Step 3 (2D only): Merge `input_array` and `Z` array** -This can be done with the *Combine Attribute Arrays* filter. Make sure **`input_array` is above the `Z` array** in the "Attribute Arrays to Combine" parameter. **The output array will now be the new `input_array` for the following steps**, so it's recommended to enable the "Move Data" parameter to avoid confusion and keep data structure tree clean. +This can be done with the [Combine Attribute Arrays](CombineAttributeArraysFilter.md) filter. Make sure **`input_array` is above the `Z` array** in the "Attribute Arrays to Combine" parameter. **The output array will now be the new `input_array` for the following steps**, so it's recommended to enable the "Move Data" parameter to avoid confusion and keep data structure tree clean. **Step 4: Convert `input_array` to `float32` (skip step if not applicable)** -This can be done with the "Convert AttributeArray DataType" filter. Be sure to set "Scalar Type" parameter to `float32`. +This can be done with the [Convert AttributeArray DataType](ConvertDataFilter.md) filter. Be sure to set "Scalar Type" parameter to `float32`. **Step 5: Create Vertex Geometry** -This can be done with the "Create Geometry" filter. Be sure to set "Geometry Type" to `Vertex`. Your `input_array` is going to be the "Shared Vertex List", so place it in the corresponding parameter with the same name. Take note of the created "Vertex Data" *AttributeMatrix* this will be referred to as `vertex_data` in following steps. +This can be done with the [Create Geometry](CreateGeometryFilter.md) filter. Be sure to set "Geometry Type" to `Vertex`. Your `input_array` is going to be the "Shared Vertex List", so place it in the corresponding parameter with the same name. Take note of the created "Vertex Data" *AttributeMatrix* this will be referred to as `vertex_data` in following steps. **Step 6: Move the `cluster_array` into `vertex_data` *AttributeMatrix*** -This can be done with the "Move Data" filter. Place the `cluster_data` array in the "Data to Move" parameter, and place `vertex_data` in the "New Parent" parameter. +This can be done with the [Move Data](MoveDataFilter.md) filter. Place the `cluster_data` array in the "Data to Move" parameter, and place `vertex_data` in the "New Parent" parameter. **Step 7: Run the pipeline** This concludes the post-processing. @@ -98,7 +102,7 @@ This implementation of DBSCAN uses a grid approach to greatly increase the speed #### Understanding the Grid -The most important part to understand for the function to click into place is the Grid. The Grid is a regular grid that contains all the points in the input array. It serves as a way to spatially partition the dataset for processing. The voxel cells all have a side length of `Epsilon / sqaure_root(Dimensions)` where `Epsilon` is the user supplied hyperparameter and `Dimensions` is the number of components in the input array. This means that if your input array has 2 components the regular grid can be visualized as a square and 3 components can be visualized as a cube. +The most important part to understand for the function to click into place is the Grid. The Grid is a regular grid that contains all the points in the input array. It serves as a way to spatially partition the dataset for processing. The voxel cells all have a side length of `Epsilon / square_root(Dimensions)` where `Epsilon` is the user supplied hyperparameter and `Dimensions` is the number of components in the input array. This means that if your input array has 2 components the regular grid can be visualized as a square and 3 components can be visualized as a cube. #### Minimum Points @@ -108,7 +112,7 @@ This hyperparameter has outsized effects on how many cluster expansion/merge ite #### Epsilon -This hyperparameter is the basis for the entire algorithm. It actually has two separate use cases in this implementation. The first was laid out already in the **Understanding the Grid** section, as it effects the size of the voxels in the regular grid. The second is the maximum distance allowed between any two points in the input array for them to be considered density connected. As you may have perceived, these two use cases are connected, in that the voxels side length ensures all points within the same voxel satisfy the density connected requirement inherently. When preforming merge checks between voxels, every point in a grid is compared against every point in the other grid to see if there are any points that have a distance *less than* `Epsilon`. +This hyperparameter is the basis for the entire algorithm. It actually has two separate use cases in this implementation. The first was laid out already in the **Understanding the Grid** section, as it effects the size of the voxels in the regular grid. The second is the maximum distance allowed between any two points in the input array for them to be considered density connected. As you may have perceived, these two use cases are connected, in that the voxels side length ensures all points within the same voxel satisfy the density connected requirement inherently. When performing merge checks between voxels, every point in a grid is compared against every point in the other grid to see if there are any points that have a distance *less than* `Epsilon`. This hyperparameter has outsized effects on how accurate cluster result is to ground truth and what value is appropriate for `Minimum Points`. Detailed further in the **Optimization** section below. @@ -116,11 +120,11 @@ This hyperparameter has outsized effects on how accurate cluster result is to gr For `Epsilon`, ideally you want a little *a priori* knowledge on what the average distance between points in the dataset is, and start with slightly above that. However, this can be supplemented by visualizing the dataset, selecting a couple of areas you would consider clusters, finding the distance between some of the points on the edges of each of the clusters, and setting an `Epsilon` slightly above that. -For `Minimum Points`, previous recommendations suggested 1 above the dimensions of input data (for 2D - 3 and for 3D - 4). However, the density of points heavily effects this. If you have several packed regions and the rest sparse higher values are reasonable (5-9), and vise versa. **Avoid supplying a 1 as this will result in 0 unlabeled points always, unless that is knowingly the intention.** +For `Minimum Points`, previous recommendations suggested 1 above the dimensions of input data (for 2D - 3 and for 3D - 4). However, the density of points heavily effects this. If you have several packed regions and the rest sparse higher values are reasonable (5-9), and vice versa. **Avoid supplying a 1 as this will result in 0 unlabeled points always, unless that is knowingly the intention.** #### Optimization -Before any optimization, you should always try cleaning up your data. **Standardizing your data with a scaler**, such as [StandardScaler `fit_transform()` from Sci-Kit](https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.StandardScaler.html), **will make it much easier to tune the `Epsilon` parameter**. Similarly, **subtle changes in output can be caused by duplicate points in input array**. Duplicate points can be identified and removed with filters like "Identify Duplicate Vertices" and "Remove Flagged Vertices". These require your data to be in a `SharedVertexList` which is type-locked to `float32`, if typecasting is safe this can be done with steps similar to the ones laid out in the **Visualization** section. Otherwise, you may need to clean the data before import to `simplnx`. +Before any optimization, you should always try cleaning up your data. **Standardizing your data with a scaler**, such as [StandardScaler `fit_transform()` from Sci-Kit](https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.StandardScaler.html), **will make it much easier to tune the `Epsilon` parameter**. Similarly, **subtle changes in output can be caused by duplicate points in input array**. Duplicate points can be identified and removed with filters like [Identify Duplicate Vertices](IdentifyDuplicateVerticesFilter.md) and [Remove Flagged Vertices](RemoveFlaggedVerticesFilter.md). These require your data to be in a `SharedVertexList` which is type-locked to `float32`, if typecasting is safe this can be done with steps similar to the ones laid out in the **Visualization** section. Otherwise, you may need to clean the data before import to `simplnx`. Optimization is going to rely on extensive *a priori* knowledge of the data no matter what. However, this knowledge can be obtained through sequential runs of the filter and some visualization of the output. That said here is how to interpret results to optimize the speed and/or increase accuracy of output: @@ -147,7 +151,7 @@ Additionally, oddities such as duplicates in the dataset or non-standardized dat This can obviously be caused by large datasets, but it can be mitigated with some changes. Firstly, the "Parse Order" parameter can result in immediate speedups of 60% or more on a majority of datasets by switching to `Low Density First`. The idea being that lower density regions are cheaper for merge checks, so other denser core grids can be picked off early if they are close to sparser core grids, meaning that the expensive grids have less of a chance of running against one another. Another change is tightening the voxels grids by lowering the `Epsilon` and reducing the `Minimum Points` slightly. For ideal performance, in the vast majority of cases, you want to reach the lowest value for both of these that still produces expected clustering. This is because the most costly part is the distance check most of the time. Logically, grids with fewer points run less distance checks. **If your algorithm spends more time in "cluster expansion pass:" than "Identifying Qualifying Independent Clusters".** See output window. -There are many datasets that this is normal in such as `No Structure` from **Examples**. This typically happens when `Minimum Points` is too high. This results in too few Core grids being identified. Since few clusters are able to be formed, most of the time is spent in iterative loops expanding the clusters rather than just preforming the early merges in the Core grid step. +There are many datasets that this is normal in such as `No Structure` from **Examples**. This typically happens when `Minimum Points` is too high. This results in too few Core grids being identified. Since few clusters are able to be formed, most of the time is spent in iterative loops expanding the clusters rather than just performing the early merges in the Core grid step. ### Parse Order diff --git a/src/Plugins/SimplnxCore/docs/DeleteDataFilter.md b/src/Plugins/SimplnxCore/docs/DeleteDataFilter.md index 0abc965f22..8b50708bda 100644 --- a/src/Plugins/SimplnxCore/docs/DeleteDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/DeleteDataFilter.md @@ -6,7 +6,28 @@ Core (Memory/Management) ## Description -This **Filter** allows the user to remove specified objects from the existing structure. This can be helpful if the user has operations that need as much memory as possible and there are extra objects that are not needed residing in memory. Alternatively, this **Filter** allows the user to remove objects that may share a name with another object further in the **Pipeline** that another **Filter** tries to create, since DREAM3D-NX generally does not allows objects at the same hierarchy to share the same name. +This **Filter** removes one or more **Data Objects** from the **Data Structure**. Common use cases: + +- **Free memory.** When subsequent filters need as much RAM as possible and some arrays are no longer needed. +- **Avoid name collisions.** DREAM3DNX does not allow two objects at the same hierarchy level to share the same name. If a downstream filter will create an object with the same name as an existing one, delete the existing one first. +- **Clean up after extraction.** When *Move* or *Extract* options on other filters left behind unused parent containers. + +### Cascade Behavior + +Deletion is recursive on containers. Deleting a: + +- **Geometry** also deletes its child Attribute Matrices and all arrays inside them. +- **Attribute Matrix** also deletes all child arrays. +- **DataGroup** also deletes all of its children, including nested DataGroups, recursively. +- **Data Array** removes only that array. + +## WARNING: Downstream Preflight Will Fail + +Any filter later in the pipeline that references a deleted object by path will fail preflight when re-run. Delete only objects you are certain are not used downstream, or be prepared to update downstream filter parameters. + +### Required Input Sources + +- **Data Objects to Delete** -- a list of paths to existing **DataObjects** in the Data Structure. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ErodeDilateBadDataFilter.md b/src/Plugins/SimplnxCore/docs/ErodeDilateBadDataFilter.md index 4e1c68abef..fec4f37983 100644 --- a/src/Plugins/SimplnxCore/docs/ErodeDilateBadDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/ErodeDilateBadDataFilter.md @@ -6,14 +6,13 @@ Processing (Cleanup) ## Description -Bad data refers to a **Cell** that has a *Feature Id* of *0*, which means the **Cell** has failed some sort of test and -been marked as a *bad* **Cell**. +This **Filter** grows or shrinks regions of *bad data* (cells with *Feature Id = 0*) by one cell-layer per iteration, using standard image-morphology operations. It is a building block for cleaning up isolated noise or for compensating for boundaries that were systematically under- or over-measured by the experiment. + +![Fig. 1: Dilate grows the bad-data (Feature Id 0) region outward by one cell layer per iteration; Erode shrinks it, reassigning each bad cell to its majority neighbor. The Number of Iterations sets the layer count.](Images/ErodeDilateBadData_IterationSequence.png) ### Dilation -If the **bad** data is *dilated*, the Filter grows the *bad* data by one **Cell** in -an iterative sequence for a user defined number of iterations. During the *dilate* process the *Feature Id* of any -Cell neighboring a *bad* **Cell** will be changed to *0*. +*Dilate* grows the bad-data region outward. Each iteration changes any cell adjacent to a bad cell into a bad cell, adding a one-cell-thick layer. | Before Dilation | After Dilation | |--------------------------------------|--------------------------------------| @@ -21,42 +20,31 @@ Cell neighboring a *bad* **Cell** will be changed to *0*. ### Erosion -If the *bad* data is *eroded*, the Filter shrinks the -bad data by one **Cell** in an iterative sequence for a user defined number of iterations. During the *erode* process -the *Feature Id* of the *bad* **Cell** is changed from *0* to the *Feature Id* of the majority of its neighbors. If -there is a tie between two *Feature Ids*, then one of the *Feature Ids*, chosen randomly, will be assigned to the *bad* -**Cell**. +*Erode* shrinks the bad-data region. Each iteration converts each bad cell into the *Feature Id* held by the majority of its neighbors. Ties are broken randomly. Single-cell bad regions disappear in one iteration; thicker regions take more. | Before Erosion | After Erosion | |--------------------------------------|--------------------------------------| | ![](Images/ErodeDilateBadData_1.png) | ![](Images/ErodeDilateBadData_3.png) | -` - -Goals a user might be trying to accomplish with this Filter include: +### When to Use This Filter -- Remove small or thin regions of bad data by running a single (or two) iteration *erode* operation. -- Increase the size of a *bad* data region by running an *dilate* operation. This might be useful if the experimental - technique tends to underestimates the size of certain objects. For example, when running EBSD, the pores (which show - up as *bad* data) are generally smaller in the scans than in the specimen, because the beam, when it is just inside - the pore, still can pick up signal from the material just beneath the pore. +- **Erode** to remove small or thin regions of bad data — single-cell EBSD dropouts, salt-and-pepper noise. +- **Dilate** to grow under-measured features. For example, EBSD scans tend to under-estimate pore size because the beam picks up signal from material *below* the pore when it sits at the pore edge; dilating the *Feature Id = 0* region restores the true pore boundary. +- **Erode followed by Dilate** (a morphological *opening*) is the classic pattern for removing isolated noise without affecting larger regions. A single erode-dilate pair will erase isolated single-cell bad regions but return larger pores to almost their original size. +- **Dilate followed by Erode** (a morphological *closing*) fills small holes inside bad-data regions while preserving their outer boundary. -Running the *erode-dilate* operations in pairs can often change the size of some objects without affecting others. For -example, if there were a number of big pores and a number of single *bad* **Cells**, running a single *erode* operation -would remove the single **Cells** and reduce the pores by one **Cell**. If this is followed immediately by a *dilate* -operation, then the pores would grow by one **Cell** and return to near their original size, while the single **Cells** -would remain removed and not "grow back". +### Iterations and Direction -### Operation +- *Number of Iterations* is in **cell-layers**. An iteration count of 3 grows or shrinks the bad-data region by 3 cells. +- *X Direction*, *Y Direction*, and *Z Direction* toggle whether the morphology is applied along that axis. Disable an axis to perform anisotropic erosion/dilation -- useful when serial-sectioning resolution is anisotropic (typically Z is coarser than X and Y) and you want to limit smoothing along the fine axes. -The *Operation* parameter selects which morphological operation to apply: +## WARNING: Feature Data Will Become Invalid -- **Dilate [0]**: Grows bad data regions by one **Cell** per iteration. Any **Cell** neighboring a bad **Cell** has its *Feature Id* changed to 0. -- **Erode [1]**: Shrinks bad data regions by one **Cell** per iteration. Each bad **Cell** is assigned the *Feature Id* of the majority of its neighbors. +By modifying cell-level data, any feature-level data that was previously computed will most likely be invalid after this filter runs. Re-run any downstream feature-level computation filters to ensure accurate results. -## WARNING: Feature Data Will Become Invalid +### Required Input Sources -By modifying the cell level data, any feature data that was previously computed will most likely be invalid at this point. Filters that compute feature level data should be rerun to ensure accurate final results from your pipeline. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). Cells with Feature Id = 0 are treated as bad. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ErodeDilateCoordinationNumberFilter.md b/src/Plugins/SimplnxCore/docs/ErodeDilateCoordinationNumberFilter.md index 2e11f06787..d6ff9c42f5 100644 --- a/src/Plugins/SimplnxCore/docs/ErodeDilateCoordinationNumberFilter.md +++ b/src/Plugins/SimplnxCore/docs/ErodeDilateCoordinationNumberFilter.md @@ -6,23 +6,39 @@ Processing (Cleanup) ## Description -This **Filter** will smooth the interface between *good* and *bad* data. The user can specify a *coordination number*, -which is the number of neighboring **Cells** of opposite type (i.e., *good* or *bad*) compared to a given **Cell** that -is acceptable. For example, a single *bad* **Cell** surrounded by *good* **Cells** would have a *coordination number* of -*6*. The number entered by the user is actually the maximum tolerated *coordination number*. If the user entered a value -of *4*, then all *good* **Cells** with 5 or more *bad* neighbors and *bad* **Cells** with 5 or more *good* neighbors -would be removed. After **Cells** with unacceptable *coordination number* are removed, then the neighboring **Cells** -are *coarsened* to fill the removed **Cells**. - -By default, the **Filter** will only perform a single iteration and will not concern itself with the possibility that -after one iteration, **Cells** that were acceptable may become unacceptable by the original *coordination number* -criteria due to the small changes to the structure during the *coarsening*. The user can opt to enable the *Loop Until -Gone* parameter, which will continue to run until no **Cells** fail the original criteria. - -| Before Filter | After Filter | -|--------------------------------------|--------------------------------------| +This **Filter** smooths the interface between *good* and *bad* cells (or, more generally, between any two adjacent feature regions) by removing cells whose neighborhood is mostly the opposite class. It targets isolated voxels and small protrusions that are surrounded by cells of a different feature, then fills them in with their neighbors' data via isotropic coarsening. + +The *coordination number* is the count of a cell's face-sharing neighbors that belong to a different class. With 6 face neighbors, the coordination number ranges from **0 to 6**: + +- **CN = 0** -- all 6 neighbors agree with the cell. Solidly inside a region. +- **CN = 1-2** -- on a flat or gently curved feature boundary. +- **CN = 4-5** -- a thin protrusion or finger of one feature sticking into another. +- **CN = 6** -- a single isolated cell completely surrounded by another feature. + +![Fig. 1: A cell's coordination number is the count of its six face-neighbors belonging to a different feature; cells whose coordination number meets the threshold are absorbed into a neighboring feature.](Images/ErodeDilateCoordinationNumber_CoordinationNumber.png) + +| Before Filter | After Filter | +|------------------------------------------------------|-----------------------------------------------------| | ![](Images/ErodeDilateCoordinationNumber_Before.png) | ![](Images/ErodeDilateCoordinationNumber_After.png) | +### How This Filter Works + +The user specifies a *coordination number* threshold. Any cell whose coordination number is **greater than or equal to** this threshold (and greater than 0) is removed. After the offending cells are identified, neighboring features grow outward (isotropic coarsening) to fill the resulting gaps. See [Remove Minimum Size Features](RequireMinimumSizeFeaturesFilter.md) for the shared definition of isotropic coarsening. + +For example, a threshold of *4* removes any cell with 4, 5, or 6 differing neighbors (i.e., isolated voxels and thin protrusions). A threshold of *2* is much more aggressive and will erase any cell with 2 or more differing neighbors. + +### Loop Until Gone + +By default the filter performs **one** pass. After one pass, the coarsening can leave new cells whose coordination number now exceeds the threshold (because their neighbors changed). Enabling *Loop Until Gone* repeats the algorithm until no remaining cell exceeds the original criterion. Use this for full smoothing; use the single-pass mode when you want a controlled, gentle cleanup. + +### When to Use This Filter + +This is the right tool for "salt-and-pepper" cleanup -- isolated single-voxel grains, thin two-cell protrusions, and other small geometric anomalies that segmentation produced but are likely noise. It is more morphologically aware than the size-based filters because it considers neighborhood shape, not just cell count. + +### 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 diff --git a/src/Plugins/SimplnxCore/docs/ErodeDilateMaskFilter.md b/src/Plugins/SimplnxCore/docs/ErodeDilateMaskFilter.md index 8f81cd62e1..3c75c0ec61 100644 --- a/src/Plugins/SimplnxCore/docs/ErodeDilateMaskFilter.md +++ b/src/Plugins/SimplnxCore/docs/ErodeDilateMaskFilter.md @@ -6,31 +6,39 @@ Processing (Cleanup) ## Description -If the mask is _dilated_, the **Filter** grows the _true_ regions by one **Cell** in an iterative sequence for a user -defined number of iterations. During the _dilate_ process, the classification of any **Cell** neighboring a _false_ * -*Cell** will be changed to _true_. If the mask is _eroded_, the **Filter** shrinks the _true_ regions by one **Cell** in -an iterative sequence for a user defined number of iterations. During the _erode_ process, _true_ **Cells** that have -at least one _false_ neighbor are changed to _false_. The **Filter** also offers the option(s) to -turn on/off the erosion or dilation in specific directions (X, Y or Z). +This **Filter** grows or shrinks the *true* region of a boolean *mask* array by one cell-layer per iteration, using standard image-morphology operations. The mask is a cell-level boolean array (typically produced by a threshold operation such as [Multi-Threshold Objects](MultiThresholdObjectsFilter.md)) where *true* marks cells of interest and *false* marks excluded cells. -This filter will ONLY change the _Mask_ data array and not any of the other data arrays in the same attribute matrix. +Only the **Mask** array is modified; no other cell data is changed. -The example images below were generated **AFTER** the execution of the filter and essentially any black pixel is where the **Mask** was false and any other color is where the **Mask** is true. (The colors are the typical IPF Colors using a <001> reference direction) +The example images below show the IPF-colored data after the filter has run. Black pixels are cells where the mask is *false*; colored pixels are where the mask is *true*. -| Before Dilatation | After Dilation | -|--------------------------------------|--------------------------------------| +| Before Dilation | After Dilation | +|----------------------------------------|----------------------------------------| | ![](Images/ErodeDilateMask_Before.png) | ![](Images/ErodeDilateMask_Dilate.png) | -| Before Erosion | After Erosion | -|--------------------------------------|--------------------------------------| -| ![](Images/ErodeDilateMask_Before.png) | ![](Images/ErodeDilateMask_Erode.png) | +| Before Erosion | After Erosion | +|----------------------------------------|----------------------------------------| +| ![](Images/ErodeDilateMask_Before.png) | ![](Images/ErodeDilateMask_Erode.png) | -### Operation +### When to Use This Filter -The *Operation* parameter selects which morphological operation to apply to the mask: +- **Erode** the mask to discard the boundary layer of valid cells. Useful before computing feature-level statistics from EBSD data, since cells right at the sample edge are often unreliable even after passing a quality threshold. +- **Dilate** the mask to recover cells that were marked invalid by an over-aggressive threshold but lie immediately adjacent to valid data. -- **Dilate [0]**: Expands the masked (true) regions by one **Cell** per iteration. Any **Cell** neighboring a false **Cell** is changed to true. -- **Erode [1]**: Shrinks the masked (true) regions by one **Cell** per iteration. True **Cells** that have at least one false neighbor are changed to false. +### Opening and Closing + +Chaining an erode and a dilate pass (with equal iteration counts) performs the two classic compound morphology operations: + +![Fig. 1: Opening (erode then dilate) removes small isolated true regions and thin protrusions while returning the larger region to about its original size; Closing (dilate then erode) fills small holes and gaps while preserving the outer boundary.](Images/Morphology_OpeningClosing.png) + +### Iterations and Direction + +- *Number of Iterations* is in **cell-layers**. An iteration count of 3 grows or shrinks the *true* region by 3 cells. +- *X Direction*, *Y Direction*, and *Z Direction* toggle whether the morphology is applied along that axis. Disable an axis to perform anisotropic morphology -- useful when serial-sectioning resolution is anisotropic (typically Z is coarser than X and Y) and you want to limit growth or shrinking along the fine axes. + +### Required Input Sources + +- **Mask Array** -- a boolean cell-level array, typically produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md) applied to an EBSD confidence index, image quality, or similar scalar. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ExecuteProcessFilter.md b/src/Plugins/SimplnxCore/docs/ExecuteProcessFilter.md index feaeda0d5e..7f1f992b43 100644 --- a/src/Plugins/SimplnxCore/docs/ExecuteProcessFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExecuteProcessFilter.md @@ -22,6 +22,17 @@ For a command with spaces in the path > "C:/Program Files/DREAM3D-6.6.332/nxrunner.exe" "C:/Program Files/DREAM3D-6.6.332/PrebuiltPipelines/Workshop/EBSD Reconstruction/(01) SmallIN100 Archive.json" +The path to the executable should be given as an **absolute path**; relative paths and shell built-ins that are resolved by a particular shell are not reliable across platforms. + +### Blocking and Timeout + +- **Should Block**: When enabled, the **Filter** waits for the launched process to finish (or to start, on platforms where that distinction applies) before the pipeline continues. When disabled, the process is launched and the pipeline moves on without waiting. +- **Timeout (ms)**: Only applies when *Should Block* is enabled. It is the maximum time, in milliseconds, that the **Filter** will wait for the command before giving up. + +### Required Input Sources + +None -- this **Filter** launches an external program and does not consume any **DataStructure** objects. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ExtractComponentAsArrayFilter.md b/src/Plugins/SimplnxCore/docs/ExtractComponentAsArrayFilter.md index 30df3ed16f..b286df21aa 100644 --- a/src/Plugins/SimplnxCore/docs/ExtractComponentAsArrayFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExtractComponentAsArrayFilter.md @@ -6,11 +6,23 @@ Core (Memory/Management) ## Description -This **Filter** will do one of the following to one component of a multicomponent **Attribute Array**: +This **Filter** operates on a single component of a multicomponent **Attribute Array**, supporting three modes of behavior: -- Remove 1 component from multicomponent **Attribute Array** completely [This is done implicitly so long as **Move Extracted Components To New Array** is false] -- Extract 1 component from multicomponent **Attribute Array** and store it in a new **DataArray** without removing from original -- Extract 1 component from multicomponent **Attribute Array** and store it in a new **DataArray** and remove that component from the original +- **Remove only** (default): the selected component is deleted from the source array; no new array is created. +- **Extract only** (*Move Extracted Components To New Array* = true, *Remove from Original* = false): the selected component is copied into a new scalar **DataArray**; the source array is unchanged. +- **Extract and remove** (*Move Extracted Components To New Array* = true, *Remove from Original* = true): the selected component is moved into a new scalar **DataArray** and removed from the source. + +### Component Indexing + +The component selector is **0-based**. For a 3-component array, valid component indices are 0, 1, and 2. + +### When to Use This Filter + +Use to pull a single channel out of a color image (e.g., extract R from an RGB array), strip a known-bad component from a tensor, or split one specific component while leaving the rest intact. For splitting *all* components into separate arrays at once, use [Split Data Array (By Component)](SplitDataArrayByComponentFilter.md) instead. + +### Required Input Sources + +- **Source Multi-Component Array** -- any **Attribute Array** with two or more components. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ExtractFeatureBoundaries2DFilter.md b/src/Plugins/SimplnxCore/docs/ExtractFeatureBoundaries2DFilter.md index dec668a45e..3b8dd4d2dc 100644 --- a/src/Plugins/SimplnxCore/docs/ExtractFeatureBoundaries2DFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExtractFeatureBoundaries2DFilter.md @@ -2,49 +2,56 @@ ## Group (Subgroup) -SimplnxCore (Geometry) +Surface Meshing (Generation) ## Description -This **Filter** extracts 2D feature boundaries from an Image Geometry and creates an Edge Geometry representing the outlines of features defined by a Feature IDs array. The filter operates only in the XY plane and requires the input Image Geometry to have a Z dimension of 1. +This **Filter** extracts the 2D boundaries between **Features** in an **Image Geometry** and builds an **Edge Geometry** that traces the outlines of those features. An **Image Geometry** is a regular grid of rectangular cells (pixels in 2D). A **Feature** is a connected region of cells that share the same identifier, recorded in a **Feature IDs** array (one integer label per cell). An **Edge Geometry** is a node-based geometry made of straight line segments (edges); here each edge lies on the interface between two cells that belong to different features. -**NOTE**: The "FeatureIds" array can be any integer type, not just `signed int32` as is the typical featureIds arrays. This means that it can work immediately on scalar images that have not been segmented already. The user could use a basic threshold to create a unsigned int 8 mask value, then use that mask value as the input into this filter. This could be used, for example, to outline just the sample border if there is overscan or just outline specific regions of a 2D Image Geometry. +The filter operates only in the XY plane and requires the input **Image Geometry** to have a Z dimension of 1 (a single slice). -The algorithm scans the Feature IDs array and identifies boundaries where adjacent cells have different feature IDs. For each boundary, an edge (line segment) is created at the cell interface. The resulting Edge Geometry contains: +**NOTE**: The Feature IDs array can be any integer type, not just the *signed int32* type used by typical feature-id arrays. This means it can operate directly on scalar images that have not been segmented. For example, the user could run a simple threshold to create a *uint8* mask (a boolean per-cell flag stored as 0/1) and feed that mask in as the Feature IDs input. This is useful for outlining just the sample border when there is **overscan** — extra collected area surrounding the actual sample — or for outlining specific regions of a 2D **Image Geometry**. + +The algorithm scans the Feature IDs array and identifies boundaries where adjacent cells have different feature IDs. For each such boundary, an edge (line segment) is created along the shared cell interface. The resulting **Edge Geometry** contains: - **Shared Vertex List**: 3D coordinates of all unique vertices at feature boundaries -- **Shared Edge List**: Connectivity pairs defining line segments between vertices +- **Shared Edge List**: connectivity pairs defining the line segments between those vertices ### Z Value Source The *Z Value Source* parameter provides the following choices: -- **Use min z value from Image geometry [0]**: Uses the origin Z value of the input Image Geometry as the Z coordinate for all generated vertices. -- **Use max z value from Image geometry [1]**: Uses the origin Z plus the spacing times the Z dimension as the Z coordinate for all generated vertices. -- **Use Custom z Offset [2]**: Allows the user to specify an arbitrary Z coordinate value for all generated vertices. +- *Use min z value from Image geometry [0]*: Uses the origin Z value of the input **Image Geometry** as the Z coordinate for all generated vertices. +- *Use max z value from Image geometry [1]*: Uses the origin Z plus the spacing times the Z dimension as the Z coordinate for all generated vertices. +- *Use Custom z Offset [2]*: Lets the user specify an arbitrary Z coordinate value for all generated vertices. ### Algorithm Details The algorithm uses a two-pass approach for efficiency: -1. **Count Pass**: Scan to count the total number of boundary edges (both vertical and horizontal) -2. **Populate Pass**: Creation of vertices and edge connectivity +1. **Count Pass**: Scans to count the total number of boundary edges (both vertical and horizontal). +2. **Populate Pass**: Creates the vertices and edge connectivity. After edge creation, duplicate vertices are eliminated to ensure a clean, connected edge network. ## Example Output -![Images/ExtractFeatureBoundaries2D_1.png](Images/ExtractFeatureBoundaries2D_1.png) +![Example feature boundaries extracted as an Edge Geometry.](Images/ExtractFeatureBoundaries2D_1.png) + +### Required Input Sources + +- **Image Geometry** -- a 2D **Image Geometry** (Z dimension of 1) holding the Feature IDs. +- **Feature IDs** -- a per-cell integer array. It may be a true segmentation produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md), or any per-cell integer/mask array produced by a thresholding filter such as [Multi-Threshold Objects](MultiThresholdObjectsFilter.md). % Auto generated parameter table will be inserted here ## Example Pipelines -- ExtractFeatureBoundaries2D.d3dpipline +- ExtractFeatureBoundaries2D.d3dpipeline ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ExtractInternalSurfacesFromTriangleGeometryFilter.md b/src/Plugins/SimplnxCore/docs/ExtractInternalSurfacesFromTriangleGeometryFilter.md index 90fd3d3b71..edee05406d 100644 --- a/src/Plugins/SimplnxCore/docs/ExtractInternalSurfacesFromTriangleGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExtractInternalSurfacesFromTriangleGeometryFilter.md @@ -6,13 +6,15 @@ Geometry ## Description -This **Filter** extracts any **Triangles** from the supplied **Triangle Geometry** that contain any *internal nodes*, then uses these extracted **Triangles** to create a new **Data Container** with the reduced **Triangle Geometry**. This operation is the same as removing all **Triangles** that only lie of the outer surface of the supplied **Triangle Geometry**. The user must supply a "Node Type" **Vertex Attribute Array** that defines the type for each node of the **Triangle Geometry**. Node types may take the following values: +This **Filter** extracts the **Triangles** from a **Triangle Geometry** that contain *internal nodes*, and uses those extracted **Triangles** to create a new **Triangle Geometry** in a new data group. This is equivalent to removing every **Triangle** that lies only on the outer surface of the supplied **Triangle Geometry**. + +The user must supply a "Node Type" **Vertex Attribute Array** that classifies each node of the **Triangle Geometry**. This node-type array is normally created when the original surface mesh is generated by [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). The node types may take the following values: ### Quick Surface Mesh | Id Value | Node Type | |----------|-----------| -| 2 | Normal **Vertex | +| 2 | Normal **Vertex** | | 3 | Triple Line | | 4 | Quadruple Point | | 12 | Normal **Vertex** on the outer surface | @@ -23,21 +25,28 @@ This **Filter** extracts any **Triangles** from the supplied **Triangle Geometry | Id Value | Node Type | |----------|-----------| -| 0 | Normal **Vertex | +| 0 | Normal **Vertex** | | 3 | Triple Line | | 4-8 | Quadruple Point | | 13 | Normal **Vertex** on the outer surface | | 14 | Triple Line on the outer surface | | 15-18 | Quadruple Point on the outer surface | -This **Filter** has the effect of removing any **Triangles** that only contain **Vertices** whose node Id values fall outside of the min and max that the user sets. In general, this *node type* array is created when the original surface mesh is created. +This **Filter** removes any **Triangle** that contains only **Vertices** whose node Id values fall outside the minimum and maximum that the user sets. It is unknown until runtime how the **Geometry** will be changed by removing certain **Vertices** and **Triangles**. -% Auto generated parameter table will be inserted here +### Required Input Sources + +- **Triangle Geometry** -- the surface mesh to process, typically produced by [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Node Types** -- the per-vertex node classification array, produced by the same surface-meshing filter that created the geometry. -## Example Pipelines +% Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/ExtractPipelineToFileFilter.md b/src/Plugins/SimplnxCore/docs/ExtractPipelineToFileFilter.md index 5c9dce5bb0..ed034916f1 100644 --- a/src/Plugins/SimplnxCore/docs/ExtractPipelineToFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExtractPipelineToFileFilter.md @@ -1,9 +1,19 @@ # Extract DREAM3D-NX Pipeline To File +## Group (Subgroup) + +IO (Output) + ## Description This **Filter** reads the pipeline from an hdf5 file with the .dream3d extension and writes it back out to a json formatted pipeline file with the appropriate extension based on whether the pipeline is a DREAM3D-NX version 6 (.json) or DREAM3D-NX version 7 (.d3dpipeline) formatted pipeline. +A `.dream3d` file *may* contain an embedded copy of the pipeline that produced it, but this is not guaranteed (for example, files written by external tools, or written with pipeline embedding disabled, will not have one). If the selected `.dream3d` file does not contain an embedded pipeline, this **Filter** has nothing to extract and will report an error rather than write an empty file. + +### Required Input Sources + +None -- the input is a `.dream3d` file selected by file path, not a **DataStructure** object created by an upstream filter. + % Auto generated parameter table will be inserted here ## Example Pipelines @@ -12,4 +22,8 @@ ExtractPipelineToFile ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/ExtractVertexGeometryFilter.md b/src/Plugins/SimplnxCore/docs/ExtractVertexGeometryFilter.md index 2e03705bae..a4acf93c72 100644 --- a/src/Plugins/SimplnxCore/docs/ExtractVertexGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/ExtractVertexGeometryFilter.md @@ -6,13 +6,17 @@ Core Filters (Geometry) ## Description -This filter will extract all the voxel centers of an Image Geometry or a RectilinearGrid geometry -into a new Vertex Geometry. The user is given the option to copy or move cell arrays over to the -newly created VertexGeometry. The user can also supply a mask array which has the effect of only +This filter will extract all the voxel centers of an **Image Geometry** or a **Rectilinear Grid Geometry** +into a new **Vertex Geometry**. The user is given the option to copy or move cell arrays over to the +newly created **Vertex Geometry**. The user can also supply a mask array which has the effect of only creating a vertex if the mask value = TRUE. ![Example showing the use of a Mask array to only generate specific points.](Images/ExtractVertexGeometry_1.png) +### Required Input Sources + +- **Image Geometry** or **Rectilinear Grid Geometry** -- the grid whose voxel/cell centers will be extracted as vertices. + ### Array Handling The *Array Handling* parameter controls how the selected cell arrays are transferred to the new **Vertex Geometry**: diff --git a/src/Plugins/SimplnxCore/docs/FeatureFaceCurvatureFilter.md b/src/Plugins/SimplnxCore/docs/FeatureFaceCurvatureFilter.md index dde27f2b8c..b74f8388b6 100644 --- a/src/Plugins/SimplnxCore/docs/FeatureFaceCurvatureFilter.md +++ b/src/Plugins/SimplnxCore/docs/FeatureFaceCurvatureFilter.md @@ -6,28 +6,33 @@ Surface Meshing (Curvature) ## Description -This **Filter** calculates *principal direction vectors* and the *principal curvatures*, and optionally the *mean* and *Gaussian* curvature, for each **Triangle** in a **Triangle Geometry** using the technique in [1]. The groups of **Triangles** over which to compute the curvatures is determines by the **Features** they are associated, denoted by their **Face Labels**. The curvature information will be stored in a **Face Attribute Matrix**. +This filter calculates *principal direction vectors* and the *principal curvatures*, and optionally the *mean* and *Gaussian* curvature, for each **Triangle** in a **Triangle Geometry** (a surface mesh built from triangles) using the technique in [1]. The groups of **Triangles** over which to compute the curvatures are determined by the **Features** they belong to, as denoted by their **Face Labels** (the pair of **Feature** Ids on either side of each triangle). The curvature information is stored in a **Face Attribute Matrix**. -Principal Curvatures 1 and 2 are the κ 1 and κ 2 from [1] and are the eigenvalues from the Wiengarten matrix. The Principal Directions 1 and 2 are the eigenvectors from the solution to the least squares fit algorithm. The Mean Curvature is (κ 1 + κ 2 ) / 2, while the Gaussian curvature is (κ 1 * -κ 2 ). +**Curvature** measures how sharply the surface bends at a point: a flat region has zero curvature, while a tightly rounded region has high curvature. The *principal curvatures* are the maximum and minimum bending values at a point, and the *principal directions* are the (unit) directions along the surface in which those extreme bends occur. -The values of the principal directions can have their signs flipped. They are calculated using eigenvectors which are unique up to a sign. +Principal Curvatures 1 and 2 are the κ1 and κ2 from [1] and are the eigenvalues of the Weingarten matrix. The Principal Directions 1 and 2 are the eigenvectors from the solution to the least-squares fit. The Mean Curvature is (κ1 + κ2) / 2, while the Gaussian curvature is (κ1 * κ2). + +The principal directions can have their signs flipped: they come from eigenvectors, which are unique only up to a sign. *Note*: Computing the Weingarten matrix values is an experimental feature, and there is no guarantee at this time that the values are correct. +### Units + +Principal curvatures and mean curvature are reported in **1/length** (the reciprocal of the geometry length units; the radius of the best-fit circle is its reciprocal). Gaussian curvature, being a product of two curvatures, is reported in **1/length^2**. Principal directions are **dimensionless** unit 3-vectors. + ![Curvature Coloring](Images/FeatureFaceCurvatureFilter_3.png) -@image latex FeatureFaceCurvatureFilter.png "Curvature Coloring of a Feature" width = 6in ## Ring Neighbor Schematic ![Ring Neighbor Schematic](Images/FeatureFaceCurvatureFilter_1.png) -## Parameter Notes: - -- The "Feature Face Ids" input data can be computed from the "Compute Triangle Face Ids" filter -- The "Face Normals" input data can be computed from the "Compute Triangle Normals" filter -- The "Face Centroids" input data can be computed from the "Compute Triangle Centroids" filter +### Required Input Sources +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** -- the per-triangle pair of **Feature** Ids, produced alongside the mesh by the surface-meshing filter above. +- **Feature Face Ids** -- computed by [Compute Triangle Face Ids](SharedFeatureFaceFilter.md). +- **Face Normals** -- computed by [Compute Triangle Normals](TriangleNormalFilter.md). +- **Face Centroids** -- computed by [Compute Triangle Centroids](TriangleCentroidFilter.md). % Auto generated parameter table will be inserted here @@ -37,13 +42,13 @@ The values of the principal directions can have their signs flipped. They are ca ## Example Pipelines -- Pipelines -> SimplnxCore -> Compute_Feature_Face_Curvature -- Pipelines -> SimplnxCore -> Compute_Feature_Face_Curvature_2 +- Compute_Feature_Face_Curvature +- Compute_Feature_Face_Curvature_2 ## License & Copyright -Please see the description file distributed with this**Plugin** +Please see the description file distributed with this **Plugin** -## DREAM3D-NX Mailing Lists +## DREAM3D-NX Help -If you need more help with a**Filter**, please consider asking your question on the [DREAM3D-NX Users Google group!](https://groups.google.com/forum/?hl=en#!forum/dream3d-users) +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/FillBadDataFilter.md b/src/Plugins/SimplnxCore/docs/FillBadDataFilter.md index ac1f800efc..2eb2d2cb2a 100644 --- a/src/Plugins/SimplnxCore/docs/FillBadDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/FillBadDataFilter.md @@ -6,45 +6,47 @@ Processing (Cleanup) ## Description -This **Filter** removes small *noise* in the data but keeps larger regions that are possibly **Features**, e.g., pores or defects. This **Filter** identifies *bad* **Cells** (*Feature Id = 0*) and fills small defects by copying data from neighboring good cells, while preserving large defect regions that meet or exceed the minimum allowed defect size specified by the user. +This **Filter** distinguishes small *bad-data noise* from large *real defects* in a segmented dataset and fills only the noise. **Cells** with *Feature Id = 0* are considered *bad*; the filter groups them into connected components, classifies each component by its size, and fills components below the user threshold by copying the most common neighbor's data into them. Components at or above the threshold are left intact, since they likely represent real features (pores, cracks, voids). | Small IN100 Before | Small IN100 After | |--------------------------------------|-------------------------------------| | ![](Images/fill_bad_data_before.png) | ![](Images/fill_bad_data_after.png) | -The above images show the before and after results of running this filter with a minimum defect size of 1000 voxels. Note that because the minimum defect size was set to 1000 voxels that the over scan area was not modified (the area in all black around the sample). +The above images show the before and after results of running this filter with a minimum defect size of 1000 voxels. The all-black overscan area around the sample exceeds the 1000-voxel threshold, so it is correctly preserved. -## Algorithm Overview +### How This Filter Works -The filter uses a four-phase algorithm optimized for both in-memory and out-of-core data processing: +1. **Connected components.** All bad cells (*Feature Id = 0*) are grouped into connected regions using face neighbors. +2. **Classify by size.** + - Components with fewer than *Minimum Allowed Defect Size* cells are flagged as *small noise* and filled. + - Components with at least *Minimum Allowed Defect Size* cells are kept as bad data, or optionally moved to a new phase if *Store Defects as New Phase* is enabled. +3. **Iterative fill.** Each cell flagged for filling examines its 6 face neighbors and copies all cell-level array data from whichever neighbor's *Feature Id* is most common. The pass repeats until every flagged cell has been filled. -### Phase 1: Connected Component Labeling (CCL) -The algorithm first identifies all connected regions of bad data (voxels with Feature Id = 0) using a chunk-sequential scanline algorithm. Each connected component is assigned a unique provisional label, and equivalences between components that span chunk boundaries are tracked using a Union-Find data structure. +### Minimum Defect Size Units -### Phase 2: Global Resolution -All provisional labels are resolved to their root representatives, and the total size (voxel count) of each connected component is computed by aggregating counts across all chunks. +The *Minimum Allowed Defect Size* is in **cells** (integer voxel count), not physical units. To convert a physical-volume threshold into a cell count, divide by the cell volume (dx * dy * dz). -### Phase 3: Classification and Relabeling -Each connected component is classified based on its size: -- **Small defects** (size < minimum allowed defect size): Marked with Feature Id = -1 for filling -- **Large defects** (size ≥ minimum allowed defect size): Retained as Feature Id = 0 (or assigned to a new phase if requested) +Choose the threshold based on what you want to keep: -### Phase 4: Iterative Morphological Fill -Small defects are filled using an iterative erosion process: -1. For each voxel marked for filling (Feature Id = -1), examine its 6 face-connected neighbors -2. Determine the most common positive Feature Id among the neighbors -3. Copy all cell array data from that neighbor to the current voxel -4. Repeat until all small defects are filled +- For removing single-cell or small-cluster EBSD scan noise, **5-50 cells** is typical. +- For preserving real pores while cleaning small noise (as in the example above), thresholds of **500-5000 cells** depend on pore size. -The algorithm processes data in a chunk-sequential manner, making it efficient for large datasets stored using out-of-core data structures. +### Store Defects as New Phase -## Performance Characteristics +When this option is enabled, any connected component that meets or exceeds the size threshold has its cells reassigned to a new phase index rather than being left as Feature Id 0. This makes large defects available to downstream filters as a distinct phase (e.g., for separate statistics or visualization). -This implementation is optimized for out-of-core processing where data may reside on disk rather than in memory. The chunk-sequential access pattern minimizes disk I/O operations compared to random-access algorithms, providing significant performance improvements for large datasets (10-100x faster for typical use cases with out-of-core storage). +### Performance Note + +The implementation is chunk-sequential and optimized for out-of-core data. For large datasets stored on disk, expect 10-100x speedups over random-access algorithms. ## WARNING: Feature Data Will Become Invalid -By modifying the cell level data, any feature data that was previously computed will most likely be invalid at this point. Filters that compute feature level data should be rerun to ensure accurate final results from your pipeline. +By modifying cell-level data, any feature-level data that was previously computed (sizes, centroids, average orientations, etc.) will most likely be invalid after this filter runs. Re-run any downstream feature-level computation filters to ensure accurate results. + +### 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). Cells with Feature Id = 0 are treated as bad. +- **Cell Phases** -- typically read from EBSD data; only required when *Store Defects as New Phase* is enabled. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/FlyingEdges3DFilter.md b/src/Plugins/SimplnxCore/docs/FlyingEdges3DFilter.md index 2afbb9becc..540f4a38e9 100644 --- a/src/Plugins/SimplnxCore/docs/FlyingEdges3DFilter.md +++ b/src/Plugins/SimplnxCore/docs/FlyingEdges3DFilter.md @@ -6,11 +6,29 @@ Visual Analysis ## Description -This filter will draw a 3 dimensional contouring surface through an Image Geometry based on an input value. +This filter generates a 3D **isosurface** (a contour surface) through the scalar values stored on an **Image Geometry**, and saves it as a **Triangle Geometry**. -Here's what the results look like: +### What is an Isosurface? -![3D-Contouring](Images/FlyingEdges3D_1.png) +An **isosurface** is the 3D equivalent of a contour line on a topographic map. Given a scalar value at every **Cell** of a volume (for example density from a CT scan, or a distance field), the isosurface is the connected surface that passes through every point where the scalar equals a chosen threshold — the *Contour Value* (also called the isovalue). Cells with values above the threshold fall on one side of the surface; cells below fall on the other. + +"Flying Edges" is a fast, parallel variant of the classic marching-cubes algorithm. It produces the same triangulated surface but scans the volume more efficiently. + +### When to Use This Filter + +Use this filter to extract a smooth surface from continuous scalar data (CT density, a level-set/distance field, simulation output). If the goal is instead to build a surface mesh around labeled regions (**Feature** Ids from a segmentation), use [Surface Nets](SurfaceNetsFilter.md) or [Quick Surface Mesh](QuickSurfaceMeshFilter.md), which contour an integer label map rather than a continuous field. + +### Parameter Guidance + +- **Contour Value** — the scalar threshold the surface is drawn at. Its units are the same as the selected **Data Array** (for CT data, density units; for a distance field, length units). The surface only appears where the data actually crosses this value, so the value must lie within the array's range. +- **Data Array to Contour** — the per-Cell scalar field the contour is computed from. + +### Required Input Sources + +- **Image Geometry** -- the volume to contour, typically from an image/volume reader such as [Read Image](ReadImageFilter.md) or an upstream processing filter. +- **Data Array to Contour** -- any single-component scalar **Cell Data** array on that geometry. + +![A 3D contour surface extracted from an Image Geometry at the chosen Contour Value.](Images/FlyingEdges3D_1.png) % Auto generated parameter table will be inserted here @@ -18,6 +36,6 @@ Here's what the results look like: Please see the description file distributed with this **Plugin** -## DREAM3D-NX Interaction +## DREAM3D-NX Help -If you need more help with a **Filter**, please consider asking your question on the [DREAM3D-NX Help Forum!](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/HierarchicalSmoothFilter.md b/src/Plugins/SimplnxCore/docs/HierarchicalSmoothFilter.md index a0538686fc..64aa6d22e5 100644 --- a/src/Plugins/SimplnxCore/docs/HierarchicalSmoothFilter.md +++ b/src/Plugins/SimplnxCore/docs/HierarchicalSmoothFilter.md @@ -97,15 +97,7 @@ This safety mechanism prevents the smoothing from producing mesh artifacts in re ![](Images/HierarchicalSmooth_error_threshold.png) -## Parameters - -| Name | Type | Description | Default | -|------|------|-------------|---------| -| Max Bisection Iterations | Int32 | Maximum number of bisection iterations for smoothing parameter optimization (see above) | 53 | -| Error Threshold | Float64 | Displacement rejection threshold as a multiple of the reference edge length (see above) | 2.0 | -| Triangle Geometry | Geometry Selection | The triangle geometry to smooth | - | -| Node Type | Array Selection (Int8, 1-comp) | Array specifying node type (2=interior, 3=triple, 4=quad; +10 for surface) | - | -| Face Labels | Array Selection (Int32, 2-comp) | Array specifying grain IDs on either side of each face | - | +In addition to the two numeric parameters described above, the filter requires the **Triangle Geometry** to smooth, a per-vertex **Node Type** array (Int8, single-component: 2 = interior, 3 = triple line, 4 = quad point; add 10 for the outer-surface variants), and a per-face **Face Labels** array (Int32, 2-component) giving the grain IDs on either side of each face. These three inputs are normally produced together by a surface-meshing filter. Unlike simple [Laplacian Smoothing](LaplacianSmoothingFilter.md), this filter uses the **Node Type** and **Face Labels** information to respect the topological hierarchy of the boundary network. ## Notes @@ -115,6 +107,10 @@ This safety mechanism prevents the smoothing from producing mesh artifacts in re - The conjugate gradient solver handles its own internal convergence; the max iterations parameter controls only the bisection search for the optimal smoothing parameter, not the CG solver iterations. - If the filter reports rejected nodes, consider increasing the Error Threshold or inspecting the input mesh for degenerate triangles near the rejected vertices. +## Required Input Sources + +- **Triangle Geometry**, **Node Type**, and **Face Labels** -- a polycrystalline surface mesh and its node-type and face-label arrays, produced together by a surface-meshing filter such as [Quick Surface Mesh](QuickSurfaceMeshFilter.md). + % Auto generated parameter table will be inserted here ## Reference @@ -122,12 +118,10 @@ This safety mechanism prevents the smoothing from producing mesh artifacts in re - S. Maddali, "HierarchicalSmooth" - Topology-aware smoothing for polycrystalline grain boundary networks. Carnegie Mellon University, 2016-2018. - S. Maddali, S. Ta'asan, R. M. Suter, Topology-faithful nonparametric estimation and tracking of bulk interface networks, Computational Materials Science 125, 328-340 (2016). -## Example Pipelines - ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** -## DREAM3D Mailing Lists +## DREAM3D-NX Help If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/IdentifyDuplicateVerticesFilter.md b/src/Plugins/SimplnxCore/docs/IdentifyDuplicateVerticesFilter.md index c93944fc51..52eeb1d9c7 100644 --- a/src/Plugins/SimplnxCore/docs/IdentifyDuplicateVerticesFilter.md +++ b/src/Plugins/SimplnxCore/docs/IdentifyDuplicateVerticesFilter.md @@ -6,7 +6,9 @@ Meshing (Cleanup) ## Description -This filter takes a geometry with a **SharedVertexList** and produces a `uint8` mask that contains `1` in positions where a duplicate of an existing vertex exists. It should be noted that this filter utilizes quicksort to speed up checks, quick sort is not a stable sort meaning the vertex point deemed "unique" (ie not labeled as a duplicate) is not guaranteed to be the first instance of the vertex point. See example section below for a visual explanation. The intention is for this filters output to be used as the input for *RemoveFlaggedVertices*. +This filter takes a geometry with a **SharedVertexList** and produces a `uint8` mask that contains `1` at the position of each vertex that duplicates an earlier vertex, and `0` otherwise. Two vertices are considered **duplicates** when their X, Y, and Z coordinates are all equal (the comparison treats coordinate differences smaller than machine epsilon as equal, so this is effectively exact coordinate equality); no user-supplied tolerance is applied. + +It should be noted that this filter utilizes quicksort to speed up checks. Quicksort is not a stable sort, meaning the vertex deemed "unique" (i.e., not labeled as a duplicate) is not guaranteed to be the first instance of that coordinate in the original list. See the example below, which uses small text arrays to illustrate this behavior. The intention is for this filter's output to be used as the input for [Remove Flagged Vertices](RemoveFlaggedVerticesFilter.md). ## Example diff --git a/src/Plugins/SimplnxCore/docs/IdentifySampleFilter.md b/src/Plugins/SimplnxCore/docs/IdentifySampleFilter.md index 333175f841..dfa14deb64 100644 --- a/src/Plugins/SimplnxCore/docs/IdentifySampleFilter.md +++ b/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 diff --git a/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.png b/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.png new file mode 100644 index 0000000000..e6b436d53d Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.svg b/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.svg new file mode 100644 index 0000000000..76ecb0ab91 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ApplyTransformationToGeometry_AxisAngle.svg @@ -0,0 +1,59 @@ + + + + + + + + + + Rotation by axis and angle + Apply Transformation to Geometry — the "Rotation" transform type + + + + + + + n = (x, y, z) + rotation axis + + + + before + + + after + + + θ + + + + + + Rotation parameter + rotation = [ x, y, z, θ° ] + unit axis (x, y, z) + angle θ in degrees + + + + + + + i + A true geometric transform — the geometry + actually moves (image geometries are re-gridded + and interpolated). To rotate the coordinate frame + instead, use Rotate Sample Reference Frame. + + + + + + + Transformation Type also offers Translation, + Scale, a manual 4×4 matrix, or a precomputed + transformation matrix. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.png b/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.png new file mode 100644 index 0000000000..c9687af8b0 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.svg b/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.svg new file mode 100644 index 0000000000..5429026176 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ComputeFeatureSizes_EquivalentDiameter.svg @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + Equivalent Sphere Diameter + The diameter of the sphere with the same volume as the feature + + + + + + + + + Feature (grain) + V = (# cells) × (voxel volume) + + + + equal volume + + + + + d + Equivalent sphere + + + + + d = 2 · ( 3V / 4π )1/3 + + + + + + + If the image is 2D (one dimension = 1), an Equivalent Circular Diameter is computed instead, + from the feature area: d = 2 · √( A / π ). + Outputs: EquivalentDiameters, Volumes, NumElements (per feature). + + diff --git a/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.png b/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.png new file mode 100644 index 0000000000..689c90abe8 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.svg b/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.svg new file mode 100644 index 0000000000..a3f170a6ee --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/CreateGeometry_GeometryTypes.svg @@ -0,0 +1,103 @@ + + + The eight geometry types + Create Geometry builds each type from the data that defines it + + + + + + + + + + Image + origin + spacing + dimensions + + + + + + + + + + + Rectilinear Grid + X / Y / Z bounds arrays + + + + + + + + + + + Vertex + vertex list (points) + + + + + + + + + + Edge + vertices + edges (2 nodes) + + + + + + + + Triangle + vertices + triangles (3 nodes) + + + + + + + + Quadrilateral + vertices + quads (4 nodes) + + + + + + + + + + + + Tetrahedral + vertices + tets (4 nodes) + + + + + + + + + + + + + + + + + + + Hexahedral + vertices + hexes (8 nodes) + + diff --git a/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.png b/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.png new file mode 100644 index 0000000000..00e09704ef Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.svg b/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.svg new file mode 100644 index 0000000000..0987bb21f7 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/CreateImageGeometry_OriginSpacingDimensions.svg @@ -0,0 +1,54 @@ + + + + + + + + Image Geometry: origin, spacing, dimensions + A regular grid fully defined by three 3-vectors + + + + + + + + + + + + dimensions X = 5 cells + + + + dimensions Y = 4 cells + + + + spacing X + + + + spacing Y + + + + + x + y + + origin + (bottom-left grid point) + + + + + + i + Dimensions — number of cells per axis (uint64, 0-based: a value of 5 spans indices 0–4). + Spacing — physical distance between grid planes per axis (float32, e.g. microns); must be positive. + Origin — physical location of the bottom-left grid point (float32). + Image geometries are always 3D; a 2D image sets one dimension to 1. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.png b/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.png new file mode 100644 index 0000000000..5b86ff9ad3 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.svg b/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.svg new file mode 100644 index 0000000000..33b00e619a --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/DataModel_CellFeatureEnsemble.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.png b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.png new file mode 100644 index 0000000000..3f15359789 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.svg b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.svg new file mode 100644 index 0000000000..78fda5174f --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateBadData_IterationSequence.svg @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Erode / Dilate Bad Data — one cell layer per iteration + Bad data = cells with Feature Id 0 (red); good feature cells in blue + + + iter 0 + iter 1 + iter 2 + iter 3 + + + Dilate + grows outward + + + + + →→→ + + + Erode + shrinks inward + + + + + →→→ + + + + + + i + Dilate grows the bad-data region outward by one cell layer per iteration (good cells touching bad become bad). + Erode shrinks it: each bad cell is reassigned to the Feature Id held by the majority of its neighbors. + The Number of Iterations sets the layer count; per-axis toggles (X / Y / Z) restrict which directions are processed. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.png b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.png new file mode 100644 index 0000000000..656a361b0b Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.svg b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.svg new file mode 100644 index 0000000000..74839b5097 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ErodeDilateCoordinationNumber_CoordinationNumber.svg @@ -0,0 +1,117 @@ + + + + + + + + + + + + Coordination Number = differing face-neighbors + Count of a cell's 6 face-neighbors (±X, ±Y, ±Z) that belong to a different feature + + + + + CN = 3 · edge cell + + + + + + + + + +Z + + + + +Y + + + + −X + + + + cell + + + + +X + + + + −Y + + + + + −Z + + 3 of 6 neighbors differ + + + + + + CN = 6 · isolated cell + + + + + + + + +Z + + + +Y + + + −X + + + cell + + + +X + + + −Y + + + + −Z + + 6 of 6 neighbors differ + + + + + + center cell + + same feature + + different feature (counts toward CN) + + + + + + + i + When CN ≥ the Coordination Number parameter, the cell's Feature Id and attributes are replaced by a neighbor's + values. With Loop Until Gone enabled, the sweep repeats until no remaining cell meets the criterion. + + + + + + + Higher coordination number = more isolated — a higher threshold absorbs only the most isolated cells. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.png b/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.png new file mode 100644 index 0000000000..a842625c39 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.svg b/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.svg new file mode 100644 index 0000000000..dbdbc58408 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/Morphology_OpeningClosing.svg @@ -0,0 +1,63 @@ + + + + + + + Morphological Opening & Closing + An erode / dilate pair applied to the mask's true (colored) region + + + Opening + erode → dilate + removes small + isolated regions + + + + + + input + + + + erode (speck gone) + + + + = opening + + + + + Closing + dilate → erode + fills small + holes + + + + + + input + + + + dilate (hole filled) + + + + = closing + + + + + + + + i + Opening (erode then dilate) removes small isolated regions and thin protrusions while returning the larger + region to about its original size. Closing (dilate then erode) fills small holes and gaps while preserving + the outer boundary. Run the erode and dilate passes with equal iteration counts to keep the overall size stable. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.png b/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.png new file mode 100644 index 0000000000..b88bee1649 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.svg b/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.svg new file mode 100644 index 0000000000..72472dcfa6 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ReadHDF5Dataset_TuplesComponents.svg @@ -0,0 +1,56 @@ + + + + + + + Read HDF5 Dataset + A flat dataset is reshaped into tuples × components + + + HDF5 dataset (flat) — 12 values + + + + + 01234567891011 + + + + + reshape + + + tuples (6) + components (2) + + + + + + + + + + 01 + 23 + 45 + 67 + 89 + 1011 + + DataArray — 6 tuples × 2 components + + + + + Reshape rule + total values = ∏(tuple dims) × ∏(comp dims) + 12 = 6 × 2 + + Tuple dimensions + how many elements (e.g. voxels / rows). + Component dimensions + values per element (e.g. a 3-vector → 3). + + diff --git a/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.png b/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.png new file mode 100644 index 0000000000..74d7da2211 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.svg b/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.svg new file mode 100644 index 0000000000..a3b392164d --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/ResampleImageGeom_SpacingCellCount.svg @@ -0,0 +1,44 @@ + + + + + + Resample Image Geometry + Change the grid resolution — the physical size stays the same + + + + + + + + + spacing (1, 1) + 8 × 8 cells + + + + resample + spacing × 2 + + + + + + + + + spacing (2, 2) + 4 × 4 cells + + + + + + i + The physical bounds are unchanged, so doubling the spacing along an axis halves the cell count there + (cells become larger and fewer). Each new cell copies the value of the nearest source cell — no interpolation. + Three modes set the new grid: Spacing (physical units), Scaling (percent per axis), or + Exact Dimensions (target cell counts). + + diff --git a/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.png b/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.png new file mode 100644 index 0000000000..cdb120ac39 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.svg b/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.svg new file mode 100644 index 0000000000..743d2e2e7b --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/RotateSampleRefFrame_SampleVsGeometric.svg @@ -0,0 +1,89 @@ + + + + + + + + + + + + + + + Sample reference-frame rotation vs geometric rotation + The same 90° rotation, applied two different ways + + + + + Rotate Sample Reference Frame + axes rotate · microstructure fixed + + + + + + + + + + + + + + + + + + + + x + y + + + + + x' + y' + + + + + + + Geometric rotation + data rotates · axes fixed + + + + + + + + + + + + + + + + + + + x + y + + + + + + + + i + Rotate Sample Reference Frame rotates the coordinate axes and resamples the cell data onto the new grid — the physical + microstructure is unchanged, and the origin usually shifts. To rotate the data itself, use Apply Transformation to Geometry. + + diff --git a/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.png b/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.png new file mode 100644 index 0000000000..5983d66278 Binary files /dev/null and b/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.png differ diff --git a/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.svg b/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.svg new file mode 100644 index 0000000000..535ed8c116 --- /dev/null +++ b/src/Plugins/SimplnxCore/docs/Images/WriteAbaqusHexahedron_VoxelToHex.svg @@ -0,0 +1,58 @@ + + + + + + Write Abaqus Hexahedron + Each voxel becomes an 8-node hexahedral (C3D8) element + + + + + + voxel (cell) + + + + export + + + + + + + + + + + + + + + + + + + C3D8 element · 8 nodes + + + + + Output files (Abaqus .inp) + <prefix>.inp — master (*Include) + _nodes.inp — node coordinates + _elems.inp — C3D8 connectivity + _elset.inp — element sets (per grain) + _sects.inp — sections + + + + + + + i + Each Cell becomes one C3D8 hexahedron with 8 corner nodes. Nodes shared between neighboring + voxels are written once, so the mesh is fully connected — a 2×2×2 block of 8 voxels has 27 unique + nodes, not 64. Element sets are written per grain from the Cell Feature Ids. + + diff --git a/src/Plugins/SimplnxCore/docs/InitializeDataFilter.md b/src/Plugins/SimplnxCore/docs/InitializeDataFilter.md index 09ab8dbb0f..847a117a04 100644 --- a/src/Plugins/SimplnxCore/docs/InitializeDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/InitializeDataFilter.md @@ -6,73 +6,80 @@ Processing (Cleanup) ## Description -This **Filter** allows the user to define the data set in a _DataArray_. +This **Filter** overwrites every tuple in a **Data Array** with a value chosen by one of four initialization modes. Multi-component arrays can be initialized either uniformly (one value applied to every component) or per-component (a semicolon-separated list). ### Initialization Type -The *Initialization Type* parameter provides the following choices: +The *Initialization Type* parameter provides four modes: -- **Fill Value [0]**: Copies a user-supplied constant value (or per-component values) into every tuple in the array. -- **Incremental [1]**: Fills the array starting from a user-supplied value and applying a fixed step (increment or decrement) to each successive tuple. -- **Random [2]**: Generates random values across the full scalar type range. An optional fixed seed can be supplied for reproducibility. -- **Random With Range [3]**: Generates random values within a user-specified minimum/maximum range per component. +- **Fill Value [0]** -- every tuple is set to a user-supplied constant value (or per-component values). +- **Incremental [1]** -- the array is filled starting from a user-supplied starting value, applying a fixed step (increment or decrement) to each successive tuple. +- **Random [2]** -- every tuple is set to a uniformly-random value drawn from the **full range** of the array's data type. An optional fixed seed can be supplied for reproducibility. +- **Random With Range [3]** -- every tuple is set to a uniformly-random value drawn from a user-specified [min, max] interval per component. + +#### Fill Value + +Provide a single value or, for multi-component arrays, a semicolon-separated list. The same value is copied into every tuple. + +#### Incremental + +Provide a starting value, a *Step Operation* (Addition or Subtraction), and a step value. Each successive tuple's value is the previous tuple's value plus (or minus) the step. A step value of 0 leaves that component unchanged across all tuples. + +Example -- a 3-component array filled with 3-D rotations in radians, stepping X and Y but not Z: + +- Starting value: `0` +- Step Operation: Addition +- Step Values: `3.141592;6.283185;0` + +#### Random and Random With Range + +Both modes draw uniformly. *Random* uses the full data-type range; *Random With Range* honors a per-component lower and upper bound. Both modes use the same random seed plumbing: + +- *Use Seed for Random Generation* + *Seed Value* -- supply a fixed integer seed for reproducibility. +- With the option disabled, a time-based seed is generated; the actual seed used is saved to the *Stored Seed Value Array* so the run can be reproduced later. + +*Standardize Seed* (Random mode only) controls whether all components in a tuple share the same random draw: + +- ON: a single value is drawn per tuple and broadcast to all components: `| 3;3;3 | 9;9;9 | 4;4;4 | ...` +- OFF: each component is drawn independently: `| 3;9;4 | 7;2;8 | 5;9;6 | ...` + +For *Random With Range* on a multi-component array, the lower and upper bounds are semicolon-separated per component. A trick for fixing one component while randomizing the others: set the lower and upper bound to the same value for the fixed component. Example -- 3-component array where the middle component is always 6 and the others vary: + +- Lower bound: `0;6;0` +- Upper bound: `90;6;252` ### Step Operation -The *Step Operation* parameter (used with **Incremental** initialization) provides the following choices: - -- **Addition [0]**: Adds the step value to the previous tuple's value at each successive tuple. -- **Subtraction [1]**: Subtracts the step value from the previous tuple's value at each successive tuple. - -This **Filter** provides several ways to do this: - -- Fill Value: - - This type is fairly straight forward you provide a value, or set of values for a multi-component array, and it gets copied into every tuple in the array. - - Nuances to note: - - None for this type aside from aforementioned boolean nuances -- Incremental: - - This allows the user to supply a start value, define the type (increment or decrement), and set a step value to for the operation. Providing 0 will ensure that that component remains unchanged. - - Example: Say you have a 3 component array where you want to define 3-D rotations in radians for different components, but you only want to operate on the x and y and not the z; You could define your starting value as '0' (ignoring the apostrophe marks), select addition as the operation, then define the step values like so: '3.141592;6.283185;0' - - Boolean Nuances: - - For the _Step Values_ please enter uint8 values, preferably a 0 or 1 only. - - Addition: - - Any step value that is greater than 0 will cause all values to be 'true' after the first tuple, 'true' values will remain unchanged. - - If your start value is 'false' and step value > 0, the array will initialize to | false | true | true | ... | - - If your start value is 'true' and step value > 0, the array will initialize to | true | true | true | ... | - - Subtraction: - - Any step value that is greater than 0 will cause all values to be 'false' after the first tuple, 'false' values will remain unchanged. - - If your start value is 'true' and step value > 0, the array will initialize to | true | false | false | ... | - - If your start value is 'false' and step value > 0, the array will initialize to | false | false | false | ... | -- Random: - - This allows the user to randomly generate values from the actual scalar type min to the scalar type max. If you choose to define the seed for the array the seed in the _Seed Value_ box will be used, otherwise a random seed will be generated. Either way the seed will be saved to the _Stored Seed Value Array_. - - **Standardizing Seed:** - - This value allows the user to be able to generate the same sequence of values for every component in the tuple throughout the array when set to true - - Example: - - When true it will look like | 3;3;3 | 9;9;9 | 4;4;4 | ... | - - When false it will look like | 3;9;4 | 7;2;8 | 5;9;6 | ... | -- Random with Range: - - This is beholden to the same rules as random with some additional considerations in relation to the range. - - If you require an array that has one stable component and other variable components you can define the lower and upper bounds of the range to be the same and the variable will never change. - - Example: Say you have a 3 component array where you want the middle component to be always be 6 and the other component to be randomized above six. When defining a range supply '6' (ignoring the apostrophe marks) for the lower bound and '90;6;252' for the upper bound - -The filter provides two ways to define the values in a multi-component array: - -- Define a single value that will be used for every component in the tuple -- Defining each component's value seperated by the semicolon ';' character - -Example: Say you have a 3 component array that you want to range that starts from zero and has unique end values for each component. In the starting value box just supply '0' (ignoring the apostrophe marks) and then define your end values in a list like this: '4;0;7' - -**Boolean Entry Notes:** - -The **ONLY** two ways to specify a 'false' boolean value are as follows: - -- boolean value string types as follows ignoring apostrophe marks: 'False', 'FALSE', 'false' -- all well-formed integers and well-formed floating point definitions of 0 - -**ANY OTHER** string or number **WILL BE** 'true', although it is good practice to define true values as follows: - -- boolean value string types as follows ignoring apostrophe marks: 'True', 'TRUE', 'true' -- all well-formed integers and well-formed floating point definitions of 1 +Used only with *Incremental*: + +- **Addition [0]** -- adds the step value to the previous tuple's value. +- **Subtraction [1]** -- subtracts the step value from the previous tuple's value. + +### Boolean Array Notes + +For boolean arrays, the only values that produce `false` are: + +- The strings `False`, `FALSE`, `false`. +- Any well-formed numeric `0` (integer or floating-point). + +**Any other** string or number is interpreted as `true`. Conventional `true` values are the strings `True`, `TRUE`, `true`, or the numeric `1`. + +For boolean arrays under *Incremental* mode, the *Step Operation* behaves as follows: + +- **Addition** with step value > 0: starting `false` produces `false, true, true, ...`; starting `true` produces all `true`. +- **Subtraction** with step value > 0: starting `true` produces `true, false, false, ...`; starting `false` produces all `false`. + +### Multi-Component Value Format + +Single value: applied to all components. Example: `2.5` initializes every component of every tuple to 2.5. + +Per-component values: semicolons separate components. Example for a 2-component array: `0;1` sets component 0 to 0 and component 1 to 1. + +Semicolons (rather than commas) are used to avoid international locale ambiguity (commas are decimal points in some locales). + +### Required Input Sources + +- **Input Data Array** -- the array to overwrite. Typically a previously created or imported array. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/InitializeImageGeomCellDataFilter.md b/src/Plugins/SimplnxCore/docs/InitializeImageGeomCellDataFilter.md index f61cc5d327..27a0dcb4aa 100644 --- a/src/Plugins/SimplnxCore/docs/InitializeImageGeomCellDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/InitializeImageGeomCellDataFilter.md @@ -6,15 +6,36 @@ Processing (Cleanup) ## Description -This **Filter** allows the user to define a subvolume of the data set in which the **Filter** will reset all data for every **Cell** within the subvolume. The user can choose from three initialization modes: *Manual* (initialize to a user-specified value), *Random* (initialize with random values across the full range of the data type), or *Random With Range* (initialize with random values within a user-specified range). +This **Filter** overwrites every cell within a user-defined *subvolume* of an **Image Geometry** with either a constant value or random values. Use this to reset a region of interest, mask out an area for testing, or stub in synthetic data for development. + +### Subvolume Specification + +The subvolume is specified by minimum and maximum **cell indices** along each axis (X, Y, Z). Indices are **0-based, inclusive** -- a min of 5 and a max of 9 includes cells 5, 6, 7, 8, and 9 (5 cells). The min must be less than or equal to the max along each axis. The min must be at least 0 and the max must be less than the geometry's dimension along that axis. + +The subvolume operates **only on cells inside this index range**; cells outside are unaffected. ### Initialization Type -The *Initialization Type* parameter provides the following choices: +The *Initialization Type* parameter provides three modes: + +- **Manual [0]**: every cell in the subvolume is set to a single user-specified constant value. The value is reinterpreted into each array's data type (e.g., 1.5 → 1 for an int array, 1.5 → 1.5 for a float array, anything non-zero → true for a bool array). +- **Random [1]**: every cell is set to an independent random value drawn from the **full range of the array's data type**. For uint8, this means 0-255. For float32, this means the full IEEE-754 range (which produces extreme values rarely useful for visualization). +- **Random With Range [2]**: every cell is set to an independent random value drawn from the user-specified [min, max] interval. The min/max are interpreted in the array's data type. + +Multiple cell arrays can be initialized in one filter pass; each gets independently-drawn random values when in Random mode. + +### Random Seed + +The random modes use a configurable seed for reproducibility. Enable *Use Seed for Random Generation* and supply an integer to make results deterministic across pipeline runs. With the option disabled, a time-based seed is used (results vary per run). + +### Behavior on Boolean Arrays + +For boolean arrays in random modes, each cell is set to a uniformly-chosen true/false. Range parameters are ignored for boolean arrays. + +### Required Input Sources -- **Manual [0]**: Initializes every cell in the subvolume to a user-specified constant value. -- **Random [1]**: Initializes every cell in the subvolume with random values drawn from the full range of the data type. -- **Random With Range [2]**: Initializes every cell in the subvolume with random values drawn from a user-specified minimum/maximum range. +- **Input Image Geometry** -- the geometry whose cell data will be modified in-place. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. +- **Cell Attribute Arrays to Initialize** -- one or more cell-level arrays already attached to the geometry's Cell Attribute Matrix. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/InterpolatePointCloudToRegularGridFilter.md b/src/Plugins/SimplnxCore/docs/InterpolatePointCloudToRegularGridFilter.md index 98d61e0105..d0c16f39e9 100644 --- a/src/Plugins/SimplnxCore/docs/InterpolatePointCloudToRegularGridFilter.md +++ b/src/Plugins/SimplnxCore/docs/InterpolatePointCloudToRegularGridFilter.md @@ -69,6 +69,10 @@ Statistics are computed on the *weighted* values (`kernel_weight * source_value` Median is not supported because it requires storing every vertex's contribution, which would negate the memory savings of the flat accumulation approach. +### Required Input Sources + +- **Vertex Geometry** -- the point cloud whose arrays will be interpolated, produced by a filter that creates a **Vertex Geometry** such as [Extract Vertex Geometry](ExtractVertexGeometryFilter.md) or [Create Geometry](CreateGeometryFilter.md). + ### Mask An optional boolean or uint8 mask array may be provided. Vertices where the mask value is *false* or *0* are skipped entirely during interpolation – they do not contribute to any voxel's accumulated value or statistics. @@ -79,7 +83,7 @@ This filter uses flat arrays rather than variable-length lists, so memory usage ### Voxel Index Computation -The destination voxel for each vertex is computed on-the-fly from the vertex coordinates and the **Image Geometry**'s origin, spacing, and dimensions. There is no need to pre-compute a voxel indices array (e.g., via the *Map Point Cloud to Regular Grid* filter). Vertices whose coordinates fall outside the **Image Geometry** bounds are silently skipped. +The destination voxel for each vertex is computed on-the-fly from the vertex coordinates and the **Image Geometry**'s origin, spacing, and dimensions. There is no need to pre-compute a voxel indices array (e.g., via the [Map Point Cloud to Regular Grid](MapPointCloudToRegularGridFilter.md) filter). Vertices whose coordinates fall outside the **Image Geometry** bounds are silently skipped. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/IterativeClosestPointFilter.md b/src/Plugins/SimplnxCore/docs/IterativeClosestPointFilter.md index 34221c35b7..bff5cee45f 100644 --- a/src/Plugins/SimplnxCore/docs/IterativeClosestPointFilter.md +++ b/src/Plugins/SimplnxCore/docs/IterativeClosestPointFilter.md @@ -16,50 +16,61 @@ which we can describe in terms of "moving geometry" and "target geometry." The b 1. Initial State: We start with two sets of points or geometries. The "moving geometry" is the one we aim to align with the "target geometry." Initially, the moving geometry may be in any orientation or position relative to the target geometry. -1. Identify Correspondences: For each point in the moving geometry, we find the closest point in the target geometry. These +2. Identify Correspondences: For each point in the moving geometry, we find the closest point in the target geometry. These pairs of points are considered correspondences, based on the assumption that they represent the same point in space after the moving geometry is properly aligned. -1. Estimate Transformation: With the correspondences identified, the algorithm calculates the optimal rigid body +3. Estimate Transformation: With the correspondences identified, the algorithm calculates the optimal rigid body transformation (which includes translation and rotation) that best aligns the moving geometry to the target geometry. This step often involves minimizing a metric, such as the sum of squared distances between corresponding points, to find the best fit. -1. Apply Transformation: The calculated transformation is applied to the moving geometry, aligning it closer to the +4. Apply Transformation: The calculated transformation is applied to the moving geometry, aligning it closer to the target geometry. -1. Iterate: Steps 2 through 4 are repeated iteratively. With each iteration, the moving geometry is brought into closer +5. Iterate: Steps 2 through 4 are repeated iteratively. With each iteration, the moving geometry is brought into closer alignment with the target geometry. The iterations continue until a stopping criterion is met, which could be a predefined number of iterations, a minimum improvement threshold between iterations, or when the change in the error metric falls below a certain threshold. -Final Alignment: Once the iterations stop, the algorithm concludes with the moving geometry optimally aligned to the target +6. Final Alignment: Once the iterations stop, the algorithm concludes with the moving geometry optimally aligned to the target geometry, based on the criteria set for minimizing the differences between them. ICP has a number of advantages, such as robustness to noise and no requirement that the two sets of points to be the same size. However, performance may suffer if the two sets of points are of significantly different size. -## Saving the Output Transformation Matrix. +## Saving the Output Transformation Matrix -The format of the output DataArray is a flattened array 16 elements in size that represents a 4x4 matrix. -The elements are encoded in a ROW MAJOR array, i.e., +The filter always reports the computed rigid body transformation as an output **DataArray**. By default the moving geometry itself is left unchanged. If the *Apply Transformation to Moving Geometry* parameter is enabled, the filter also applies the transformation to the moving geometry's vertices in place, so that it is aligned to the target geometry. + +The output **DataArray** is a flattened array 16 elements in size that represents a 4x4 transformation matrix. +The elements are encoded in ROW MAJOR order, i.e., 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 -represents the following 4x4 Matrix +represents the following 4x4 matrix 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 +The upper-left 3x3 block holds the rotation, and the first three entries of the rightmost column (elements 4, 8, 12) hold the translation, expressed in the coordinate units of the input geometries. + +The reported matrix can be supplied to [Apply Transformation to Geometry](ApplyTransformationToGeometryFilter.md) to transform this or another geometry as a separate step. + +### Required Input Sources + +- **Moving Vertex Geometry** -- the **Vertex Geometry** to be aligned to the target. +- **Target Vertex Geometry** -- the fixed reference **Vertex Geometry**. The two geometries need not have the same number of points. + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/LabelTriangleGeometryFilter.md b/src/Plugins/SimplnxCore/docs/LabelTriangleGeometryFilter.md index 0150c0e50e..7ddbb33bc0 100644 --- a/src/Plugins/SimplnxCore/docs/LabelTriangleGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/LabelTriangleGeometryFilter.md @@ -24,6 +24,10 @@ The image below shows a single STL file that contains 12 different geometries. T ![Filter Output](Images/LabelTriangleGeometry_1.png) +### Required Input Sources + +- **Triangle Geometry** -- the surface mesh whose triangles will be labeled, typically read from a CAD mesh via [Read STL File](ReadStlFileFilter.md). STL is a common CAD mesh file format that stores a surface as a collection of triangles. + % Auto generated parameter table will be inserted here ## License & Copyright @@ -32,4 +36,4 @@ Please see the description file distributed with this plugin. ## DREAM3D-NX Help -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues) GitHub site where the community of DREAM3D-NX users can help answer your questions. +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/LaplacianSmoothingFilter.md b/src/Plugins/SimplnxCore/docs/LaplacianSmoothingFilter.md index fc52a99704..78d7c298d0 100644 --- a/src/Plugins/SimplnxCore/docs/LaplacianSmoothingFilter.md +++ b/src/Plugins/SimplnxCore/docs/LaplacianSmoothingFilter.md @@ -6,26 +6,26 @@ Surface Meshing (Smoothing) ## Description -This **Filter** applies Laplacian smoothing to any node based geometry except for **vertex**. A. Belyaev [2] has a concise explanation of the Laplacian Smoothing as follows: +This **Filter** applies **Laplacian smoothing** to any node-based geometry except for a **Vertex Geometry**. Laplacian smoothing repeatedly moves each node toward the average position of its connected neighbors, which reduces high-frequency surface noise and tends to flatten the surface. A. Belyaev [1] gives a concise explanation: --------------------------- Let us consider a triangulated surface and for any vertex P let us define the so-called umbrella-operator -![](Images/Laplacian_Fig1.png) +![Definition of the umbrella-operator as a weighted sum over the neighbors of vertex P.](Images/Laplacian_Fig1.png) where summation is taken over all neighbors of P and wi are positive weights. See Fig. 1 for the geometric idea behind the umbrella-operator. -![](Images/Laplacian_Fig2.png) +![Geometric illustration of the umbrella-operator centered on vertex P and its neighbor ring.](Images/Laplacian_Fig2.png) -The weights, can be defined, for example, as the inverse distances between P and its neighbors. The simplest umbrella-operator is obtained if *w* i = 1 and the umbrella-operator has the form +The weights can be defined, for example, as the inverse distances between P and its neighbors. The simplest umbrella-operator is obtained if *w* i = 1 and the umbrella-operator has the form -![](Images/Laplacian_Eq1.png) +![Simplified umbrella-operator where every neighbor weight equals one, divided by the number of neighbors.](Images/Laplacian_Eq1.png) where n is the number of neighbors. The local update rule -![](Images/Laplacian_Eq2.png) +![Local update rule that moves vertex P by lambda times the umbrella-operator.](Images/Laplacian_Eq2.png) applied to every point of the triangulated surface is called Laplacian smoothing of the surface. Typically the factor λ is a small positive number, and the process (2) is executed repeatedly. The Laplacian smoothing algorithm reduces the high frequency surface information and tends to flatten the surface. See Fig. 2 where Laplacian smoothing is applied to a triangulated model of a Noh mask. @@ -33,17 +33,21 @@ If λ is too small, one needs more iterations for smoothing and the smooth --------------------------- -In the Laplacian algorithm the λ term has a range of 0 ≤ λ ≤ 1 and defines a relative distance that a node can move relative to the positions of the nodes neighbors. A λ = 0 value will effectively stop those node types from any movement during the algorithm thus by allowing the user to set this value for specific types of nodes the user can arrest the shrinkage of the surface mesh during the smoothing process. +In the Laplacian algorithm the λ term is dimensionless with a range of 0 ≤ λ ≤ 1 and defines the relative distance that a node can move toward the average position of its neighbors. A value of *λ = 0* effectively stops those node types from any movement during the algorithm. By setting this value for specific types of nodes, the user can arrest the shrinkage of the surface mesh during smoothing. ### Taubin's Lambda-Mu Smoothing Algorithm -One of the options for the filter allows the user to apply Taubin's Lambda-Mu variation on Laplacian smoothing. This variation removes the shrinkage typically found with Laplacian smoothing by adding an additional step within each iteration where the negative of the (Lambda value \* Mu Factor) which effectively moves the points in the **opposite** direction from the initial movement. Because of this negative movement the number of iterations to achieve the same level of smoothing is greatly increased, on the order of 10x to 20x. +One of the filter options applies **Taubin's Lambda-Mu** variation on Laplacian smoothing. This variation removes the shrinkage typically found with Laplacian smoothing by adding a second step within each iteration: it moves the points back by the negative of (*Lambda* * *Mu Factor*), effectively pushing them in the **opposite** direction from the initial movement. The *Mu Factor* is a dimensionless multiplier. Because of this negative movement, the number of iterations needed to achieve the same level of smoothing increases greatly, on the order of 10x to 20x. + +If you instead need a smoothing method that strictly preserves the mesh topology (triple lines, quadruple points, and feature boundaries), consider [Hierarchical Smoothing](HierarchicalSmoothFilter.md). ### Algorithm Usage and Memory Requirements -Currently, if you lock the *Default Lambda* value to zero (0), the triple lines and quadruple points will not be able to move because none of their neighbors can move. The user may want to consider allowing a small value of λ for the default nodes which will allow some movement of the triple lines and/or quadruple Points. +Currently, if you lock the *Default Lambda* value to zero (0), the **triple lines** (edges where three features meet) and quadruple points will not be able to move because none of their neighbors can move. The user may want to consider allowing a small value of λ for the default nodes, which will allow some movement of the triple lines and/or quadruple points. + +The *Iteration Steps* parameter is a dimensionless count of smoothing passes; more steps produce more smoothing. -This **Filter** will create additional internal arrays in order to facilitate the calculations. These arrays are +This **Filter** creates additional internal arrays to facilitate the calculations: - Float - lambda values (same size as nodes array) - 64 bit integer - unique edges array @@ -51,14 +55,11 @@ This **Filter** will create additional internal arrays in order to facilitate th - Integer for number of connections for each node (same size as nodes array) - 64 bit float for delta values (3x size of nodes array) -Due to these array allocations this **Filter** can consume large amounts of memory if the starting mesh has a large number of nodes. - -At the conclusion of the filter these extra internal arrays will be reclaimed by the system. - +Because of these array allocations, this **Filter** can consume large amounts of memory if the starting mesh has a large number of nodes. At the conclusion of the filter these extra internal arrays are reclaimed by the system. ### Node Type Values -The values for the *Node Type* array can take one of the following values. +The values for the *Node Type* array can take one of the following values: namespace SurfaceMesh { namespace NodeType { @@ -72,17 +73,20 @@ The values for the *Node Type* array can take one of the following values. } } -If your surface mesh is lacking a `Node Type` array, you can simply create a DataArray inside the Vertex Data Attribute Matrix. The type should be "int8" and have an initialization value of 3. This will allow **all** nodes to move. +If your surface mesh is lacking a `Node Type` array, you can create a DataArray inside the Vertex Data Attribute Matrix. The type should be "int8" with an initialization value of 3. This will allow **all** nodes to move. + +### Required Input Sources -For more information on surface meshing, visit the tutorial. +- **Triangle Geometry** -- the surface mesh to smooth, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Node Type** -- the per-vertex node classification array, produced by the same surface-meshing filter that created the geometry. % Auto generated parameter table will be inserted here ## References -[1] D. A. Feature, (1988) Laplacian smoothing and Delaunay triangulations. Commun. appl. numer. methods, 4: 709 712. doi: 10.1002/cnm.1630040603 +[1] A. Belyaev, *Mesh smoothing and enhancing curvature estimation*, lecture notes, Max-Planck-Institut fur Informatik. [http://www.mpi-inf.mpg.de/~ag4-gm/handouts/06gm_surf3.pdf](http://www.mpi-inf.mpg.de/~ag4-gm/handouts/06gm_surf3.pdf) -[2] A. Belyaev, Mesh smoothing and enhancing curvature estimation, [http://www.mpi-inf.mpg.de/ ag4-gm/handouts/06gm_surf3.pdf]( ag4-gm/handouts/06gm_surf3.pdf). +[2] Field, D. A. (1988). *Laplacian smoothing and Delaunay triangulations*. Communications in Applied Numerical Methods, 4(6): 709-712. doi:10.1002/cnm.1630040603 ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/MapPointCloudToRegularGridFilter.md b/src/Plugins/SimplnxCore/docs/MapPointCloudToRegularGridFilter.md index 28620ddf87..c2c4d6c02d 100644 --- a/src/Plugins/SimplnxCore/docs/MapPointCloudToRegularGridFilter.md +++ b/src/Plugins/SimplnxCore/docs/MapPointCloudToRegularGridFilter.md @@ -8,13 +8,15 @@ Sampling (Mapping) This **Filter** determines, for a user-defined grid, in which voxel each point in a **Vertex Geometry** lies. The user can either construct a sampling grid by specifying the dimensions, or select a pre-existing **Image Geometry** to use as the sampling grid. The voxel indices that each point lies in are stored on the vertices. -Additionally, the user may opt to use a mask; points for which the mask are false are ignored when computing voxel indices (instead, they are initialized to voxel 0). +Additionally, the user may opt to use a mask; points for which the mask is false are ignored when computing voxel indices (instead, they are initialized to voxel 0). + +The per-vertex voxel indices produced by this filter are commonly used as the input to [Interpolate Point Cloud to Regular Grid](InterpolatePointCloudToRegularGridFilter.md), which transfers point-cloud attribute values onto the regular grid. ### Sampling Grid Type The *Sampling Grid Type* parameter controls how the target grid is defined: -- **Manual [0]**: The user specifies the grid dimensions directly. The filter creates a new **Image Geometry** with those dimensions to use as the sampling grid. +- **Manual [0]**: The user specifies the grid dimensions directly as voxel counts along X, Y, and Z (dimensionless counts). The filter creates a new **Image Geometry** with those dimensions to use as the sampling grid. - **Use Existing Image Geometry [1]**: The user selects a pre-existing **Image Geometry** from the data structure to use as the sampling grid. ### Out of Bounds Handling @@ -35,16 +37,20 @@ The default selection is `Silent`, but it is mostly provided as a way to preserv - User may intend to create a workflow that will be distributed in which the end user may not have control over the parameter, but should be monitoring for anomalies in output - User may want to watch for unexpected behavior - `Error at First Instance` option - - User may to trace down where a anomaly first occurred + - User may want to trace down where an anomaly first occurred - User may be creating a pipeline in a known problem space with a well defined outcome where any data anomalies must be caught early to prevent downstream problems -Continuing along the Out-of-Bounds discussion, the Out-of-Bounds value allows the user to specify a specific `uint64` (0 - 18,446,744,073,709,551,616) value to use for every value from the vertex geometry that falls outside the image geometry. The default value is just the max `unsigned long long int` in an effort to make sure that it doesn't intersect with existing indexed values. This is identical to previous functionality. However, consider the situation where a user has a geometry that contains 1000 voxels, in this case the actual index values are 0-999, so a user could select 1000 and it wouldn't overlap any existing voxel index. Doing this may reduce skew of coloring or other statistic-based analysis. Advanced users may intentionally select a value that overlaps an existing voxel index they wish to remove in a later filter or to later downcast the datasize without overflow, but this is considered an edge case that is functional, but not recommended. +Continuing along the Out-of-Bounds discussion, the Out-of-Bounds value allows the user to specify a specific `uint64` (0 - 18,446,744,073,709,551,615) value to use for every value from the vertex geometry that falls outside the image geometry. The default value is just the max `unsigned long long int` in an effort to make sure that it doesn't intersect with existing indexed values. This is identical to previous functionality. However, consider the situation where a user has a geometry that contains 1000 voxels, in this case the actual index values are 0-999, so a user could select 1000 and it wouldn't overlap any existing voxel index. Doing this may reduce skew of coloring or other statistic-based analysis. Advanced users may intentionally select a value that overlaps an existing voxel index they wish to remove in a later filter or to later downcast the datasize without overflow, but this is considered an edge case that is functional, but not recommended. + +### Required Input Sources + +- **Vertex Geometry** -- the input point cloud whose points are mapped to grid voxels, typically created by an import step or a filter that produces a **Vertex Geometry**. % Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/MoveDataFilter.md b/src/Plugins/SimplnxCore/docs/MoveDataFilter.md index 814595d1b3..e445cf7f56 100644 --- a/src/Plugins/SimplnxCore/docs/MoveDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/MoveDataFilter.md @@ -6,7 +6,24 @@ Core (Memory/Management) ## Description -This **Filter** allows the user to move one or more **Data Objects** to a new parent **Group**. When moving a **Data Array** into an **Attribute Matrix**, the destination must be compatible, meaning the *number of tuples* must be equal (though the actual *tuple dimensions* need not match). +This **Filter** moves one or more **Data Objects** to a new parent **Group** (a **DataGroup**, **Attribute Matrix**, or **Geometry**). The objects retain their names; only their parent changes. + +### Tuple Compatibility When Moving Arrays + +When moving a **Data Array** *into* an **Attribute Matrix**, the destination must be tuple-compatible: the **number of tuples** of the array must equal the number of tuples implied by the destination matrix's tuple dimensions. The *shape* of the tuple dimensions does not need to match -- moving a 1-D array of 60 tuples into a (3, 4, 5) Attribute Matrix is allowed, because both equal 60 total tuples. Moving the same array into a (10, 10) matrix would fail (only 100 total tuples). + +When moving between non-Attribute-Matrix parents (e.g., between two DataGroups), tuple matching is not enforced because DataGroups have no tuple-dimension contract. + +### When to Use This Filter + +- Reorganize pipeline output so related arrays end up in one matrix. +- Move a computed array (e.g., output of a custom filter that landed in a temporary group) into the proper Cell/Feature/Ensemble matrix where downstream filters expect to find it. +- Move a Geometry under a DataGroup to organize multiple geometries. + +### Required Input Sources + +- **Objects to Move** -- a list of paths to existing **DataObjects**. +- **New Parent Path** -- an existing **DataGroup**, **Attribute Matrix**, or **Geometry**. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/MultiThresholdObjectsFilter.md b/src/Plugins/SimplnxCore/docs/MultiThresholdObjectsFilter.md index 2e07d2da61..4df65b0d3e 100644 --- a/src/Plugins/SimplnxCore/docs/MultiThresholdObjectsFilter.md +++ b/src/Plugins/SimplnxCore/docs/MultiThresholdObjectsFilter.md @@ -8,7 +8,9 @@ Processing (Threshold) This **Filter** allows the user to input single or multiple criteria for thresholding **Attribute Arrays** in an **Attribute Matrix**. Internally, the algorithm creates the output boolean arrays for each comparison that the user creates. Comparisons can be either a value and boolean operator (*Less Than*, *Greater Than*, *Equal To*, *Not Equal To*) or a collective set of comparisons. Then all the output arrays are compared with their given comparison operator ( *And* / *Or* ) with the value of a set being the result of its own comparisons calculated from top to bottom. -An example of this **Filter's** use would be after EBSD data is read into DREAM3D-NX and the user wants to have DREAM3D-NX consider **Cells** that the user considers *good*. The user would insert this **Filter** and select the criteria that makes a **Cell** *good*. All arrays **must** come from the same **Attribute Matrix** in order for the **Filter** to execute. +An example of this **Filter's** use would be after EBSD (Electron Backscatter Diffraction) data is read into DREAM3D-NX and the user wants to have DREAM3D-NX consider **Cells** that the user considers *good*. The user would insert this **Filter** and select the criteria that makes a **Cell** *good*. All arrays **must** come from the same **Attribute Matrix** in order for the **Filter** to execute. + +A **Cell** is a single element (voxel) of a gridded geometry such as an **Image Geometry**, and an **Attribute Matrix** is the container that groups together all of the per-**Cell** **Attribute Arrays** (e.g., Confidence Index, Image Quality, Phases) so that they share the same number of tuples. Because the threshold is evaluated tuple-by-tuple across the selected arrays, every array used in a comparison must live in that same **Attribute Matrix**. For example, an integer array contains the values 1, 2, 3, 4, 5. For a comparison value of 3 and the comparison operator greater than, the boolean threshold array produced will contain *false*, *false*, *false*, *true*, *true*. For the comparison set { *Greater Than* 2 AND *Less Than* 5} OR *Equals* 1, the boolean threshold array produced will contain *true*, *false*, *true*, *true*, *false*. @@ -16,9 +18,11 @@ It is possible to set custom values for both the TRUE and FALSE values that will **NOTE**: If custom TRUE/FALSE values are chosen, then using the resulting mask array in any other filters that require a mask array will break those other filters. This is because most other filters that require a mask array make the assumption that the true/false values are 1/0. -% Auto generated parameter table will be inserted here +### Required Input Sources -## Example Pipelines +- The **Attribute Arrays** being thresholded -- any per-element scalar arrays that already exist in a single **Attribute Matrix**. Common producers are EBSD readers such as [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), [Read CTF Data](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read ANG Data](../OrientationAnalysis/ReadAngDataFilter.md) (which supply Confidence Index, Image Quality, Phases, etc.), but any filter that creates scalar **Cell** or **Feature** arrays can supply the inputs. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/NearestPointFuseRegularGridsFilter.md b/src/Plugins/SimplnxCore/docs/NearestPointFuseRegularGridsFilter.md index e62adf49ba..83b4566bb7 100644 --- a/src/Plugins/SimplnxCore/docs/NearestPointFuseRegularGridsFilter.md +++ b/src/Plugins/SimplnxCore/docs/NearestPointFuseRegularGridsFilter.md @@ -6,9 +6,26 @@ Sampling (Resolution) ## Description -This **Filter** fuses two **Image Geometry** data sets together. The grid of **Cells** in the *Reference* **Data Container** is overlaid on the grid of **Cells** in the *Sampling* **Data Container**. Each **Cell** in the *Reference* **Data Container** is associated with the nearest point in the *Sampling* **Data Container** (i.e., no *interpolation* is performed). All the attributes of the **Cell** in the *Sampling* **Data Container** are then assigned to the **Cell** in the *Reference* **Data Container**. +This filter copies the **Cell** data from one **Image Geometry** onto another by matching each cell to the spatially nearest cell in the other grid. It is used to bring the attribute arrays of two separately-sampled volumes into a single grid so they can be analyzed together. -*Note:* The *Sampling* **Data Container** remains identical after this **Filter**, but the *Reference* **Data Container**, while "geometrically identical", gains all the attribute arrays from the *Sampling* **Data Container**. +### Reference vs. Sampling Geometry + +The filter works with two **Image Geometries**: + +- The **Reference** geometry is the grid that is kept. Its cells are the destination. +- The **Sampling** geometry is the grid that is read from. Its cells are the source of the copied data. + +For each cell in the *Reference* geometry, the filter finds the cell in the *Sampling* geometry whose center is physically closest (using the two grids' origins and spacings), and copies all of that sampling cell's attribute arrays onto the reference cell. **No interpolation is performed** — the nearest sampling value is taken as-is. Because the match is by physical position, the two grids may have different spacings, dimensions, or extents; only their overlap in space is meaningful. + +The *Sampling* geometry is left unchanged. The *Reference* geometry keeps its own geometry but gains a copy of the sampling geometry's attribute arrays. + +### Parameter Guidance + +- **Use Custom Fill Value** — controls what happens to reference cells that fall outside the sampling grid (no nearby sampling cell). When off, copied arrays are filled with *0* there; when on, the user supplies the fill value. + +### Required Input Sources + +- **Reference Image Geometry** and **Sampling Image Geometry** -- two **Image Geometries** (each with a **Cell Attribute Matrix**), typically created by separate import or resampling steps. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/PadImageGeometryFilter.md b/src/Plugins/SimplnxCore/docs/PadImageGeometryFilter.md index 37b3e73bcf..8b7eb85866 100644 --- a/src/Plugins/SimplnxCore/docs/PadImageGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/PadImageGeometryFilter.md @@ -1,39 +1,57 @@ # Pad Image Geometry - -## Group (Subgroup) ## +## Group (Subgroup) Generic (Generic) -## Description ## +## Description -This **Filter** pads an image geometry by the given min/max voxels for each dimension in X, Y, and Z, using the default padding value. -It is also possible to optionally update the origin of the image geometry, which prevents the original data from shifting in space. +This **Filter** extends an **Image Geometry** outward by adding cells around the edges. Each added cell is initialized to a user-specified default value. Optionally, the geometry's origin can be updated so that the original data stays in the same physical location after padding. -For example given the original input geometry in Figure 1: +Padding is the inverse operation of [Crop Geometry (Image)](CropImageGeometryFilter.md). Common use cases are creating a margin around a sample before applying a transformation, or extending a small ROI to a standard size for batch processing. -### Figure 1 +### Example -![](Images/PadImageGeometry_0.png) +Given the input geometry in Figure 1: +#### Figure 1 + +![](Images/PadImageGeometry_0.png) -Padding the Image Geometry with X Min=0, X Max=10, Y Min=0, Y Max=10 will give the output as shown in Figure 2 +Padding with X Min=0, X Max=10, Y Min=0, Y Max=10 produces: -### Figure 2 +#### Figure 2 ![](Images/PadImageGeometry_1.png) +### Pad Amounts and Units + +The pad amounts (*X Min*, *X Max*, *Y Min*, *Y Max*, *Z Min*, *Z Max*) are integers in **cells/voxels**. A value of 10 adds 10 cells to that face. Setting a pad amount to 0 means no padding on that face. + +### Default Value + +Each padded cell is initialized to the *Default Value* for every cell-level **Attribute Array** in the target Attribute Matrix. The default value is interpreted in the same data type as each array (e.g., for a uint8 array, the value is cast to uint8; for a float32 array, to float32). Pick a value that is sentinel-like in every array (commonly 0). + +### Update Origin + +If *Update Origin* is **OFF** (the default), the geometry's origin stays at its current location. New cells appear at coordinates less than the original origin, so the original data effectively shifts to "the middle" of the new bounds. + +If *Update Origin* is **ON**, the geometry's origin is shifted so that the original data stays in its original physical coordinates. New cells extend to coordinates below the original origin. + +### Required Input Sources + +- **Input Image Geometry** -- the geometry to extend. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. + % Auto generated parameter table will be inserted here -## Example Pipelines ## +## Example Pipelines 'pad_image_geometry.d3dpipline' -## License & Copyright ## +## License & Copyright Please see the description file distributed with this plugin. -## DREAM3D Mailing Lists ## +## DREAM3D-NX Help -If you need more help with a filter, please consider asking your question on the DREAM3D Users mailing list: -https://groups.google.com/forum/?hl=en#!forum/dream3d-users +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/PartitionGeometryFilter.md b/src/Plugins/SimplnxCore/docs/PartitionGeometryFilter.md index b18da7c2ad..224a8643b3 100644 --- a/src/Plugins/SimplnxCore/docs/PartitionGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/PartitionGeometryFilter.md @@ -6,7 +6,7 @@ Reconstruction (Reconstruction) ## Description -This **Filter** generates a partition grid and assigns partition IDs for every voxel/node of a given geometry. +This **Filter** overlays a coarse **partition grid** onto an existing geometry and tags every cell or vertex of that geometry with the **partition ID** of the partition cell it falls into. The output is a per-cell or per-vertex integer label plus an Image Geometry representing the partition grid itself. Use this filter to prepare for sub-volume statistics, spatially-binned analysis, parallel decomposition, or any workflow that needs to group elements by spatial region. If the **Filter** determines that any voxel/node of the original geometry is out-of-bounds compared to the generated partition grid, the **Out-Of-Bounds Cell ID** will be used as the partition ID in the output partition IDs array. @@ -113,6 +113,12 @@ On all partitioning modes, a vertex mask can be used with a vertex-based input g |:---:|:---:| | ![](Images/PartitionGeometry/UseVertexMask_1a.png) | ![](Images/PartitionGeometry/UseVertexMask_1b.png) | +### Required Input Sources + +- **Input Geometry** -- any supported geometry (Image, RectGrid, Vertex, Edge, Triangle, Quad, Tet, Hex). Typically produced by [Create Geometry](CreateGeometryFilter.md), [Create Image Geometry](CreateImageGeometryFilter.md), or an upstream reader. +- **Partition Grid Geometry** (only when *Partitioning Mode* is *Existing Partition Grid*) -- an Image Geometry produced by a prior run of this filter. +- **Vertex Mask** (optional, for vertex-based input geometries) -- a boolean cell-level array on the input geometry's vertices. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/PointSampleEdgeGeometryFilter.md b/src/Plugins/SimplnxCore/docs/PointSampleEdgeGeometryFilter.md index 19286760e2..3829e1c0bc 100644 --- a/src/Plugins/SimplnxCore/docs/PointSampleEdgeGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/PointSampleEdgeGeometryFilter.md @@ -1,20 +1,37 @@ # Point Sample Edge Geometry +## Group (Subgroup) + +Sampling (Geometry) + ## Description -This **Filter** will take an Edge geometry and sample each edge at a fixed spatial resolution to generate a new Vertex geometry of sample points. For each interpolated point it will: +This filter walks along each edge of an **Edge Geometry** and places new sample points at a fixed spacing, building a new **Vertex Geometry** (a point cloud) of those samples. + +An **Edge Geometry** is a set of straight line segments connecting pairs of vertices. In additive-manufacturing workflows each such segment is a **scan vector** — the path the energy source (e.g. a laser) travels in one pass. This filter converts those continuous segments into evenly spaced discrete points, which is useful for simulating or analyzing the path at a controlled resolution. + +For every sample point the filter: + +- Copies the **edge ID** of the segment the point lies on, so each point knows which original edge it came from. +- Optionally records the **cumulative sample distance** — the straight-line distance from the start of that edge (scan vector) to the sample point. + +Any additional **Edge Data Arrays** the user selects are also copied onto the matching points of the new Vertex Geometry. + +### Parameter Guidance + +- **Sampling Spacing (mm)** — the distance between successive sample points along each edge, in **millimeters**. A smaller value yields more, more closely spaced points (finer resolution) and a larger output. +- **Calculate Cumulative Sample Distance** — when enabled, stores the start-of-edge distance described above for each sample point. -- Copy over the edge ID from the original edge. -- Record the linear distance from the beginning of its scan vector. +### Required Input Sources -The user can select additional Edge Data Arrays to also be copied onto the newly constructed Vertex geometry +- **Input Edge Geometry** -- an **Edge Geometry**, typically produced by [Slice Triangle Geometry](SliceTriangleGeometryFilter.md) or [Create AM Scan Paths](CreateAMScanPathsFilter.md). % Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help -If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. \ No newline at end of file +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/PointSampleTriangleGeometryFilter.md b/src/Plugins/SimplnxCore/docs/PointSampleTriangleGeometryFilter.md index e10fa4b96f..71b2799245 100644 --- a/src/Plugins/SimplnxCore/docs/PointSampleTriangleGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/PointSampleTriangleGeometryFilter.md @@ -2,37 +2,39 @@ ## Group (Subgroup) -DREAM3D Review (Geometry) +Sampling (Geometry) ## Description -This **Filter** randomly samples point locations on **Triangles** in a **Triangle Geometry**. The sampled point locations are then used to construct a **Vertex Geometry**. The number of point samples may either be specified manually or by inferring from another **Geometry**: +This **Filter** randomly samples point locations on the triangles of a **Triangle Geometry** (a node-based surface mesh of triangular faces) and uses those sampled locations to construct a new **Vertex Geometry** (a point cloud). The total number of sample points is supplied directly through the *Number of Sample Points* parameter. -| Geometry | Source for Number of Samples | -|----------|-----------| -| Image | Number of cells | -| Rectilinear Grid | Number of cells | -| Vertex | Number of vertices | -| Edge | Number of vertices | -| Triangle | Number of vertices | -| Quadrilateral | Number of vertices | -| Tetrahedral | Number of vertices | +To ensure an even sampling across the whole surface area of the **Triangle Geometry**, the average number of points placed on each triangle is made proportional to that triangle's area. Larger triangles therefore receive proportionally more samples than smaller ones, which produces a spatially uniform point density rather than an even count per triangle. -In order to ensure an even sampling of the total surface are of the **Triangle Geometry**, the average number of points sampled per triangle is made proportional to the area of the triangle. Within a given **Triangle**, a point is chosen using the following approach: +Within a given triangle, each point is chosen with the following formula: -![Equation 1](Images/PointSampleTriangleGeometry_Eqn1.png) +![Equation: the sampled point P equals (1 minus the square root of r1) times A, plus the square root of r1 times (1 minus r2) times B, plus the square root of r1 times r2 times C.](Images/PointSampleTriangleGeometry_Eqn1.png) -where ![](Images/PSTG_2.png) are the coordinates of the sampled point; ![](Images/PSTG_3.png), ![](Images/PSTG_4.png), and ![](Images/PSTG_5.png) are the coordinates of the vertices beloning to the **Triangle**; and ![](Images/PSTG_6.png) and ![](Images/PSTG_7.png) are random real numbers on the interval ![](Images/PSTG_8.png). This approach has the benefit of uniform sampling within the **Triangle** area, and functions correctly regardless of the dimensionality of the space embedding (i.e., whether the **Triangle** is in the plane or embedded in 3D). +where ![the sampled point coordinates P](Images/PSTG_2.png) are the coordinates of the sampled point; ![vertex A](Images/PSTG_3.png), ![vertex B](Images/PSTG_4.png), and ![vertex C](Images/PSTG_5.png) are the coordinates of the vertices belonging to the triangle; and ![random number r1](Images/PSTG_6.png) and ![random number r2](Images/PSTG_7.png) are random real numbers on the interval ![the interval from zero to one](Images/PSTG_8.png). This approach gives uniform sampling within the triangle area and works correctly regardless of the dimensionality of the embedding space (whether the triangle lies in a plane or is embedded in 3D). -The user may opt to use a mask to prevent certain **Triangles** from being sampled; where the mask is _false_, the **Triangle** will not be sampled. Additionally, the user may choose any number of **Face Attribute Arrays** to transfer to the created **Vertex Geometry**. The vertices in the new **Vertex Geometry** will gain the values of the **Faces** from which they were sampled. +### Random Sampling and Reproducibility -% Auto generated parameter table will be inserted here +The point placement is **random**: both the distribution of samples across triangles and the location of each point within its triangle are drawn from a pseudo-random number generator. By default a new seed is used each run, so the output point cloud differs from run to run. To obtain repeatable results, enable *Use Seed for Random Generation* and supply a fixed *Seed Value*; the seed actually used is also stored in an output array so a run can be reproduced later. + +### Masking and Transferred Data + +The user may opt to use a **mask** (a boolean per-face flag) to prevent certain triangles from being sampled; where the mask is *false*, the triangle is not sampled. Additionally, the user may choose any number of **Face Attribute Arrays** to transfer to the created **Vertex Geometry**. Each vertex in the new geometry inherits the values of the face from which it was sampled. -## Example Pipelines +### Required Input Sources + +- **Triangle Geometry to Sample** -- a **Triangle Geometry** (surface mesh), typically produced by [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Areas** -- a single-component per-face area array, produced by [Compute Triangle Areas](ComputeTriangleAreasFilter.md). +- **Mask** (optional) -- a boolean per-face array, typically produced by a thresholding filter such as [Multi-Threshold Objects](MultiThresholdObjectsFilter.md). + +% Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/QuickSurfaceMeshFilter.md b/src/Plugins/SimplnxCore/docs/QuickSurfaceMeshFilter.md index 3938111fa9..16b0b4ba12 100644 --- a/src/Plugins/SimplnxCore/docs/QuickSurfaceMeshFilter.md +++ b/src/Plugins/SimplnxCore/docs/QuickSurfaceMeshFilter.md @@ -4,81 +4,67 @@ Surface Meshing (Generation) -## Deprecation Notice +## ⚠ Deprecation Notice -The "SurfaceNets" filter should be used instead. Search the filter list for "Surface Nets". +**This filter is deprecated.** Use the [Surface Nets](SurfaceNetsFilter.md) filter instead. Surface Nets produces a smoother mesh (no stair-stepping), runs faster, and includes smoothing in a single pass. This filter is retained for compatibility with legacy pipelines. ## Description -This **Filter** generates a **Triangle Geometry** from a grid **Geometry** (either an **Image Geometry** or a **RectGrid Geometry**) that represents a surface mesh of the present **Features**. The algorithm proceeds by creating a pair of **Triangles** for each face of the **Cell** where the neighboring **Cells** have a different **Feature** Id value. The meshing operation is extremely quick but can result in a surface mesh that is very "stair stepped". The user is encouraged to use a smoothing operation to reduce this "blockiness". +This **Filter** generates a **Triangle Geometry** surface mesh from a grid **Geometry** (Image or Rectilinear Grid). For every cell face shared between two different **Features** (i.e., a Feature boundary), the filter emits two triangles, producing the *stair-stepped* surface that defines the boundary of each Feature. -The user may choose any number of **Cell Attribute Arrays** to transfer to the created **Triangle Geometry**. The **Faces** will gain the values of the **Cells** from which they were created. Currently, the **Filter** disallows the transferring of data that has a *multi-dimensional* component dimensions vector. For example, scalar values and vector values are allowed to be transferred, but N x M matrices cannot currently be transferred. +The resulting mesh is "blocky" because each triangle aligns with a voxel face. To smooth it, apply [Laplacian Smoothing](LaplacianSmoothingFilter.md) afterward -- or, preferably, use [Surface Nets](SurfaceNetsFilter.md), which combines meshing and smoothing in one step. -This filter will ensure that the smaller of the 2 **FaceLabel** values will always be in the first component (component[0]). This will allow assumptions made in downstream filters to continue to work correctly. +![Example Quick Mesh Output](Images/QuickSurface_Output.png) -This filter attempts to repair the windings for a mesh. This may not be possible due to the nature of how meshes are stored in the software. See Verify Traingle Winding documentation for detailed breakdown of nuance. +*Quick Surface Mesh output without smoothing.* -For more information on surface meshing, visit the tutorial. +![Example Quick Mesh Output](Images/QuickSurface_Smooth_Output.png) ---------------- +*Quick Surface Mesh output with Laplacian Smoothing applied.* -![Example Quick Mesh Output](Images/QuickSurface_Output.png) +### Cell Data Transfer -Quick Surface Mesh output **without** any extra smoothing applied +The user may select any number of **Cell Attribute Arrays** to transfer onto the new **Triangle Geometry**. Each output **Face** inherits the values of the **Cell** it came from. Only scalar and vector arrays can be transferred; multi-dimensional component shapes (e.g., N×M matrices) are not supported. ---------------- +### Face Labels Convention -![Example Quick Mesh Output](Images/QuickSurface_Smooth_Output.png) +Each triangle gets a 2-component *Face Labels* attribute storing the two Feature IDs on either side of the boundary. The filter guarantees the smaller Feature ID is in component 0, so downstream filters can rely on a consistent ordering. -Quick Surface Mesh output **with** Laplacian Smoothing filter applied. +If a triangle borders the outer volume rather than a real Feature (i.e., the cell on one side is outside the geometry), one of its Face Labels is set to **-1**. ---------------- +### Node Types -![NodeType = 2](Images/QuickMesh_NodeType_2.png) +A *Node Type* vertex array is produced classifying each vertex by its mesh role: + +| Value | Description | +|-------|-------------| +| 2 | Vertex on the interior of a grain face | +| 3 | Vertex on a triple line (3 grains meet) | +| 4 | Vertex on a quadruple point (4 grains meet) | +| 12 | Vertex on the exterior of the mesh, on a grain face | +| 13 | Vertex on the exterior of the mesh, on a triple line | +| 14 | Vertex on the exterior of the mesh, on a quadruple point | -NodeType = 2 +![NodeType = 2](Images/QuickMesh_NodeType_2.png) ---------------- +*Node Type 2 -- interior face vertex.* ![NodeType = 3](Images/QuickMesh_NodeType_3.png) -NodeType = 3 - ---------------- +*Node Type 3 -- triple line vertex.* ![NodeType = 4](Images/QuickMesh_NodeType_4.png) -NodeType = 4 +*Node Type 4 -- quadruple point vertex.* ---------------- +### Winding -### Node Types +The filter attempts to repair mesh windings so that triangle normals point outward consistently. This may not always succeed -- see [Verify Triangle Winding](VerifyTriangleWindingFilter.md) for cases where the mesh storage scheme prevents fully consistent windings. -One of the arrays to come out of the algorithm is the "Node Type" vertex array. This array uses a value to label each vertex as to what kind of node it was determined to be during the meshing process. +### Required Input Sources -| Value | Description | -|-------|-------------| -| 2 | Node within the interior of the grain face. | -| 3 | Node along a triple line | -| 4 | Node that is a Quadruple point | -| 12 | Node that is on the exterior of the mesh | -| 13 | Node that is on the exterior of the mesh and is a triple line | -| 14 | Node that is on the exterior of the mesh and is a quadruple point | - -### Exterior or Boundary Triangles - -Each triangle that is created will have an 2 component attribute called `Face Labels` that represent the Feature ID on either -side of the triangle. If one of the triangles represents the border of the virtual box then one of the FaceLables will -have a value of -1. - -## Notes - -The Quick Mesh algorithm is very crude and naive in its implementation. This filter -along with the Laplacian Smoothing filter can give you reasonable results. The -newer filter that should replace both the Quick Mesh and the Laplacian Smoothing -filter is the "Surface Nets" surface meshing algorithm. This will create the surface -mesh and smooth in a single filter and give subjectively better results and perform -much faster at both. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). +- **Image Geometry** -- typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. ## Comparison of Surface Meshing Filters diff --git a/src/Plugins/SimplnxCore/docs/RandomizeFeatureIdsFilter.md b/src/Plugins/SimplnxCore/docs/RandomizeFeatureIdsFilter.md index f26616aacc..c45c6a50d5 100644 --- a/src/Plugins/SimplnxCore/docs/RandomizeFeatureIdsFilter.md +++ b/src/Plugins/SimplnxCore/docs/RandomizeFeatureIdsFilter.md @@ -8,13 +8,21 @@ Core (Filters) ***WARNING:** This filter can throw a pipeline terminating error (at runtime) if the number of tuples in the supplied Feature `Attribute Matrix` is less than the max value in the Feature Ids `DataArray`* -This filter will randomize a user selected "Feature Ids" array and update every container (`DataArray`, `NeighborList`, and `StringArray`) in the feature `Attribute Matrix`. This does not generate random data but instead uses the existing values and swaps the positions of the values in the array. The intended use case is primarily for visualization, so feature data does not appear as a smooth gradient. +This filter will randomize a user selected **Feature Ids** array and update every container (`DataArray`, `NeighborList`, and `StringArray`) in the Feature **Attribute Matrix**. This does not generate random data but instead uses the existing values and swaps the positions of the values in the array. The intended use case is primarily for visualization, so feature data does not appear as a smooth gradient. + +**Feature Ids** are per-cell integer labels that assign each element (voxel) of a geometry to a *Feature* (for example, a grain). The Feature **Attribute Matrix** is the container holding one tuple per Feature; its per-Feature **Attribute Arrays** (such as sizes, phases, or average orientations) and any `NeighborList` (a variable-length list of each Feature's neighbors) are re-ordered consistently with the new Feature Id assignment so the data stays internally coherent. + +This filter does not expose a random-seed parameter, so the shuffle is **not reproducible** from run to run. If you need a deterministic visualization, apply the randomization once and persist the result rather than re-running it. + +### Required Input Sources + +- A **Feature Ids** array, typically produced by a feature-segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md), and the matching Feature **Attribute Matrix** that array indexes into. % Auto generated parameter table will be inserted here ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/ReadBinaryCTNorthstarFilter.md b/src/Plugins/SimplnxCore/docs/ReadBinaryCTNorthstarFilter.md index 327b8b3aba..2096bd7e7f 100644 --- a/src/Plugins/SimplnxCore/docs/ReadBinaryCTNorthstarFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadBinaryCTNorthstarFilter.md @@ -2,13 +2,13 @@ ## Group (Subgroup) -IOFilters (Input) +IO (Input) ## Description -This **Filter** will import a NorthStar Imaging data set consisting of a single .nsihdr and one or more .nsidat files. The data is read into an Image Geometry. The user can import a subvolume instead of reading the entire data set into memory. +This **Filter** will import a NorthStar Imaging computed tomography (CT) data set consisting of a single .nsihdr and one or more .nsidat files. The data is read into an **Image Geometry**. The scan intensities are stored in a single-component `float32` array (default name *Density*) inside a **Cell Attribute Matrix** (default name *CT Scan Data*). -The user should note that when using the subvolume feature that the ending voxels are **inclusive**. +The user can import a subvolume instead of reading the entire data set into memory. The subvolume start and end values are specified in **voxels** (zero-based), and both the starting and ending voxels are **inclusive**. The .nsihdr file will be read during preflight and the .nsidat file(s) will be extracted from there. The expectation is that the .nsidat files are in the same directory as the .nsihdr files. @@ -18,6 +18,10 @@ The *Length Unit* parameter sets the physical units associated with the **Image Yoctometer, Zeptometer, Attometer, Femtometer, Picometer, Nanometer, Micrometer, Millimeter, Centimeter, Decimeter, Meter, Decameter, Hectometer, Kilometer, Megameter, Gigameter, Terameter, Petameter, Exameter, Zettameter, Yottameter, Angstrom, Mil, Inch, Foot, Mile, Fathom, Unspecified, Unknown. +## Required Input Sources + +None — this filter reads directly from a `.nsihdr`/`.nsidat` file set on disk. + % Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/ReadCSVFileFilter.md b/src/Plugins/SimplnxCore/docs/ReadCSVFileFilter.md index 064a248e34..d23da621dd 100644 --- a/src/Plugins/SimplnxCore/docs/ReadCSVFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadCSVFileFilter.md @@ -8,51 +8,55 @@ IO (Input) This **Filter** reads text data from any text-based file and imports the data into DREAM3D-NX-style arrays. The user specifies which file to import, how the data is formatted, what to call each array, and what type each array should be. -*Note:* This **Filter** is intended to read data that is column-oriented, such that each created DREAM3D-NX array corresponds to a column of data in the text file. Therefore, this **Filter** will only import scalar arrays. If multiple columns are in fact different components of the same array, then the columns may be imported as separate arrays and then combined in the correct order using the Combine Attribute Arrays **Filter**. +*Note:* This **Filter** is intended to read data that is column-oriented, such that each created DREAM3D-NX array corresponds to a column of data in the text file. Therefore, this **Filter** will only import scalar arrays. If multiple columns are in fact different components of the same array, then the columns may be imported as separate arrays and then combined in the correct order using the [Combine Attribute Arrays](CombineAttributeArraysFilter.md) filter. ### Filling Out The Inputs The user first selects the **Input Text File** path, which then enables the rest of the interface. -![Input Text File Field](Images/Read_CSV_1.png) +![Selecting the input text file path](Images/Read_CSV_1.png) If the chosen **Input Text File** already has headers inside the file, the user can select the **Input File Has Headers** checkbox. This enables the **Headers Line Number** spin box where the user can select which line of the file contains the headers. *NOTE*: The interface only allows importing data starting at the line after the chosen **Headers Line Number**. So, in the example below, the **Headers Line Number** is set to 1, so **Start Import Line Number** defaults to 2 and has a range of 2-297 (this particular input file has 297 total lines). The max range of **Headers Line Number** is, of course, set to 296 so that at least 1 line can be imported. -![Input Text File Field](Images/Read_CSV_2.png) +![Setting the headers line number and start import line number](Images/Read_CSV_2.png) The user can choose how the data is delimited: comma (,), tab, semicolon (;) or space ( ). The user may also elect to ignore consecutive delimiters, which treats consecutive delimiters as one delimiter. -![Input Text File Field](Images/Read_CSV_3.png) +![Choosing the column delimiter](Images/Read_CSV_3.png) The user can select the number of preview lines available by changing the **Number of Preview Lines** spin box. The range in the example is set to 1-296 because the import is currently starting at row 2 (from **Start Import Line Number** spin box). -![Input Text File Field](Images/Read_CSV_4.png) +![Adjusting the number of preview lines](Images/Read_CSV_4.png) The user can then set the data format for each column. Selecting one or more columns will enable the **Column Data Type** combo box, where you can choose a data type or decide to skip importing specific columns as well. -![Input Text File Field](Images/Read_CSV_5.png) -![Input Text File Field](Images/Read_CSV_6.png) +![Selecting columns to set the column data type](Images/Read_CSV_5.png) +![Choosing a data type for the selected columns](Images/Read_CSV_6.png) If the **Input File Has Headers** checkbox is OFF, then it is also possible to double-click the headers in the Preview Table to edit them. These values will be used as the name of the **Data Array** in DREAM3D-NX. *NOTE:* Editing table headers is only available when the **Input File Has Headers** checkbox is OFF. If the **Input File Has Headers** checkbox is ON, then the headers will be read from the **Headers Line Number** in the data file, and the table headers will not be editable. -![Input Text File Field](Images/Read_CSV_7.png) +![Editing column header names in the preview table](Images/Read_CSV_7.png) The user can select the tuple dimensions that will be applied to the imported arrays. -![Input Text File Field](Images/Read_CSV_8.png) +![Setting the tuple dimensions for the imported arrays](Images/Read_CSV_8.png) The imported arrays can be stored in an existing attribute matrix or data group, or a new attribute matrix can be created. -![Input Text File Field](Images/Read_CSV_9.png) +![Choosing the destination attribute matrix or data group](Images/Read_CSV_9.png) Afterwards, you end up with a data structure that looks like this: -![Input Text File Field](Images/Read_CSV_10.png) +![Resulting data structure after import](Images/Read_CSV_10.png) + +## Required Input Sources + +None — this filter reads directly from a text/CSV file on disk. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ReadDREAM3DFilter.md b/src/Plugins/SimplnxCore/docs/ReadDREAM3DFilter.md index fceb2b32e7..4ad0f9161f 100644 --- a/src/Plugins/SimplnxCore/docs/ReadDREAM3DFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadDREAM3DFilter.md @@ -1,8 +1,28 @@ # Read DREAM3D-NX File +## Group (Subgroup) + +IO (Input) + ## Description -This **Filter** reads the data structure from an hdf5 file with the .dream3d extension. This filter is capable of reading from legacy .dream3d files also. +This filter reads data from a `.dream3d` file into the pipeline. A `.dream3d` file is an HDF5-based file (HDF5 is a portable, self-describing container format for large scientific datasets) that stores a complete DREAM3D-NX **DataStructure** — its geometries, **Attribute Matrix** groups, and **Data Array**s. + +### Selective (Partial) Import + +The filter does not have to read the entire file. Through the *Import File Path* parameter, the user can browse the structure of the selected `.dream3d` file and choose exactly which data objects to import. Selecting only the objects that are needed avoids loading large arrays that the rest of the pipeline does not use, which saves memory and time. To import everything, simply select all objects. + +### How Imported Objects Are Added + +The selected objects are added into the pipeline's current **DataStructure** at the same paths they had in the file. If an object being imported has the same path as an object already present in the current **DataStructure**, the existing object is replaced (overwritten) by the imported one, so take care when reading into a non-empty **DataStructure**. Any pipeline metadata stored in the file may also be read when the file is opened. + +### Legacy Files + +This filter can also read **legacy** `.dream3d` files — those written by the older DREAM3D 6.x / SIMPL-era applications. Such files use an earlier internal layout, and this filter converts them to the current **DataStructure** format on import. + +### Required Input Sources + +None — this filter reads directly from a `.dream3d` file on disk. % Auto generated parameter table will be inserted here @@ -12,4 +32,8 @@ ALL ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** + +## DREAM3D-NX Help + +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/ReadDeformKeyFileV12Filter.md b/src/Plugins/SimplnxCore/docs/ReadDeformKeyFileV12Filter.md index 925989129e..4c1e1cb721 100644 --- a/src/Plugins/SimplnxCore/docs/ReadDeformKeyFileV12Filter.md +++ b/src/Plugins/SimplnxCore/docs/ReadDeformKeyFileV12Filter.md @@ -6,9 +6,43 @@ SimulationIO (SimulationIO) ## Description -This **Filter** reads DEFORM v12 key files and saves the data in a newly created **Data Container**. +This filter reads a **DEFORM** version 12 "key file" and imports its mesh and field data into a newly created **Quad Geometry**. **DEFORM** is a commercial finite-element simulation package for metal-forming processes (such as forging, extrusion, and rolling). A DEFORM *key file* is the text results file the software exports; it contains the simulation mesh together with the values of physical variables computed at each node and element. -It reads the quadrilateral mesh data (nodal coordinates and connectivity), and the value of variables such as stress, strain, ndtmp, etc at cells and nodes. +### What the Filter Creates + +The filter builds a **Quad Geometry** — a surface mesh made of four-sided (quadrilateral) elements — from the key file. The **Quad Geometry** holds: + +- **Node coordinates**: the positions of the mesh nodes (vertices). +- **Connectivity**: which four nodes form each quadrilateral element. + +Alongside the geometry, the filter creates two attribute groups for the field variables stored in the key file: + +- **Vertex (node) data**: variables defined at each node, such as `ndtmp` (nodal temperature). +- **Cell (element) data**: variables defined at each element, such as stress and strain. + +The units of each imported variable are whatever DEFORM exported them in (for example temperature in degrees Celsius, or stress in MPa); the filter does not convert units. + +### Example Input Structure + +A DEFORM v12 key file is a keyword-driven text file. Each block begins with a keyword followed by the data for that block — for example, a node-coordinate block, an element-connectivity block, and one block per nodal or element variable: + +```text +RZ + 1 0.000000 0.000000 + 2 0.500000 0.000000 + .. +ELMCON + 1 1 2 5 4 + .. +NDTMP + 1 20.000000 + 2 20.000000 + .. +``` + +### Required Input Sources + +None — this filter reads directly from a DEFORM v12 key file on disk. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ReadHDF5DatasetFilter.md b/src/Plugins/SimplnxCore/docs/ReadHDF5DatasetFilter.md index 6247254de6..106d991dee 100644 --- a/src/Plugins/SimplnxCore/docs/ReadHDF5DatasetFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadHDF5DatasetFilter.md @@ -6,37 +6,59 @@ Core (IO/Read) ## Description -This **Filter** allows the user to import datasets from an HDF5 file and store them as attribute arrays in DREAM3D-NX. This filter supports importing datasets with any number of dimensions, as long as the created attribute array's total number of components and the tuple count of the destination attribute matrix multiply together to match the HDF5 dataset's total number of elements. +This filter imports one or more datasets from an HDF5 file and stores each one as a **Data Array** in DREAM3D-NX. HDF5 (Hierarchical Data Format version 5) is a binary file format that organizes named datasets inside a tree of groups, much like files inside folders on a disk. -The component dimensions are input as a comma-delimited list of dimensional values. For example: +When the filter is configured, the user browses the structure of the selected HDF5 file and checks one or more datasets to import. Multiple datasets can be selected and imported in a single pass; each checked dataset becomes its own Data Array. For every checked dataset the user supplies how that dataset's elements should be split into **tuple dimensions** and **component dimensions**: -1. 3, 4 = 3x4 -2. 5, 2, 1 = 5x2x1 -3. 6 = 6 +- **Tuple dimensions** describe how many elements (tuples) the array holds — for example, the number of voxels or rows of data. +- **Component dimensions** describe how many values belong to each tuple — for example, a 3-component vector stores 3 values per tuple. -### Examples +![Fig. 1: The flat HDF5 dataset is reshaped into a Data Array of tuples × components; the element count must equal (product of tuple dimensions) × (product of component dimensions).](Images/ReadHDF5Dataset_TuplesComponents.png) -1. Suppose we have a 1D dataset in an HDF5 file with dimension **12,000**. - We can input component dimensions of **5, 2, 2** and set the destination attribute matrix tuple dimensions to **35 x 5 x 2 x 2** +The filter places the imported array either at the top level of the **Data Structure** or, if the user selects an existing **Data Group** or **Attribute Matrix** as the parent, inside that container. When an Attribute Matrix is chosen as the parent, the tuple dimensions are taken automatically from that Attribute Matrix and do not need to be entered. -+ The total number of elements for the HDF5 dataset is 12,000. -+ The total number of tuples in the destination attribute matrix is 35\*5\*2\*2 = 700. -+ The total number of components for the created attribute array is 5\*2\*2 = 20. -+ The total number of elements for the created attribute array will be 700\*20 = 14,000. +### How It Works -14,000 does not equal 12,000, so this will result in a preflight error. +The import only succeeds when the math is consistent: the total number of elements actually stored in the HDF5 dataset must equal the number of tuples multiplied by the number of components per tuple. -2. Suppose we have a 3D dataset in an HDF5 file with dimensions **1 x 16 x 1001 x 1001**. -We can input component dimensions of **2** and set our destination attribute matrix tuple dimensions to **134 x 67**. +``` +HDF5 dataset element count == (product of tuple dimensions) x (product of component dimensions) +``` -+ The total number of elements for the HDF5 dataset is 1\*16\*1001\*1001 = 16,032,016. -+ The total number of tuples in the destination attribute matrix is 8\*1001\*1001 = 8,016,008. -+ The total number of components for the created attribute array is 2. -+ The total number of elements for the created attribute array will be 8,016,008\*2 = 16,032,016. -+ The total number of elements of the created attribute array (16,032,016) equals the total number of elements of the HDF5 dataset (16,032,016), so we can import this dataset without errors (see below). +If these two totals do not match, the filter reports a preflight error and nothing is imported. + +The component dimensions are entered as a comma-separated list. For example: + +1. `3, 4` means 3 x 4 = 12 components per tuple +2. `5, 2, 1` means 5 x 2 x 1 = 10 components per tuple +3. `6` means 6 components per tuple + +### Worked Examples + +**Example 1 (valid):** Suppose an HDF5 file contains a 1D dataset with **12,000** elements. + +- The user enters component dimensions of `2` (so 2 components per tuple). +- The user enters tuple dimensions of `6000` (so 6,000 tuples). +- Check: 6,000 tuples x 2 components = 12,000 elements, which equals the HDF5 dataset element count of 12,000. The dataset imports successfully. + +**Example 2 (invalid):** Suppose an HDF5 file contains a 1D dataset with **12,000** elements. + +- The user enters component dimensions of `5, 2, 2` (so 5 x 2 x 2 = 20 components per tuple). +- The user enters tuple dimensions of `35, 5, 2, 2` (so 35 x 5 x 2 x 2 = 700 tuples). +- Check: 700 tuples x 20 components = 14,000 elements, which does not equal the HDF5 dataset element count of 12,000. The filter reports a preflight error. + +**Example 3 (valid, multi-dimensional dataset):** Suppose an HDF5 file contains a dataset whose stored dimensions are **16 x 1001 x 1001**, for a total of 16 x 1001 x 1001 = 16,032,016 elements. + +- The user enters component dimensions of `2` (so 2 components per tuple). This means there must be 16,032,016 / 2 = 8,016,008 tuples. +- The user enters tuple dimensions of `8, 1001, 1001` (so 8 x 1001 x 1001 = 8,016,008 tuples). +- Check: 8,016,008 tuples x 2 components = 16,032,016 elements, which equals the HDF5 dataset element count of 16,032,016. The dataset imports successfully. ![Example Image](Images/ImportHDF5Dataset_ui.png) +## Required Input Sources + +None — this filter reads directly from an external `.h5`/`.hdf5` file on disk. The imported array may optionally be placed into an existing **Data Group** or **Attribute Matrix** if one is selected as the parent. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ReadImageFilter.md b/src/Plugins/SimplnxCore/docs/ReadImageFilter.md index 8684f93a39..b73401e0de 100644 --- a/src/Plugins/SimplnxCore/docs/ReadImageFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadImageFilter.md @@ -6,7 +6,9 @@ IO (Input) ## Description -Reads a single 2D image file into a newly created Image Geometry. This filter does not depend on ITK. It uses stb_image for PNG/JPEG/BMP files and libtiff for TIFF files. +Reads a single 2D image file into a newly created **Image Geometry**. To read a numbered sequence of slices into a 3D volume instead, use [Read Images [3D Stack]](ReadImageStackFilter.md). + +This filter does not depend on ITK. It uses stb_image for PNG/JPEG/BMP files and libtiff for TIFF files. The following image types are supported: @@ -17,7 +19,7 @@ The following image types are supported: ### Origin & Spacing Caveats -The user can optionally override the origin and spacing (length units per pixel) for the imported image. The default values from the input file will be used unless the user explicitly enables the "Set Origin" and/or "Set Spacing" options. +The user can optionally override the origin and spacing for the imported image. *Spacing* is the physical size of each pixel and *Origin* is the coordinate of the lower-left corner of the geometry; both are expressed in the same physical length units (for example microns). The default values from the input file will be used unless the user explicitly enables the "Set Origin" and/or "Set Spacing" options. When setting a custom origin, the user can choose whether to place the origin at the corner of the geometry (default) or at the center of the geometry by enabling the "Put Input Origin at the Center of Geometry" option. @@ -50,6 +52,10 @@ The user can crop the incoming 2D image using the Cropping Options section. The Both subvolume cropping types have checkboxes to turn on/off cropping in the X and Y dimensions. For example, if **Physical Subvolume** is selected and only **Crop Y Dimension** is enabled, the image will be cropped in the Y dimension only using physical coordinate bounds. +## Required Input Sources + +None — this filter reads directly from a single image file on disk. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ReadImageStackFilter.md b/src/Plugins/SimplnxCore/docs/ReadImageStackFilter.md index 8bfdb21328..f58c87e044 100644 --- a/src/Plugins/SimplnxCore/docs/ReadImageStackFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadImageStackFilter.md @@ -1,4 +1,4 @@ -# Read Image Stack +# Read Images [3D Stack] ## Group (Subgroup) @@ -6,7 +6,7 @@ IO (Input) ## Description -Reads a numbered sequence of 2D image files and stacks them into a 3D volume. This filter does not depend on ITK; it uses stb_image for PNG/JPEG/BMP files and libtiff for TIFF files. The per-slice read is delegated to the **Read Image** filter, so any option available there (data type conversion, origin/spacing overrides, 2D cropping) is also available per-slice here. +Reads a numbered sequence of 2D image files and stacks them into a 3D volume. This filter does not depend on ITK; it uses stb_image for PNG/JPEG/BMP files and libtiff for TIFF files. The per-slice read is delegated to the [Read Image](ReadImageFilter.md) filter, so any option available there (data type conversion, origin/spacing overrides, 2D cropping) is also available per-slice here. Supported image types: @@ -15,6 +15,10 @@ Supported image types: - BMP (via stb) - TIFF / TIF (via libtiff) +### File List and Slice Ordering + +The stack is defined by a file list rather than a single file. The user supplies an input directory plus a numeric naming pattern (a file prefix, suffix, file extension, and the start/end index with a padding digit count). The filter expands that pattern into an ordered list of files, where each file becomes one Z-slice of the resulting 3D volume. The first file in the list becomes Z = 0, the next file Z = 1, and so on, so the numeric ordering of the file names directly determines the slice order along the Z axis. The total number of files becomes the Z dimension of the created **Image Geometry**. + ### Processing Order Image operations are applied in the following order: @@ -27,7 +31,7 @@ Image operations are applied in the following order: ### Origin & Spacing Caveats -The filter will create a new Image Geometry. The user can optionally override the origin and spacing for the created geometry. The default values from the input files will be used unless the user explicitly enables the "Set Origin" and/or "Set Spacing" options. +The filter will create a new **Image Geometry**. The user can optionally override the origin and spacing for the created geometry. *Spacing* is the physical size of each voxel and *Origin* is the coordinate of the lower-left-back corner of the volume; both are expressed in the same physical length units (for example microns). The default values from the input files will be used unless the user explicitly enables the "Set Origin" and/or "Set Spacing" options. ### Origin & Spacing Processing @@ -64,7 +68,7 @@ The user can optionally resample each image as it is read in. The *Resample Imag ### Grayscale Conversion -When *Convert To GrayScale* is enabled, RGB image data is converted to a scalar grayscale array using the luminosity algorithm with the supplied *Color Weighting* values. Only uint8 input data is supported for grayscale conversion. +When *Convert To GrayScale* is enabled, RGB image data is converted to a scalar grayscale array using the luminosity algorithm. The luminosity algorithm computes each gray value as a weighted sum of the red, green, and blue channels (gray = wR·R + wG·G + wB·B), where the weights come from the supplied *Color Weighting* values (dimensionless). This produces a perceptually weighted brightness rather than a simple channel average. Only uint8 input data is supported for grayscale conversion. ### Output Data Type @@ -88,6 +92,10 @@ Both subvolume cropping types have checkboxes to turn on/off cropping in each of The user can select to flip the images about the X or Y axis during import. +## Required Input Sources + +None — this filter reads from a file list of image files on disk. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ReadNIfTIFileFilter.md b/src/Plugins/SimplnxCore/docs/ReadNIfTIFileFilter.md index 983a12d4cb..eabf585ffb 100644 --- a/src/Plugins/SimplnxCore/docs/ReadNIfTIFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadNIfTIFileFilter.md @@ -15,10 +15,10 @@ The filter transparently handles both uncompressed (`.nii`) and gzipped comparing `sizeof_hdr` against the expected value of 348. NIfTI-1 allows a variable-length extension block between the 348-byte -header and the voxel data. The filter honors `vox_offset` and seeks -past the extension block before reading voxels — any custom extension -metadata (DICOM attributes, AFNI XML, etc.) is **skipped, not -preserved**. +header and the voxel data. The filter honors `vox_offset` (the byte offset +in the file where the voxel data begins) and seeks past the extension +block before reading voxels — any custom extension metadata (DICOM +attributes, AFNI XML, etc.) is **skipped, not preserved**. ### Supported voxel datatypes @@ -41,10 +41,19 @@ Complex and 128-bit float types are not currently supported. ### Orientation -When *Use Stored Affine Transform* is enabled (the default), the filter uses +NIfTI stores up to two affine transforms that map voxel indices to physical +space: the `sform` ("standard" transform, a general affine matrix) and the +`qform` ("quaternion" transform, a rigid rotation plus translation). When +*Use Stored Affine Transform* is enabled (the default), the filter uses the NIfTI `sform` transform (if `sform_code > 0`) or `qform` transform (if `qform_code > 0`) to set the **Image Geometry** origin and spacing. If neither -is set, the filter falls back to `pixdim[1..3]` for spacing and a zero origin. +is set, the filter falls back to `pixdim[1..3]` (the per-axis voxel size +stored in the header) for spacing and a zero origin. + +The spacing units are whatever the source file recorded (most commonly +millimeters for medical NIfTI data) and are **not** converted by this +filter. Treat the resulting **Image Geometry** spacing as being in the +file's native physical units. simplnx Image Geometries are axis-aligned; if the stored transform contains a non-trivial rotation, only the spacing (column magnitudes) and origin are @@ -53,8 +62,10 @@ native storage order. ### Data scaling -When *Apply Scaling Transform* is enabled and the header specifies a -non-trivial scaling (`scl_slope != 0` and (`scl_slope != 1` or +NIfTI can store a linear intensity rescaling defined by two header fields: +`scl_slope` (the multiplicative slope) and `scl_inter` (the additive +intercept). When *Apply Scaling Transform* is enabled and the header +specifies a non-trivial scaling (`scl_slope != 0` and (`scl_slope != 1` or `scl_inter != 0`)), the filter computes `y = scl_slope * x + scl_inter` at read time and promotes the output array to `float32`. Per the NIfTI-1 specification, scaling is never applied to `RGB24` or `RGBA32` data and a @@ -129,18 +140,6 @@ version: In short: use cropping to keep the output DataArray small, not to make large compressed files read faster. -## Parameters - -| Parameter | Type | Default | Description | -|---|---|---|---| -| Input NIfTI File | File path | — | Path to the `.nii` or `.nii.gz` file to read. | -| Use Stored Affine Transform | Bool | `true` | Use `sform`/`qform` to set origin + spacing when present. | -| Apply Scaling Transform | Bool | `true` | Apply `y = slope*x + inter` at read time; promotes to float32. | -| Cropping Options | CropGeometry | `NoCropping` | Optional voxel-index or physical-coordinate sub-volume. Only the selected region is retained in the output DataArray; data outside the region is read but never stored. | -| Image Geometry | Data Path | `NIfTI Image` | Path to the created Image Geometry. | -| Cell Attribute Matrix Name | String | `Cell Data` | Name of the attribute matrix holding voxel values. | -| Image Data Array Name | String | `ImageData` | Name of the array receiving voxel values. | - ## Caveats * Only the single-file NIfTI-1 format (magic `n+1`) is supported. The @@ -163,7 +162,11 @@ large compressed files read faster. * `start <= end` is required on each cropped axis; reversed ranges are rejected at parameter-validation time. -% Auto generated parameter table will be inserted here +## Required Input Sources + +None — this filter reads directly from a `.nii` or `.nii.gz` file on disk. + +% Auto generated parameter table will be inserted here ## Reference diff --git a/src/Plugins/SimplnxCore/docs/ReadRawBinaryFilter.md b/src/Plugins/SimplnxCore/docs/ReadRawBinaryFilter.md index 108db506ba..da7fc63087 100644 --- a/src/Plugins/SimplnxCore/docs/ReadRawBinaryFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadRawBinaryFilter.md @@ -75,6 +75,10 @@ The output array can be placed in two ways: 2. **Standalone**: Select an output path that is not inside an Attribute Matrix (e.g., `MyArray`). The user must provide explicit tuple dimensions via the *Set Tuple Dimensions* checkbox and table. +### Required Input Sources + +None — this filter reads directly from a raw binary file on disk. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ReadStlFileFilter.md b/src/Plugins/SimplnxCore/docs/ReadStlFileFilter.md index 0e5de47d6e..a6a0c961d4 100644 --- a/src/Plugins/SimplnxCore/docs/ReadStlFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReadStlFileFilter.md @@ -6,40 +6,44 @@ IO (Input) ## Description -This **Filter** will read a binary STL File and create a **Triangle Geometry** object in memory. The STL reader is very strict to the STL specification. An explanation of the STL file format can be found on [Wikipedia](https://en.wikipedia.org/wiki/STL). The structure of the file is as follows: +An STL file describes a 3D surface as a list of triangles. This filter reads a **binary** STL file from disk and creates a **Triangle Geometry** (a surface mesh made of triangular faces) in memory, along with a *Face Normals* array (one 3-component normal vector per triangle) and, optionally, a *Face Labels* array. + +The vertex coordinates in an STL file are plain numbers with no embedded unit. They are in whatever length unit the file's author intended (often millimeters or inches), so the reader treats them as dimensionless and copies them through unchanged. + +**Only binary STL files are supported. ASCII STL files are not read by this filter; the filter will report an error if given one.** An ASCII STL file can be converted to binary using a separate 3D mesh tool before reading. + +An explanation of the STL file format can be found on [Wikipedia](https://en.wikipedia.org/wiki/STL_(file_format)). The binary structure is: UINT8[80] Header - UINT32 Number of triangles + UINT32 Number of triangles foreach triangle REAL32[3] Normal vector REAL32[3] Vertex 1 REAL32[3] Vertex 2 REAL32[3] Vertex 3 - UINT16 Attribute byte count + UINT16 Attribute byte count end -The filter will look for specific header information to try and determine the vendor of the STL file. Certain vendors do not write STL files that adhere to the file spec. +The filter inspects the header to try to determine the vendor of the STL file, because some vendors do not write files that strictly follow the specification. -## IMPORANT NOTES: +## IMPORTANT NOTES -**It is very important that the "Attribute byte Count" is correct as DREAM3D-NX follows the specification strictly.** If you are writing an STL file be sure that the value for the "Attribute byte count" is *zero* (0). If you chose to encode additional data into a section after each triangle then be sure that the "Attribute byte count" is set correctly. DREAM3D-NX will obey the value located in the "Attribute byte count". +The reader follows the STL specification strictly and obeys the "Attribute byte count" value written after each triangle. If you are writing an STL file, set the "Attribute byte count" to *zero* (0) unless you are deliberately encoding extra data after each triangle, in which case the count must exactly match the number of extra bytes. An incorrect "Attribute byte count" is the most common cause of read failures, because the reader will skip the number of bytes the file claims are present. -## Known Vendors who Write out of spec STL Files +## Known Vendors Who Write Out-of-Spec STL Files - Materialise Magics [https://www.materialise.com/en/industrial/software/magics-data-build-preparation](https://www.materialise.com/en/industrial/software/magics-data-build-preparation) - The filter looks in the header for "COLOR=" and "MATERIAL=" strings in the header. + The filter looks in the header for "COLOR=" and "MATERIAL=" strings. - Creaform VXelements [https://www.creaform3d.com/en/metrology-solutions/3d-applications-software-platforms](https://www.creaform3d.com/en/metrology-solutions/3d-applications-software-platforms) - + The filter looks for "VXelements" in the header. -## Code to convert +## Code to Convert -If you find yourself in a situation where the STL File is non-conforming and is not made by one of the vendors above, this bit of Python -code can clean up the file. This makes the absolute assumption that the **ONLY** thing wrong with the STL file is that the trailing UINT16 value for -each triangle needs to be set to ZERO. +If you have a non-conforming STL file that was not made by one of the vendors above, the Python snippet below can clean it up. It assumes the **ONLY** problem with the file is that the trailing UINT16 "Attribute byte count" value for each triangle needs to be set to zero. import struct @@ -48,24 +52,24 @@ each triangle needs to be set to ZERO. # Read and copy header header = input_file.read(80) output_file.write(header) - + # Read number of triangles num_triangles = struct.unpack(' [Greater Than] [1]**: Targets **Cells** whose value is greater than the threshold. The replacement neighbor is the one with the lowest value among neighbors that fall below the threshold. +1. For every cell, compare its value of the *Selected Array* to the *Threshold Value* using the *Comparison Operator* (less-than or greater-than). +2. For each cell that passes the comparison (i.e., is flagged for replacement), examine its 6 face-neighbors. +3. Among the neighbors that do **not** pass the comparison, find the one with the maximum (when operator is `<`) or minimum (when operator is `>`) value of the same scalar. This is the "best" neighbor. +4. Copy **all** cell-level arrays in the same attribute matrix from that best neighbor into the flagged cell. -*Note:* By default, the **Filter** will run only one iteration of the cleanup. If the user selects the *Loop Until Gone* -option, then the **Filter** will run iteratively until no **Cells** exist that meet the users criteria. So, if a **Cell** -meets the threshold and so are all of its neighbors, then that **Cell** will not be changed during that iteration and -will remain unchanged until one of its neighbors gets changed by a **Cell** further away. +If a flagged cell has only flagged neighbors (i.e., none of its neighbors pass the threshold), it is left unchanged in this pass. -## Examples +### Comparison Operator -### TSL Data (.ang) File +- **< [Less Than] [0]**: Targets cells whose scalar is **less than** the threshold. Replacement neighbor is the one with the **highest** scalar value among neighbors that exceed the threshold. Use this for measures where higher = better (Confidence Index, Image Quality). +- **> [Greater Than] [1]**: Targets cells whose scalar is **greater than** the threshold. Replacement neighbor is the one with the **lowest** scalar value among neighbors that fall below the threshold. Use this for measures where lower = better (Mean Angular Deviation, scan error metrics). -When attempting to "clean up" EBSD data generated by EDAX/TSL the Attribute Array "Confidence Index" can be used. -Confidence Index is a measure of how confident in the indexing results given by the OIM Analysis software and ranges -from 0.0 (No confidence) to 1.0 (Absolute confidence). More information about the Confidence Index can be found in the -OIM analysis user manual. Typical inputs for TSL (.ang) Data might be the following. +### Loop Until Gone -| Filter Parameter | Value | -|------------------|-----------------------------------------------| -| Threshold Value | 0.1 | -| Operator | < | -| Selected Array | [DataContainer] / CellData / Confidence Index | -| Loop Until Gone | User dependent | +By default, the filter runs a **single pass**. If a flagged cell's neighbors are all flagged in that pass, the cell is left alone. Enabling *Loop Until Gone* repeats the algorithm until every flagged cell has been replaced (typically because flag-replacements propagate inward across multiple passes). + +### Caution: Flood Fill Behavior + +If the threshold is set too aggressively or the dataset has large contiguous regions of low-quality cells, *Loop Until Gone* can act like a flood-fill, propagating one neighbor's data across an entire region. The end result may bear little resemblance to the true microstructure. Always inspect the output and, if grain morphology has shifted dramatically, lower the *Threshold Value* or run a single pass. + +| Original Data | Threshold CI < 0.1 | After Running Filter | True Data | +|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------|----------------------------------------------| +| ![Original Data](Images/NeighborReplace_No_Cleanup.png) | ![Original Data. Black pixels have Confidence Index < 0.1](Images/NeighborReplace_No_Cleanup_Mask.png) | ![Text](Images/NeighborReplace_After_Cleanup.png) | ![Text](Images/NeighborReplace_Exemplar.bmp) | -Using these values says that for every cell that has a confidence index < 0.1 it's neighbor cells will be considered. If -the neighbor cell has a confidence > 0.1 AND is greater than the other neighbors then this cell's data will be copied -into the original cell data location. +The example above shows what happens when too much of the data is below threshold: most fine grains and twins do **not** match the true microstructure. -### Example EDAX Results +## Example Use Cases -**Reasonable Use of the Filter** +### Reasonable Use of the Filter | Original Data | | After Running Filter | True Data | |-----------------------------------------------------------|-----|-----------------------------------------------------|----------------------------------------------| | ![Original Data](Images/NeighborReplace_No_Cleanup_2.png) | | ![Text](Images/NeighborReplace_After_Cleanup_2.png) | ![Text](Images/NeighborReplace_Exemplar.bmp) | -**Example of Too Much Replacement** +### TSL Data (.ang) -- Using Confidence Index -| Original Data | Threshold CI < 0.1 | After Running Filter | True Data | -|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------|----------------------------------------------| -| ![Original Data](Images/NeighborReplace_No_Cleanup.png) | ![Original Data. Black pixels have Confidence Index < 0.1](Images/NeighborReplace_No_Cleanup_Mask.png) | ![Text](Images/NeighborReplace_After_Cleanup.png) | ![Text](Images/NeighborReplace_Exemplar.bmp) | +EDAX/TSL ANG files include a *Confidence Index* (CI) array that ranges from 0.0 (no confidence) to 1.0 (absolute confidence). To clean up cells with poor indexing, use: -Note how in the above use of the filter the grain morphology is substantially changed from the exemplar data. Except for -very large grains being similar most of the fine grains and twins are **NOT** reproduced from the original. +| Filter Parameter | Value | +|------------------|-----------------------------------------------| +| Threshold Value | 0.1 | +| Operator | < | +| Selected Array | [DataContainer] / CellData / Confidence Index | +| Loop Until Gone | User dependent | + +This says: for every cell with CI < 0.1, find the neighbor with the highest CI among those above 0.1, and copy that neighbor's data into the cell. -### Oxford/Bruker (.ctf) File +### Oxford/Bruker (.ctf) -- Using Error -Oxford Instruments and Bruker CTF data files do not include a "Confidence Index" measure. There are several measures -such as *Mean Angular Deviation (MAD)* or *Bands* but these values are not filled in or are defaulted to 0 (Zero) if the -scan point was not indexed. By using the *Error* value from the data file we can get the same effect as the EDAX -*Confidence Index*. The user would use the following input values: +CTF files do not include a Confidence Index, but they do have an *Error* value that defaults to 0 for indexed points and is non-zero for non-indexed points. This is the inverse direction from CI: | Filter Parameter | Value | |------------------|------------------------------------| @@ -74,14 +70,15 @@ scan point was not indexed. By using the *Error* value from the data file we can | Selected Array | [DataContainer] / CellData / Error | | Loop Until Gone | User dependent | -### Example Oxford/Bruker Results - | Original Data | After Running Filter | |---------------------------------------------------------|-------------------------------------------| | ![Original Data](Images/NeighborReplace_CTF_Before.png) | ![](Images/NeighborReplace_CTF_After.png) | -Note the large areas of unindexed pixels in the original image (black pixels) and how they are all filled in. The filter -can act much like a generic "flood fill" image processing algorithm if used improperly. +The black pixels in the original are unindexed cells (Error > 0) and are filled in by the filter. + +### Required Input Sources + +- **Selected Scalar Array** -- any single-component cell-level scalar suitable for thresholding. Common sources: confidence/quality arrays from [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), [Read CTF Data](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read ANG Data](../OrientationAnalysis/ReadAngDataFilter.md), or any computed per-cell scalar. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/RequireMinNumNeighborsFilter.md b/src/Plugins/SimplnxCore/docs/RequireMinNumNeighborsFilter.md index 5596f74021..887351a8c8 100644 --- a/src/Plugins/SimplnxCore/docs/RequireMinNumNeighborsFilter.md +++ b/src/Plugins/SimplnxCore/docs/RequireMinNumNeighborsFilter.md @@ -6,17 +6,27 @@ Processing (Cleanup) ## Description -This **Filter** sets the minimum number of contiguous neighboring **Features** a **Feature** must have to remain in the structure. Entering zero results in nothing changing. Entering a number larger than the maximum number of neighbors of any **Feature** generates an *error* (since all **Features** would be removed). The user needs to proceed conservatively here when choosing the value for the minimum to avoid accidentally exceeding the maximum. After **Features** are removed for not having enough neighbors, the remaining **Features** are *coarsened* iteratively, one **Cell** per iteration, until the gaps left by the removed **Features** are filled. Effectively, this is an isotropic **Feature** growth in the regions around removed **Features**. +This **Filter** removes **Features** that have fewer than the user-specified number of contiguous neighbors. The most common use case is cleaning up isolated single-feature islands left over from segmentation -- features whose surroundings turned out to be too sparsely connected to support a meaningful grain. After flagged features are removed, the remaining features grow outward via [isotropic coarsening](RequireMinimumSizeFeaturesFilter.md) until every cell is reassigned. -The **Filter** can be run in a mode where the minimum number of neighbors is applied to a single **Ensemble**. The user can select to apply the minimum to one specific **Ensemble**. +The threshold is a **count of contiguous neighbors** (a non-negative integer). Setting the threshold to 0 removes nothing. Setting it larger than the maximum number of neighbors any feature has produces an error (since all features would be removed). Inspect the *Number of Neighbors* output of [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) before choosing a threshold. + +### Apply to Single Phase + +When *Apply to Single Phase* is enabled, the threshold is applied only to features of the specified phase. Features of other phases are untouched regardless of how many neighbors they have. This is useful when isolated features are noise in one phase but meaningful in another. ## WARNING: Feature Data Will Become Invalid -By modifying the cell level data, any feature data that was previously computed will most likely be invalid at this point. Filters that compute feature level data should be rerun to ensure accurate final results from your pipeline. +By modifying cell-level data, any feature-level data that was previously computed will most likely be invalid after this filter runs. Re-run any downstream feature-level computation filters to ensure accurate results. ## WARNING: NeighborList Removal -If 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. +If the Cell Feature **Attribute Matrix** contains any *NeighborList* arrays, they will be **removed** because the neighbor relationships have changed. Re-run [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) afterward to rebuild them. + +### 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). +- **Number of Neighbors** -- produced by [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md). +- **Feature Phases** (only when *Apply to Single Phase* is enabled) -- produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). % Auto generated parameter table will be inserted here @@ -24,7 +34,6 @@ If the Cell Feature AttributeMatrix contains any *NeighborList* data arrays, tho + (02) Small IN100 Full Reconstruction - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/SimplnxCore/docs/RequireMinimumSizeFeaturesFilter.md b/src/Plugins/SimplnxCore/docs/RequireMinimumSizeFeaturesFilter.md index d3a1c185b3..f106557a1f 100644 --- a/src/Plugins/SimplnxCore/docs/RequireMinimumSizeFeaturesFilter.md +++ b/src/Plugins/SimplnxCore/docs/RequireMinimumSizeFeaturesFilter.md @@ -6,17 +6,43 @@ Processing (Cleanup) ## Description -This **Filter** removes **Features** that have a total number of **Cells** below the minimum threshold defined by the user. Entering a number larger than the largest **Feature** generates an *error* (since all **Features** would be removed). Hence, a choice of threshold should be carefully chosen if it is not known how many **Cells** are in the largest **Features**. After removing all the small **Features**, the remaining **Features** are isotropically coarsened to fill the gaps left by the small **Features**. +This **Filter** removes small **Features** from a segmented dataset and fills in the space they leave behind by expanding their neighbors. Features whose cell count is below the user-specified *Minimum Allowed Features Size* are erased; the remaining features grow outward into the erased cells until every cell is reassigned to a surviving feature. -The **Filter** can be run in a mode where the minimum number of neighbors is applied to a single **Ensemble**. The user can select to apply the minimum to one specific **Ensemble**. +This is typically used immediately after segmentation ([Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or similar) to discard spurious single-cell or few-cell "grains" that are almost always noise rather than real features. + +### How This Filter Works + +1. For each **Feature**, look up its cell count from the input *Feature Num. Cells* array. +2. If the feature's count is below the threshold, mark it for removal. All of its cells are temporarily set to Feature Id 0 ("unassigned"). +3. After all small features are removed, the remaining features are *isotropically coarsened* to fill the gaps. + +### What is Isotropic Coarsening? + +"Isotropic coarsening" is an iterative dilation that grows each surviving feature outward by one cell layer at a time, uniformly in all directions. On each pass, an unassigned cell is given the Feature Id of whichever neighbor feature touches it; if multiple features touch it, one is picked. The process repeats until no unassigned cells remain. The result is that every removed cell is absorbed into the closest surviving feature, with no preferred direction. + +### Minimum Size Units + +The *Minimum Allowed Features Size* is in **cells** (integer voxel count), not physical units. A threshold of 10 means "remove any feature with fewer than 10 cells," regardless of the image's spacing. To convert a physical-volume threshold into a cell count, divide by the product of the cell spacing (dx * dy * dz). + +Entering a number larger than the size of the largest feature produces an error, since every feature would be removed. If the size distribution is unknown, compute feature sizes first with [Compute Feature Sizes](ComputeFeatureSizesFilter.md) and inspect the range. + +### Apply to Single Phase + +When *Apply to Single Phase* is enabled, the size threshold is applied only to features of the specified phase. Features of other phases are untouched regardless of their size. This is useful when small features are noise in one phase but meaningful in another (e.g., small precipitates in a matrix). ## WARNING: Feature Data Will Become Invalid -By modifying the cell level data, any feature data that was previously computed will most likely be invalid at this point. Filters that compute feature level data should be rerun to ensure accurate final results from your pipeline. +By modifying the cell-level Feature Ids, any feature-level data that was previously computed (sizes, centroids, average orientations, etc.) will almost certainly be invalid after this filter runs. Re-run any feature-level computation filters downstream of this one to ensure accurate results. ## WARNING: NeighborList Removal -If 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. +If the Cell Feature **Attribute Matrix** contains any *NeighborList* arrays, they will be **removed** because the list of neighbors for each surviving feature has changed. Re-run [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) afterward to rebuild the neighbor relationships. + +### 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). +- **Feature Num. Cells** -- the cell count per feature, produced by [Compute Feature Sizes](ComputeFeatureSizesFilter.md). +- **Feature Phases** (only when *Apply to Single Phase* is enabled) -- produced by [Compute Feature Phases](ComputeFeaturePhasesFilter.md). % Auto generated parameter table will be inserted here @@ -24,7 +50,6 @@ If the Cell Feature AttributeMatrix contains any *NeighborList* data arrays, tho + (02) Small IN100 Full Reconstruction - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/SimplnxCore/docs/ResampleImageGeomFilter.md b/src/Plugins/SimplnxCore/docs/ResampleImageGeomFilter.md index cbaf8036ba..4fb2600e17 100644 --- a/src/Plugins/SimplnxCore/docs/ResampleImageGeomFilter.md +++ b/src/Plugins/SimplnxCore/docs/ResampleImageGeomFilter.md @@ -6,75 +6,56 @@ Sampling (Resample) ## Description -This **Filter** changes the **Cell** spacing/resolution based on inputs from the user. There are several resampling modes: +This **Filter** changes the cell resolution of an **Image Geometry** by overlaying a new regular grid on the existing data and copying the *closest-cell* value from the old grid to each new cell. No interpolation is performed. -### Resampling Mode - -The *Resampling Mode* parameter provides the following choices: - -- **Spacing (0) [0]**: The entered values are the desired new spacings (not multiples of the current resolution). The number of cells in the volume will change accordingly. -- **Scaling (1) [1]**: The entered values are the desired scaling factor for each dimension, expressed as percentages. -- **Exact Dimensions (2) [2]**: The entered values are the desired cell dimensions of the resampled geometry. - -## WARNING: NeighborList Removal - -If the option to "Renumber Features" is turn ON 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. - -### Spacing - -The values entered are the desired new spacings (not multiples of the current resolution). The number of **Cells** in the volume will change when the spacing values are changed and thus the user should be cautious of generating "too many" **Cells** by entering very small values (i.e., very high resolution). +The overall **bounds** of the volume do not change -- only the spacing and the number of cells. To scale the physical extent of a geometry, apply a scaling transformation with [Apply Transformation To Geometry](ApplyTransformationToGeometryFilter.md) instead. -**Example 1**: +![Fig. 1: Resampling overlays a new grid of a different spacing on the same physical volume; doubling the spacing along an axis halves the cell count there. Each new cell takes the value of the nearest source cell — no interpolation is performed.](Images/ResampleImageGeom_SpacingCellCount.png) -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). - -If the new spacing value is (2, 2, 2), then the geometry will have cell dimensions (262, 195, 82) and spacing (2, 2, 2). - -**Example 2**: - -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). - -If the new spacing value is (0.25, 0.7, 2.3), then the geometry will have cell dimensions (2096, 557, 71) and spacing (0.25, 0.7, 2.3). - -### Scale Factor +### Resampling Mode -The values entered are the desired scaling factor for each dimension, in percentages. +The *Resampling Mode* parameter provides three ways to specify the new grid: -**Example 1**: +- **Spacing [0]**: Set the new spacing directly (in physical units; same as the input geometry's spacing). The cell count adjusts accordingly. Use small spacings cautiously -- they can produce very large cell counts. +- **Scaling [1]**: Scale spacing by a percentage per axis. A scaling factor of 30% reduces cell count to roughly 30% of the original (and increases spacing by ~3.33x). +- **Exact Dimensions [2]**: Set the exact new cell counts per axis (integer). Spacing is computed automatically to span the original bounds. -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). +#### Spacing Examples -If the new scaling value is (30%, 30%, 30%), then the geometry will have cell dimensions (157, 117, 49) and spacing (3.3333, 3.3333, 3.3333). +Image with cell dimensions (524, 390, 164) and spacing (1, 1, 1) (units in microns/voxel). -**Example 2**: +- New spacing (2, 2, 2) → cell dimensions (262, 195, 82), spacing (2, 2, 2) microns/voxel. +- New spacing (0.25, 0.7, 2.3) → cell dimensions (2096, 557, 71), spacing (0.25, 0.7, 2.3). -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). +#### Scaling Examples -If the new scaling value is (120.4%, 50.74%, 68.12%), then the geometry will have cell dimensions (630, 197, 111) and spacing (0.830565, 1.97083, 1.468). +Same starting image. -### Exact Dimensions +- Scaling (30%, 30%, 30%) → cell dimensions (157, 117, 49), spacing (3.333, 3.333, 3.333). +- Scaling (120.4%, 50.74%, 68.12%) → cell dimensions (630, 197, 111), spacing (0.831, 1.971, 1.468). -The values entered are the desired cell dimensions of the resampled geometry. (100, 100, 100) would resample the geometry so that there are 100 cells in each dimension. +#### Exact Dimensions Examples -**Example 1**: +Same starting image. -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). +- Exact dimensions (100, 100, 100) → cell dimensions (100, 100, 100), spacing (5.24, 3.9, 1.64). +- Exact dimensions (100, 500, 20) → cell dimensions (100, 500, 20), spacing (5.24, 0.78, 8.2). -If the new exact dimensions are (100, 100, 100), then the geometry will have cell dimensions (100, 100, 100) and spacing (5.24, 3.9, 1.64). +### Resampling Algorithm -**Example 2**: +A new regular grid is overlaid on the old one. For each new cell, the filter finds the old cell whose center is closest and copies that old cell's attributes (Feature Ids, phases, orientations, etc.) into the new cell. There is **no interpolation** -- this is the right behavior for label data (Feature Ids), but it does mean that small features can disappear during downsampling. -Image Geometry with cell dimensions (524, 390, 164) and spacing (1, 1, 1). +### Renumber Features -If the new exact dimensions are (100, 500, 20), then the geometry will have cell dimensions (100, 500, 20) and spacing (5.24, 0.78, 8.2). +When downsampling produces a result in which some Features no longer have any cells, those Features become invalid. Enable *Renumber Features* to detect this case, resize the Cell Feature Attribute Matrix to drop the empty features, and renumber the remaining features so that Feature IDs remain contiguous starting at 1. ---- +## WARNING: NeighborList Removal -A new grid of **Cells** is created and "overlaid" on the existing grid of **Cells**. There is currently no *interpolation* performed, rather the attributes of the old **Cell** that is closest to each new **Cell's** is assigned to that new **Cell**. +When *Renumber Features* is enabled and the Cell Feature Attribute Matrix contains any *NeighborList* arrays, those arrays are **removed** because they refer to the old (pre-renumber) Feature IDs. Re-run [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md) afterward to rebuild them. -*Note:* Present **Features** may disappear when down-sampling to coarse resolutions. If *Renumber Features* is checked, the **Filter** will check if this is the case and resize the corresponding **Feature Attribute Matrix** to comply with any changes. Additionally, the **Filter** will renumber **Features** such that they remain contiguous. +### Required Input Sources -*Note:* This filter does NOT change the overall bounds of the volume, just the spacing and number of cells in the volume. To change the overall bounds of the volume, apply a scaling transformation with the [Apply Transformation To Geometry](./ApplyTransformationToGeometryFilter.md) filter. +- **Input Image Geometry** -- the geometry to be resampled. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ResampleRectGridToImageGeomFilter.md b/src/Plugins/SimplnxCore/docs/ResampleRectGridToImageGeomFilter.md index bbc146e6ed..6ef84c23b2 100644 --- a/src/Plugins/SimplnxCore/docs/ResampleRectGridToImageGeomFilter.md +++ b/src/Plugins/SimplnxCore/docs/ResampleRectGridToImageGeomFilter.md @@ -6,13 +6,30 @@ Sampling (Sampling) ## Description -This **Filter** will resample an existing RectilinearGrid onto a regular grid (Image Geometry) and copy cell data into the newly created Image Geometry Data Container during the process. +This **Filter** converts a **Rectilinear Grid Geometry** (which has variable spacing along each axis) into an **Image Geometry** (which has uniform spacing along each axis). Selected cell-level arrays from the rectilinear grid are copied onto the new uniform grid using a *last-one-wins* rule. -The sampling algorithm is a simple "last one wins" algorithm due to the likely hood that interpolating data is probably not the correct algorithm to bring in data to the new Image Geometry. +### When to Use This Filter -The algorithm logic is thus: If the ImageGeometry cell would contain multiple RectilinearGrid cells, then we select from the covered cells the cell with the largest X, Y and Z index and copy that data into the Image Geometry Cell Attribute Matrix. +Many downstream filters and most external visualization tools expect uniform-grid data. This filter is the right choice when: -The user can select which cell attribute matrix data arrays will be copied into the newly created Image Geometry Cell Attribute Matrix. +- You have data on a variable-spacing rectilinear grid (e.g., imported from a simulation or instrument that uses non-uniform sampling). +- You need uniform Image Geometry data for downstream processing. +- The data being resampled is *categorical* (Feature Ids, phase labels) and interpolation would produce nonsensical intermediate values. + +For interpolatable scalar data (intensity, density), prefer a true resampling filter with interpolation rather than this filter. + +### Algorithm + +If a single Image Geometry cell covers multiple Rectilinear Grid cells, the filter selects the rectilinear cell with the **largest X, Y, and Z index** among the covered cells and copies that one's data. This is a deterministic "last one wins" rule chosen because interpolating across categorical data would be incorrect. + +The user selects: + +- The target Image Geometry's dimensions, origin, and spacing. +- Which cell-level Attribute Arrays from the rectilinear grid should be copied onto the new geometry. + +### Required Input Sources + +- **Rectilinear Grid Geometry** -- the source geometry. Typically produced by [Create Geometry](CreateGeometryFilter.md) with type Rectilinear Grid, or imported from an external simulation. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ReshapeDataArrayFilter.md b/src/Plugins/SimplnxCore/docs/ReshapeDataArrayFilter.md index cf73edcd11..60211190f7 100644 --- a/src/Plugins/SimplnxCore/docs/ReshapeDataArrayFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReshapeDataArrayFilter.md @@ -6,17 +6,33 @@ Core (Generation) ## Description -This **Filter** is used to modify the tuple shape of Data Arrays, Neighbor Lists, and String Arrays within a data structure. It validates the new tuple dimensions to ensure they are positive and differ from the current shape, preventing unnecessary or invalid reshapes. +This **Filter** updates the **tuple dimensions** (the *shape* metadata) of an existing **Data Array**, **Neighbor List**, or **String Array** in place. The total number of tuples is unchanged; only how the shape is described is changed. -**THIS FILTER DOES NOT MOVE ANY THE VALUES IN MEMORY. IT SIMPLY UPDATES THE TUPLE DIMENSIONS. This means that if the data does not -have the proper stride for the new dimensions this could result in incorrect results.** +## ⚠ CRITICAL WARNING: Values Are Not Reordered -For example if a data set is read in from an HDF5 file with a tuple dimension of 3 x 45 this means that there are 45 columns -and 3 rows. If this data is supposed to be interpreted as 3D points, using this data within DREAM3D-NX would not -work because DREAM3D-NX is "C" ordered and the dimensions should be 3 columns x 45 rows. Using this filter will -**NOT** result the correct ordering of the data because the filter will not move any data in memory. +**This filter does NOT move any data in memory.** It only updates the tuple-dimensions metadata. If the data's existing memory layout does not match the new shape's expected layout, **the filter will silently produce incorrectly-shaped data** that downstream filters will misinterpret. -**NOTE:** If the input array is a Neighbor List or String Array, the filter will throw a warning if the new tuple dimensions are multi-dimensional. This is because these array types do not support multi-dimensional tuple dimensions and the filter will default to reshaping the data to an equivalent 1-dimensional number of tuples. +### When This Is Safe vs Dangerous + +DREAM3DNX uses **C-order (row-major)** layout: the last dimension varies fastest in memory. So `(3, 45)` is stored as 3 rows × 45 columns -- 3 contiguous chunks of 45 values each. + +- **Safe**: changing `(135)` → `(3, 45)` simply tells the system "treat this 135-tuple array as a 3×45 array". The bytes in memory are the same; only the shape interpretation changes. +- **Safe**: changing `(3, 45)` → `(135)` flattens to 1D. Memory is identical. +- **DANGEROUS**: reading an array from an HDF5 file that was stored 3 rows × 45 columns and trying to use it as 3-component 45-vertex data. In DREAM3DNX, 3-vertex data is stored as `(N, 3)` with 3 contiguous values per tuple. Calling Reshape from `(3, 45)` to `(45, 3)` **does not transpose** -- it just relabels the shape, and the bytes are now in the wrong order for the new shape. + +To actually transpose or reorder data, use external preprocessing (e.g., reshape the HDF5 dataset before reading) or use an array-arithmetic filter to manually rebuild the array with the desired ordering. + +### Validation + +The filter validates that the new tuple dimensions are positive and that the total tuple count matches the array's existing total. A shape change that would alter the total tuple count fails preflight. + +### Neighbor Lists and String Arrays + +Neighbor Lists and String Arrays do not support multi-dimensional tuple shapes. If you specify a multi-dimensional new shape for one of these array types, the filter emits a warning and falls back to an equivalent 1-D tuple count. + +### Required Input Sources + +- **Array to Reshape** -- any **Data Array**, **Neighbor List**, or **String Array** in the Data Structure. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/ReverseTriangleWindingFilter.md b/src/Plugins/SimplnxCore/docs/ReverseTriangleWindingFilter.md index d6b97553aa..fbf92d32aa 100644 --- a/src/Plugins/SimplnxCore/docs/ReverseTriangleWindingFilter.md +++ b/src/Plugins/SimplnxCore/docs/ReverseTriangleWindingFilter.md @@ -6,11 +6,15 @@ Surface Meshing (Connectivity/Arrangement) ## Description -This **Filter** reverses the *winding* for each **Triangle** in a **Triangle Geometry**. This will *reverse* the direction of calculated **Triangle** normals. Some analysis routines require the normals to be pointing "away" from the center of a **Feature**. This **Filter** allows for manipulation of this construct. +This **Filter** reverses the **winding** of every **Triangle** in a **Triangle Geometry**. The *winding* is the order in which a triangle's three vertices are listed; that order determines which way the triangle's normal points. Reversing the winding therefore *flips* the direction of the triangle normals so they point the opposite way. -% Auto generated parameter table will be inserted here +Some analysis routines require the normals to point "away" from the center of a **Feature**. This **Filter** lets you flip the winding so the normals point in the required direction. After reversing the winding, recompute normals with [Compute Triangle Normals](TriangleNormalFilter.md) so they reflect the new vertex order. To check whether a mesh has consistent winding before or after this operation, use [Verify Triangle Winding](VerifyTriangleWindingFilter.md). + +### Required Input Sources -## Example Pipelines +- **Triangle Geometry** -- the surface mesh whose triangle winding will be reversed. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/RobustAutomaticThresholdFilter.md b/src/Plugins/SimplnxCore/docs/RobustAutomaticThresholdFilter.md index 3042e596e9..146d27799b 100644 --- a/src/Plugins/SimplnxCore/docs/RobustAutomaticThresholdFilter.md +++ b/src/Plugins/SimplnxCore/docs/RobustAutomaticThresholdFilter.md @@ -2,15 +2,19 @@ ## Group (Subgroup) -DREAM3D Review (Threshold) +Threshold ## Description -This **Filter** automatically computes a threshold value for a scalar **Attribute Array** based on the array's gradient magnitude, producing a boolean array that is *false* where the input array is less than the threshold value and *true* otherwise. The threshold value is computed using the following equation: +This filter is *automatic* because it computes the threshold value itself, and *robust* because it derives that value from where the data changes most sharply rather than from a fixed cutoff. The user does not have to choose a threshold value manually; the filter selects one that tends to separate the input array along its sharpest boundaries. It produces a boolean **Mask** array that is *false* where the input array is less than the computed threshold and *true* otherwise. -![\f[ T = \sum_{i = 1}^{n} \frac{a_{i} g_{i}}{g_{i}} \f]](Images/latex24.png) +The threshold is computed as a gradient-magnitude-weighted average of the input array. Each value of the input array is weighted by its corresponding gradient magnitude, so **Cells** that sit on strong boundaries (high gradient magnitude) contribute most to the chosen threshold, while flat interior regions (low gradient magnitude) contribute little. The result is a single threshold value `T` that generally partitions the input array where its gradient is highest. -where \f$ a \f$ is the input array, \f$ g \f$ is the gradient magnitude array, \f$ n \f$ is the length of the input array, and \f$ T \f$ is the computed threshold value. Computing a threshold in this manner will generally partition the input array where its gradient is highest. Gradients may be computed using the Find Derivatives **Filter**. The gradient magnitude may then be found by computing the 2-norm of the gradient. +The *gradient magnitude* measures how quickly the input field changes from one location to the next: it is large at edges or boundaries and near zero in smooth regions. It is obtained by computing the *2-norm* (the square root of the sum of the squares of the per-axis derivative components) of the gradient vector at each **Cell**, which collapses the multi-component gradient into a single non-negative scalar value per **Cell**. The required gradient magnitude array can be produced with the [ITK Gradient Magnitude Image Filter](../ITKImageProcessing/ITKGradientMagnitudeImageFilter.md). + +### Required Input Sources + +- **Gradient Magnitude Data** -- a single-component 32-bit float array giving the gradient magnitude of the input array, produced by [ITK Gradient Magnitude Image Filter](../ITKImageProcessing/ITKGradientMagnitudeImageFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/RotateSampleRefFrameFilter.md b/src/Plugins/SimplnxCore/docs/RotateSampleRefFrameFilter.md index d75c6c003b..fc3797b9fe 100644 --- a/src/Plugins/SimplnxCore/docs/RotateSampleRefFrameFilter.md +++ b/src/Plugins/SimplnxCore/docs/RotateSampleRefFrameFilter.md @@ -17,7 +17,9 @@ This **Filter** is a *lossless reference-frame rotation*: the output is an exact The **Filter** enforces this in preflight. Any rotation that does **not** map the grid onto itself — an arbitrary angle (e.g. 45 degrees), or an off-group axis/angle combination such as **90 degrees about (111)** — is rejected with an error, because a nearest-neighbor resample of such a rotation would silently drop and duplicate voxels and pad the result with background values. To apply an arbitrary rotation (with interpolation), use the [Apply Transformation To Geometry](ApplyTransformationToGeometryFilter.md) filter instead. -### Rotation Representation +![Fig. 1: Rotating the sample reference frame rotates the coordinate axes and resamples the data onto the new grid, leaving the microstructure fixed (left); a geometric rotation instead rotates the data within fixed axes (right).](Images/RotateSampleRefFrame_SampleVsGeometric.png) + +### ⚠ Limited Verification The *Rotation Representation* parameter selects how the rotation is specified. Both forms must still resolve to a rotation that maps the voxel grid onto itself (see Supported Rotations above): @@ -50,6 +52,21 @@ When importing EBSD data from EDAX, the user typically rotates the sample refere - **Selected Image Geometry** -- an **Image Geometry** and all of its **Cell** arrays; produced by any image or EBSD reader, for example [Read H5EBSD File](../OrientationAnalysis/ReadH5EbsdFilter.md), [Import EDAX OIM Data (.h5)](../OrientationAnalysis/ReadH5OimDataFilter.md), or [ITK Import Images (3D Stack)](../ITKImageProcessing/ITKImportImageStackFilter.md). +### Rotation Representation + +The *Rotation Representation* parameter selects how the rotation is specified: + +- **Axis Angle [0]**: A unit axis vector (x, y, z) plus an angle in **degrees**. The most common form for single-axis rotations. +- **Rotation Matrix [1]**: A 3x3 rotation matrix entered directly. + +### Notes on the Output Origin + +The rotated geometry will most likely have an origin that differs from the input geometry's origin (see EDAX example above). If you wish to keep the input origin, enable the *Keep Input Geometry's Origin* option. By default, the option is OFF, so the transformation-derived origin is used. + +### Required Input Sources + +- **Image Geometry** -- the input image whose reference frame is being rotated. Typically produced by an EBSD reader such as [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), [Read CTF Data](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read ANG Data](../OrientationAnalysis/ReadAngDataFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/ScalarSegmentFeaturesFilter.md b/src/Plugins/SimplnxCore/docs/ScalarSegmentFeaturesFilter.md index ab536a2667..031c7de402 100644 --- a/src/Plugins/SimplnxCore/docs/ScalarSegmentFeaturesFilter.md +++ b/src/Plugins/SimplnxCore/docs/ScalarSegmentFeaturesFilter.md @@ -6,19 +6,35 @@ Reconstruction (Segmentation) ## Description -This **Filter** segments the **Features** by grouping neighboring **Cells** that satisfy the *scalar tolerance*, i.e., have a scalar difference less than the value set by the user. The process by which the **Features** are identified is given below and is a standard *burn algorithm*. +This **Filter** groups neighboring **Cells** (voxels) that have similar scalar values into **Features** (connected regions). The output is a *FeatureIds* array that assigns every cell in the input **Image Geometry** to a numbered feature, so that downstream analyses can operate on features instead of individual cells. -1. Randomly select a **Cell**, add it to an empty list and set its *FeatureId* to the current **Feature** -2. Compare the **Cell** to each of its six (6) face-sharing neighbors (i.e., calculate the scalar difference with each neighbor) -3. Add each neighbor **Cell** that has a scalar difference below the user defined tolerance to the list created in 1) and set the *FeatureId* 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 +Use this filter whenever your segmentation criterion is a single scalar value per cell -- for example, image quality, confidence index, a phase label, or a computed property. For orientation-based segmentation of EBSD data, see [Segment Features (Misorientation)](../OrientationAnalysis/EBSDSegmentFeaturesFilter.md) or [Segment Features (C-Axis Misalignment)](../OrientationAnalysis/CAxisSegmentFeaturesFilter.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. +### What is Feature Segmentation? -After all the **Features** have been identified, an **Attribute Matrix** is created for the **Features** and each **Feature** is flagged as *Active* in a boolean array in the matrix. +Segmentation groups cells that "belong together" into discrete regions. Each region receives a unique positive integer *Feature Id*; cells that are excluded (for example, by a mask) are assigned Feature Id 0. After segmentation, a new **Feature Attribute Matrix** is created so that per-feature statistics (sizes, centroids, phases, etc.) can be computed and stored. -If the data is specified as **Periodic**, the segmentation will check if features wrap around geometry bounds in a tileable fashion. If any such features are detected, the filter will throw a warning that centroid data may be incorrect. +![Fig. 1: DREAM3D-NX groups cells into features (grains) via the FeatureIds array, and features into ensembles (phases). Per-feature data lives in the Cell Feature Data attribute matrix; per-phase data lives in Cell Ensemble Data.](Images/DataModel_CellFeatureEnsemble.png) + +### How This Filter Works + +This 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. Compare the cell's scalar value to each of its neighboring cells (see **Neighbor Scheme** below). +3. Any neighbor whose scalar value differs from the seed by less than the user-specified *Scalar Tolerance* 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. + +### Tolerance and Units + +The *Scalar Tolerance* is in **the same units as the input scalar array**. There are no universal "good" values; the right tolerance depends entirely on what array you are segmenting: + +- For an integer phase map, a tolerance of 0 (or less than 1) groups only cells with exactly the same phase. +- For a floating-point image-quality array with values 0-1, tolerances around 0.05-0.1 are typical. +- For a raw grayscale image with values 0-255, tolerances of 5-20 are typical. + +Start conservative (smaller tolerance -> more, smaller features), inspect the result, and loosen the tolerance if features are being over-split. ### Neighbor Scheme @@ -27,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; switch to *All Connected* when diagonal connectivity should merge a feature that would otherwise be split. | Neighbor Scheme = "Face Only" | Neighbor Scheme = "All Connected" | |:--:|:--:| @@ -49,6 +61,19 @@ 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 valid sample regions -- for example, a quality threshold on an EBSD confidence index (see [Multi-Threshold Objects](MultiThresholdObjectsFilter.md)). + +### Periodic Option + +If the input data represents a **periodic** structure (i.e., features are allowed to wrap across opposite faces of the volume), enable *Is Periodic*. The filter will detect features that tile across the geometry bounds and emit a warning that centroid and other spatial statistics may be incorrect for those features. + +### Required Input Sources + +- **Input Scalar Array** -- any single-component cell-level scalar array suitable for thresholding. Common sources include image readers such as [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), phase or quality arrays from EBSD readers such as [Read H5EBSD](../OrientationAnalysis/ReadH5EbsdFilter.md), or any computed per-cell scalar from an earlier filter in the pipeline. +- **Mask Array** (optional) -- a boolean array marking valid cells, typically produced by [Multi-Threshold Objects](MultiThresholdObjectsFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/SetImageGeomOriginScalingFilter.md b/src/Plugins/SimplnxCore/docs/SetImageGeomOriginScalingFilter.md index d4ed868025..e4252cff3e 100644 --- a/src/Plugins/SimplnxCore/docs/SetImageGeomOriginScalingFilter.md +++ b/src/Plugins/SimplnxCore/docs/SetImageGeomOriginScalingFilter.md @@ -6,13 +6,35 @@ Core (Spatial) ## Description -This **Filter** changes the origin and/or the spacing of an **Image Geometry**. For example, if the current origin is at (0, 0, 0) and the user would like the origin to be (10, 4, 8), then the user should enter the following input values: +This **Filter** updates the origin and/or spacing of an existing **Image Geometry**. The grid dimensions (number of cells per axis) are unchanged; only the physical placement and physical size of the cells are modified. Use this filter to: -+ X Origin: 10 -+ Y Origin: 4 -+ Z Origin: 8 +- Correct an incorrect origin after import (e.g., reset to (0, 0, 0) after a sample-frame rotation). +- Convert the geometry's spacing to a different physical unit (e.g., millimeters → microns). +- Recenter a geometry so the user-specified point lands at the volume's geometric center. -When setting the origin, the user may also enable the *Put Input Origin at the Center of Geometry* option, which adjusts the geometry so that the specified origin is placed at the geometric center rather than the corner. +![Fig. 1: An Image Geometry is defined by its dimensions, spacing, and origin. This filter changes the origin (bottom-left grid point) and/or spacing (distance between grid planes); the dimensions are left unchanged.](Images/CreateImageGeometry_OriginSpacingDimensions.png) + +### Origin + +The *Origin* parameter sets the new physical location of the bottom-left corner of the geometry. For example, to change the origin from (0, 0, 0) to (10, 4, 8): + +- X Origin: 10 +- Y Origin: 4 +- Z Origin: 8 + +Origin coordinates are in the geometry's physical units (microns, millimeters, etc.). + +### Spacing + +The *Spacing* parameter sets the new physical distance between grid planes along each axis. Spacing values must be positive and non-zero. Updating spacing rescales the entire physical extent of the geometry (since the number of cells is unchanged) but leaves cell data values untouched. + +### Put Input Origin at the Center of Geometry + +If *Put Input Origin at the Center of Geometry* is enabled, the user-supplied origin value is treated as the **geometric center** of the volume rather than the bottom-left corner. The filter computes the corresponding bottom-left origin so that the user-supplied point lands at the center. This is convenient for centering a geometry on a meaningful reference point (sample center, beam axis, etc.) without computing the corner offset by hand. + +### Required Input Sources + +- **Input Image Geometry** -- the geometry to modify in place. Typically produced by [Create Image Geometry](CreateImageGeometryFilter.md), [ITK Import Image Stack](../ITKImageProcessing/ITKImportImageStackFilter.md), or an EBSD reader. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/SharedFeatureFaceFilter.md b/src/Plugins/SimplnxCore/docs/SharedFeatureFaceFilter.md index 4f0c21a6ba..eb99998c96 100644 --- a/src/Plugins/SimplnxCore/docs/SharedFeatureFaceFilter.md +++ b/src/Plugins/SimplnxCore/docs/SharedFeatureFaceFilter.md @@ -4,21 +4,24 @@ Surface Meshing (Connectivity/Arrangement) +(Note: this filter's human name is *Compute Triangle Face Ids*, even though its source file is named `SharedFeatureFace`.) + ## Description -This **Filter** assigns a unique Id to each **Triangle** in a **Triangle Geometry** that represents the _unique boundary_ -on which that **Triangle** resides. For example, if there were only two **Features** that shared one boundary, -then the **Triangles** on that boundary would be labeled with a single unique Id. This procedure creates _unique groups_ -of **Triangles**, which themselves are a set of **Features**. Thus, this **Filter** also creates a **Feature Attribute -Matrix** for this new set of **Features**, and creates **Attribute Arrays** for their Ids and number of **Triangles**. This -process can be considered a **segmentation** where each unique id is the shared boundary between two features. +This filter assigns a unique Id to each **Triangle** in a **Triangle Geometry** (a surface mesh built from triangles) that identifies the *unique boundary* on which that triangle resides. A **Feature** is a region of material; the **Face Labels** of a triangle are the pair of **Feature** Ids on either side of it. All triangles sharing the same pair of **Face Labels** form one shared boundary and receive the same unique Id. + +For example, if only two **Features** shared a single boundary, every triangle on that boundary would be labeled with one unique Id. This procedure groups the triangles into unique boundaries, which are themselves treated as a new set of **Features** (one per shared boundary). + +The filter therefore also creates a **Feature Attribute Matrix** (a table holding one row of data per shared-boundary feature) and places two **Attribute Arrays** into it: -Because the algorithm is essentially segmenting the triangles based on the unique combination of face labels, the filter will -also generate a Feature level Attribute Matrix and place two additional _DataArrays_ into that feature attribute matrix -that store the following information: +1. The number of triangles in each unique boundary. +2. The pair of **Face Labels** values that made up each unique boundary. -1. The number of triangles in each unique boundary -2. The pair of Face Label values that made up the unique boundary. +This process can be viewed as a **segmentation** in which each unique Id is the shared boundary between two features. + +### Randomize Face IDs + +The *Randomize Face IDs* parameter shuffles the assigned boundary Id values. The grouping of triangles is unchanged; only the numeric Id labels are permuted. This is purely a visualization aid: with sequential Ids, neighboring boundaries can map to similar colors and blend together, whereas randomized Ids spread adjacent boundaries across the color map so they are easier to tell apart. The two figures below illustrate the difference. ### Generated Feature Boundaries _with_ Randomization @@ -28,13 +31,16 @@ that store the following information: ![Example Surface Mesh Coloring By Feature Face Id](Images/SharedFeaturFace_2.png) ---------------- +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** -- the per-triangle pair of **Feature** Ids, produced alongside the mesh by the surface-meshing filter above. % Auto generated parameter table will be inserted here ## Example Pipelines -"(03) Small IN100 Mesh Statistics.d3dpipeline" ++ (03) Small IN100 Mesh Statistics ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/SilhouetteFilter.md b/src/Plugins/SimplnxCore/docs/SilhouetteFilter.md index 43f31ca03f..09bd6a2d6b 100644 --- a/src/Plugins/SimplnxCore/docs/SilhouetteFilter.md +++ b/src/Plugins/SimplnxCore/docs/SilhouetteFilter.md @@ -6,13 +6,15 @@ DREAM3D Review (Clustering) ## Description -This **Filter** computes the silhouette for a clustered **Attribute Array**. The user must select both the original array that has been clustered and the array of cluster Ids. The silhouette represents a measure for the quality of a clustering. Specifically, the silhouette provides a measure for how strongly a given point belongs to its own cluster compared to all other clusters. The silhouette is computed as follows: +This **Filter** computes the silhouette for a clustered **Attribute Array**. The user must select both the original array that has been clustered and the array of cluster Ids. The silhouette is a dimensionless measure of the quality of a clustering. Specifically, the silhouette provides a measure of how strongly a given point belongs to its own cluster compared to all other clusters. The silhouette is computed as follows: -\f[ s_{i} = \frac{b_{i} - a_{i}}{\max\{a_{i},b_{i}\}} \f] +$$ s_{i} = \frac{b_{i} - a_{i}}{\max\{a_{i},b_{i}\}} $$ -where \f$ a \f$ is the average distance between point \f$ i \f$ and all other points in the cluster point \f$ i \f$ belongs to, \f$ b \f$ is the *next closest* average distance among all other clusters, and \f$ s \f$ is the silhouette value. Using this definition, \f$ s \f$ exists on the interval \f$ [-1, 1] \f$, where 1 indicates that the point strongly belongs to its current cluster and -1 indicates that the point does not belong well to its current cluster. The user may select from a variety of options to use as the distance metric. Additionally, the user may opt to use a mask array to ignore points in the silhouette; these points will contain a silhouette value of 0. +where $a$ is the average distance between point $i$ and all other points in the cluster point $i$ belongs to, $b$ is the *next closest* average distance among all other clusters, and $s$ is the silhouette value. Using this definition, $s$ exists on the interval $[-1, 1]$ (dimensionless), where 1 indicates that the point strongly belongs to its current cluster and -1 indicates that the point does not belong well to its current cluster. The user may select from a variety of options to use as the distance metric. Additionally, the user may opt to use a mask array to ignore points in the silhouette; these points will contain a silhouette value of 0. -The silhouette can be used to determine how well a particular clustering has performed, such as k means or k medoids. +The filter writes one float silhouette value per input point into the created silhouette array, located alongside the input array. Each value lies in the range $[-1, 1]$ (dimensionless). + +The silhouette can be used to determine how well a particular clustering has performed, such as a clustering produced by [Compute K Means](ComputeKMeansFilter.md) or [Compute K Medoids](ComputeKMedoidsFilter.md). ### Distance Metric @@ -25,13 +27,18 @@ The *Distance Metric* parameter controls how the distance between two points is - **Pearson [4]**: Correlation-based distance derived from the Pearson correlation coefficient. - **Squared Pearson [5]**: Square of the Pearson distance. +### Required Input Sources + +- **Cluster Ids** -- the per-point cluster label array, produced by [Compute K Means](ComputeKMeansFilter.md) or [Compute K Medoids](ComputeKMedoidsFilter.md). +- **Clustered Attribute Array** -- the original **Attribute Array** that was clustered (the same array passed to the clustering filter). + % Auto generated parameter table will be inserted here ## Example Pipelines ## License & Copyright -Please see the description file distributed with this plugin. +Please see the description file distributed with this **Plugin** ## DREAM3D-NX Help diff --git a/src/Plugins/SimplnxCore/docs/SliceTriangleGeometryFilter.md b/src/Plugins/SimplnxCore/docs/SliceTriangleGeometryFilter.md index 445a39d67a..36017f7b1b 100644 --- a/src/Plugins/SimplnxCore/docs/SliceTriangleGeometryFilter.md +++ b/src/Plugins/SimplnxCore/docs/SliceTriangleGeometryFilter.md @@ -6,7 +6,9 @@ Sampling (Geometry) ## Description -This **Filter** slices an input **Triangle Geometry**, producing an **Edge Geometry**. The user can control the range over which to slice (either the entire range of the geoemtry or a specified subregion), and the spacing bewteen slices. Currently this filter only supports slicing along the direction of the z axis. The total area and perimieter of each slice is also computed and stored as an attribute on each created slice. +This **Filter** slices an input **Triangle Geometry**, producing an **Edge Geometry**. The user can control the range over which to slice (either the entire range of the geometry or a specified subregion), and the spacing between slices. Currently this filter only supports slicing along the direction of the z axis. The total area and perimeter of each slice is also computed and stored as an attribute on each created slice. + +Both the *Slice Spacing* and the *User Defined Range* values are specified in the same physical units as the input **Triangle Geometry** coordinates (for example, microns if the mesh is in microns). The computed slice area and perimeter are likewise reported in those physical units (squared, for area). Additionally, if the input **Triangle Geometry** is labeled with an identifier array (such as different regions or features), the user may select this array and the resulting edges will inherit these identifiers. @@ -26,7 +28,11 @@ Example Surface Mesh being sliced with a 2.0 slice spacing. The *Slice Range* parameter controls which portion of the geometry is sliced: - **Full Range [0]**: Slices across the entire extent of the geometry along the slicing direction. -- **User Defined Range [1]**: Allows specifying custom start and end values for the slicing range, restricting slices to a subregion of the geometry. +- **User Defined Range [1]**: Allows specifying custom start and end values (in the geometry's physical units) for the slicing range, restricting slices to a subregion of the geometry. + +### Required Input Sources + +- **Triangle Geometry** -- an existing surface mesh. Typically produced by [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md), read from disk via [Read STL File](ReadStlFileFilter.md), or assembled from multiple files by [Combine STL Files](CombineStlFilesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/SplitDataArrayByComponentFilter.md b/src/Plugins/SimplnxCore/docs/SplitDataArrayByComponentFilter.md index 6afce43553..f558c0bb31 100644 --- a/src/Plugins/SimplnxCore/docs/SplitDataArrayByComponentFilter.md +++ b/src/Plugins/SimplnxCore/docs/SplitDataArrayByComponentFilter.md @@ -18,14 +18,18 @@ This **Filter** will produce three new scalar unsigned 8-bit arrays: The user must specify a postfix string to add to the newly created arrays. For example, if the original multicomponent **Attribute Array** is named "Foo" and the postfix is set to "Component", this **Filter** will produce three new arrays named "FooComponent0", "FooComponent1", and "FooComponent2". The numbering will always be present regardless of how the postfix is set. -There is an alternative option which allows the user to select a subset of components to extract instead of extracting all the components by entering the components to be extracted. The components should be specified starting with the first componet as 0. So if the original array has 3 components and the user wanted the first and second components, the unput to the component table should be 0 and 1 respectively. +An alternative *Select Components* option lets the user extract a subset of components rather than all of them. Components are **0-based** -- for a 3-component array, entering 0 and 1 extracts only the first two components. -This **Filter** is the opposite operation of the Combine Attribute Arrays **Filter**, and the generalized version of the Extract Component as Attribute Array **Filter**. +This **Filter** is the inverse of [Combine Attribute Arrays](CombineAttributeArraysFilter.md), and a generalized version of [Extract/Remove Components](ExtractComponentAsArrayFilter.md). **Looking to split by *tuples* instead?** See the *[Split Data Array (By Tuple)](SplitDataArrayByTupleFilter.md)* filter that separates a data array into several smaller data arrays based on the tuple layout. +### Required Input Sources + +- **Multi-Component Input Array** -- any multi-component **Attribute Array**. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/SplitDataArrayByTupleFilter.md b/src/Plugins/SimplnxCore/docs/SplitDataArrayByTupleFilter.md index bddb3f935b..d80710aedf 100644 --- a/src/Plugins/SimplnxCore/docs/SplitDataArrayByTupleFilter.md +++ b/src/Plugins/SimplnxCore/docs/SplitDataArrayByTupleFilter.md @@ -50,6 +50,14 @@ An optional flag allows you to delete the original input array after splitting. See the *[Split Data Array (By Component)](SplitDataArrayByComponentFilter.md)* filter that separates each component into its own scalar array. +### Tuple Counts + +The per-output *tuple counts* are integers. The sum of all requested output counts along the split dimension must equal the input's tuple count along that dimension. + +### Required Input Sources + +- **Input Data Array** -- the array to split. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/SurfaceNetsFilter.md b/src/Plugins/SimplnxCore/docs/SurfaceNetsFilter.md index 81a3b1a1b1..27e66f1230 100644 --- a/src/Plugins/SimplnxCore/docs/SurfaceNetsFilter.md +++ b/src/Plugins/SimplnxCore/docs/SurfaceNetsFilter.md @@ -6,22 +6,25 @@ Surface Meshing (Generation) ## Description -This filter uses the algorithm from {1} to produce a triangle surface mesh. The code is directly based on the sample code from the paper but has been modified to -work with the simplnx library classes. This filter uses a different algorithm that aims to produce a mush that keeps sharp edges -while still producing a mesh superior to marching cubes or QuickMesh. +This filter generates a **Triangle Geometry** (a surface mesh) that wraps the boundaries between labeled regions in a volume. It uses the **Surface Nets** algorithm from {1}. The code is based directly on the sample code from that paper, modified to work with the simplnx library classes. + +Unlike **marching cubes** (a classic algorithm that builds an isosurface by placing triangles inside each cube of eight neighboring **Cells**), Surface Nets keeps sharp edges between materials while still producing a mesh that is generally smoother and higher quality than either marching cubes or the older [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) approach. + +An **isosurface** is the surface that separates regions above a threshold from regions below it; for a labeled volume the "threshold" is simply the boundary between one **Feature** label and a different one. From the abstract of the paper: - We extend 3D SurfaceNets to generate surfaces of segmented 3D medical images composed - of multiple materials represented as indexed labels. Our extension generates smooth, high- - quality triangle meshes suitable for rendering and tetrahedralization, preserves topology and - sharp boundaries between materials, guarantees a user-specified accuracy, and is fast enough - that users can interactively explore the trade-off between accuracy and surface smoothness. +> We extend 3D SurfaceNets to generate surfaces of segmented 3D medical images composed +> of multiple materials represented as indexed labels. Our extension generates smooth, high- +> quality triangle meshes suitable for rendering and tetrahedralization, preserves topology and +> sharp boundaries between materials, guarantees a user-specified accuracy, and is fast enough +> that users can interactively explore the trade-off between accuracy and surface smoothness. + +The filter writes a **Face Labels** array on each triangle: a 2-component value holding the **Feature** Id on either side of the triangle. The filter guarantees the smaller of the two Face Labels values is always stored in the first component (component 0), so that assumptions made in downstream filters continue to work correctly. -This filter will ensure that the smallest of the 2 **FaceLabel** values will always be in the first component (component[0]). This will allow assumptions made in -downstream filters to continue to work correctly. +The filter also attempts to repair the triangle **winding** (the order in which a triangle's three vertices are listed, which determines the direction its normal points). A fully consistent winding may not be achievable because of how meshes are stored in the software; see [Verify Triangle Winding](VerifyTriangleWindingFilter.md) for a detailed breakdown of the nuances. -This filter attempts to repair the windings for a mesh. This may not be possible due to the nature of how meshes are stored in the software. See Verify Traingle Winding documentation for detailed breakdown of nuance. +The *Relaxation Iterations* parameter is a dimensionless count of smoothing passes, and *Max Distance from Voxel Center* is a physical length (same units as the Image Geometry spacing) limiting how far a node may move from its originating voxel center. --------------- @@ -39,12 +42,11 @@ SurfaceNets output **with** the built-in smoothing operation applied. ## Node Types -During the meshing process, each vertex, or node, will get a "Node Type" value assigned to it. These will range from 0 to 6. The value is an internal representation from the SurfaceNets algorithm. They are roughly equivelent to the Node Types from the Quick Surface Mesh algorithm but not strictly the same. - -- Node Type = 0: This is a node that ONLY has 2 features connected to the node. -- Node Type = 2: This is a node that has 3 features connected to the node, such as a triple line -- Node Type = 3-6: These nodes have 4 or more features connected to the node. +During the meshing process, each vertex (node) is assigned a "Node Type" value ranging from 0 to 6. The value is an internal representation from the Surface Nets algorithm. The values are roughly equivalent to the Node Types from the [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) algorithm but are not strictly the same. +- Node Type = 0: A node that has ONLY 2 features connected to it. +- Node Type = 2: A node that has 3 features connected to it, such as a **triple line** (the edge where exactly three features meet). +- Node Type = 3-6: Nodes that have 4 or more features connected to them. | Node Type | Example Image | |-----------|----------------------------------------------| @@ -56,20 +58,22 @@ During the meshing process, each vertex, or node, will get a "Node Type" value a ### Exterior or Boundary Nodes -Nodes that appear on the exterior of a volume have Node Type values starting at 10 and going up from there. For instance, a triple line that is also on the exterior of the volume should have a value of 12. +Nodes that appear on the exterior of a volume have Node Type values starting at 10 and going up from there. For instance, a triple line that is also on the exterior of the volume has a value of 12. ![Exterior Node Types](Images/SurfaceNets_NodeType_Exterior.png) ### Exterior or Boundary Triangles -Each triangle that is created will have an 2 component attribute called `Face Labels` that represent the Feature ID on either -side of the triangle. If one of the triangles represents the border of the virtual box then one of the FaceLables will -have a value of -1. +Each triangle has a 2-component **Face Labels** array that holds the Feature Id on either side of the triangle. If a triangle lies on the border of the virtual bounding box, one of its Face Labels values is -1. ## Notes -This filter should be used in place of the "QuickMesh Surface Filter". +This filter should be used in place of the [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) filter. + +### Required Input Sources +- **Image Geometry** -- the labeled volume to mesh, from an image/volume reader or an upstream processing filter. +- **Cell Feature Ids** -- the per-Cell integer label array that defines the regions to wrap, typically produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). ## Comparison of Surface Meshing Filters @@ -92,19 +96,18 @@ DREAM3D-NX provides three **Filters** that convert a segmented grid into a multi ## Example Pipelines - Pipelines/SimplnxCore/SurfaceNets_Demo.d3dpipeline +Pipelines/SimplnxCore/SurfaceNets_Demo.d3dpipeline ## Citations -{1}[SurfaceNets for Multi-Label Segmentations with Preservation of Sharp Boundaries](https://jcgt.org/published/0011/01/03/paper.pdf) +{1} [SurfaceNets for Multi-Label Segmentations with Preservation of Sharp Boundaries](https://jcgt.org/published/0011/01/03/paper.pdf) + +Sarah F. Frisken, *SurfaceNets for Multi-Label Segmentations with Preservation of Sharp Boundaries*, Journal of Computer Graphics Techniques (JCGT), vol. 11, no. 1, 34-54, 2022. [http://jcgt.org/published/0011/01/03](http://jcgt.org/published/0011/01/03) ## License & Copyright -`Sarah F. Frisken, SurfaceNets for Multi-Label Segmentations with Preservation of Sharp -Boundaries, Journal of Computer Graphics Techniques (JCGT), vol. 11, no. 1, 34–54, 2022` -[http://jcgt.org/published/0011/01/03](http://jcgt.org/published/0011/01/03) +Please see the description file distributed with this **Plugin** -## DREAM3D-NX Mailing Lists +## DREAM3D-NX Help -If you need more help with a **Filter**, please consider asking your question on -the [DREAM3D-NX Users Google group!](https://groups.google.com/forum/?hl=en#!forum/dream3d-users) +If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions. diff --git a/src/Plugins/SimplnxCore/docs/TriangleCentroidFilter.md b/src/Plugins/SimplnxCore/docs/TriangleCentroidFilter.md index 545dcfb1f6..0e2fb65c15 100644 --- a/src/Plugins/SimplnxCore/docs/TriangleCentroidFilter.md +++ b/src/Plugins/SimplnxCore/docs/TriangleCentroidFilter.md @@ -6,7 +6,21 @@ Surface Meshing (Misc) ## Description -This **Filter** computes the centroid of each **Triangle** in a **Triangle Geometry** by calculating the average position of all 3 **Vertices** that make up the **Triangle**. +This filter computes the centroid of each **Triangle** in a **Triangle Geometry** (a surface mesh built from triangles) by averaging the positions of the 3 **vertices** (nodes) that make up the triangle, and stores the result as a per-triangle **Face Data** array. + +### When to Use This Filter + +A per-triangle centroid gives a single representative point for each triangle. It is commonly used as a position reference when fitting a local neighborhood of triangles (for example, by [Compute Feature Face Curvature](FeatureFaceCurvatureFilter.md)) and when visualizing or sampling per-face quantities at a point rather than across the whole triangle. + +Note: this filter produces one centroid **per triangle**. To instead compute one centroid **per Feature** (averaged over all the nodes that bound a feature), use [Compute Feature Centroids from Triangle Geometry](ComputeTriangleGeomCentroidsFilter.md). + +### Units + +Centroid coordinates are reported in the **geometry length units** of the **Triangle Geometry** vertices (for example, micrometers if the mesh coordinates are stored in micrometers). + +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/TriangleDihedralAngleFilter.md b/src/Plugins/SimplnxCore/docs/TriangleDihedralAngleFilter.md index ea6e6ac6a9..5922f99334 100644 --- a/src/Plugins/SimplnxCore/docs/TriangleDihedralAngleFilter.md +++ b/src/Plugins/SimplnxCore/docs/TriangleDihedralAngleFilter.md @@ -6,7 +6,24 @@ Surface Meshing (Misc) ## Description -This **Filter** computes the minimum dihedral angle of each **Triangle** in a **Triangle Geometry** by utilizing matrix mathematics +This filter computes, for every **Triangle** in a **Triangle Geometry**, the smallest of its three interior corner angles, and stores that value as a per-triangle **Face Data** array. + +### What This Measures and Why + +Each triangle has three interior angles. This filter records the **minimum** of those three angles. (For a single flat triangle this minimum interior angle is what is referred to here as the "dihedral angle".) It is a standard **mesh-quality** metric: + +- A well-shaped, near-equilateral triangle has a minimum angle close to 60°. +- A long, thin "sliver" triangle has a very small minimum angle (close to 0°). Slivers are numerically poorly conditioned and degrade downstream calculations (curvature, smoothing, finite-element meshing). + +Coloring a surface mesh by this value is a quick way to locate sliver triangles that may need remeshing or smoothing. + +### Units + +The output angle is reported in **degrees** (0° to 60°; a value of 60° corresponds to a perfectly equilateral triangle). + +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Surface Nets](SurfaceNetsFilter.md) or [Quick Surface Mesh](QuickSurfaceMeshFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/TriangleNormalFilter.md b/src/Plugins/SimplnxCore/docs/TriangleNormalFilter.md index c2a4f5ac9c..d722e1478d 100644 --- a/src/Plugins/SimplnxCore/docs/TriangleNormalFilter.md +++ b/src/Plugins/SimplnxCore/docs/TriangleNormalFilter.md @@ -6,14 +6,30 @@ Surface Meshing (Misc) ## Description -This **Filter** computes the normal of each **Triangle** in a **Triangle Geometry** by utilizing matrix subtraction, cross product, and normalization to implement the following theory: - For a triangle with point1, point2, point3, if the vector U = point2 - point1 and the vector V = point3 - point1 +This filter computes the **normal** of each **Triangle** in a **Triangle Geometry** (a surface mesh built from triangles) and stores the result as a per-triangle **Face Data** array. A normal is the direction that points straight out of the flat triangle surface. - Nx = UyVz - UzVy - Ny = UzVx - UxVz - Nz = UxVy - UyVx +### How It Is Computed - Where "point#" represents a 3x1 Matrix of coordinates x, y, and z belonging to one of a Triangles vertexes and N represents the normal of the corresponding axis value +For a triangle with corner **vertices** *point1*, *point2*, and *point3*, the filter forms two edge vectors + + U = point2 - point1 + V = point3 - point1 + +and computes their **cross product** (a vector perpendicular to both edges, and therefore perpendicular to the triangle): + + Nx = Uy*Vz - Uz*Vy + Ny = Uz*Vx - Ux*Vz + Nz = Ux*Vy - Uy*Vx + +The result is then normalized to unit length. + +### Output and Direction + +The output is a 3-component **unit vector** (length 1) and is therefore **dimensionless**. Its sense (which of the two opposite directions it points along) is set by the **winding order** -- the order in which the triangle's three vertices are listed. Reversing the vertex order flips the normal to point the opposite way. Consistent winding across the mesh is what makes all normals point consistently inward or outward. + +### Required Input Sources + +- **Triangle Geometry** -- a surface mesh, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/UncertainRegularGridSampleSurfaceMeshFilter.md b/src/Plugins/SimplnxCore/docs/UncertainRegularGridSampleSurfaceMeshFilter.md index ddaf37c656..38091602b9 100644 --- a/src/Plugins/SimplnxCore/docs/UncertainRegularGridSampleSurfaceMeshFilter.md +++ b/src/Plugins/SimplnxCore/docs/UncertainRegularGridSampleSurfaceMeshFilter.md @@ -6,15 +6,24 @@ Sampling (Resolution) ## Description -This **Filter** "samples" a triangulated surface mesh on a rectilinear grid, but with "uncertainty" in the absolute position of the **Cells**. The "uncertainty" is meant to simulate the possible positioning error in a sampling probe. The user can specify the number of **Cells** along the X, Y, and Z directions in addition to the resolution in each direction and origin to define a rectilinear grid. The sampling, with "uncertainty", is then performed by the following steps: +This **Filter** "samples" a triangulated surface mesh onto a **rectilinear grid** (a regular grid of box-shaped **Cells**), but with "uncertainty" in the absolute position of each Cell. The uncertainty simulates the possible positioning error of a sampling probe. A **Cell** is a single volume element of the output grid, and a **Feature** is one labeled region of the surface mesh. -1. Determine the bounding box and **Triangle** list of each **Feature** by scanning all **Triangles** and noting the **Features** on either side of the **Triangle** -2. For each **Cell** in the rectilinear grid, perturb the location of the **Cell** by generating a three random numbers between [-1, 1] and multiplying them by the three uncertainty values (one for each direction) -3. For each perturbed **Cell** in the rectilinear grid, determine which bounding box(es) they fall in (*Note:* the bounding box of multiple **Features** can overlap) -4. For each bounding box a **Cell** falls in, check against that **Feature's** **Triangle** list to determine if the **Cell** falls within that n-sided polyhedra. (*Note:* if the surface mesh is conformal, then each **Cell** will only belong to one **Feature**, but if not, the last **Feature** the **Cell** is found to fall inside of will *own* the **Cell**) -5. Assign the **Feature** number that the **Cell** falls within to the *Feature Ids* array in the new rectilinear grid geometry +The user specifies the number of **Cells** along the X, Y, and Z directions, plus the resolution (spacing) and origin that define the grid. The grid resolution and origin are given in the same physical length units as the input surface mesh (typically microns). The three uncertainty values are also physical lengths in those same units. The sampling, with uncertainty, is performed by the following steps: -**Note that the unperturbed grid is where the *Feature Ids* actually live, but the perturbed locations are where the Cells are sampled from. Essentially, the *Feature Ids* are stored where the user *thinks* the sampling took place, not where it actually took place!** +1. Determine the bounding box and **Triangle** list of each **Feature** by scanning all **Triangles** and noting the **Features** on either side of each **Triangle**. +2. For each **Cell** in the rectilinear grid, perturb its location by generating three random numbers in the range [-1, 1] and multiplying them by the three uncertainty values (one for each direction). +3. For each perturbed **Cell**, determine which bounding box(es) it falls in (*Note:* the bounding boxes of multiple **Features** can overlap). +4. For each bounding box a **Cell** falls in, test it against that **Feature's** **Triangle** list to determine whether the **Cell** lies within that n-sided polyhedron. (*Note:* if the surface mesh is **conformal** -- meaning adjacent features share exactly one common surface with no gaps or overlaps -- each **Cell** belongs to only one **Feature**; if not, the last **Feature** the **Cell** is found inside of *owns* the **Cell**.) +5. Assign the **Feature** number that the **Cell** falls within to the *Feature Ids* array in the new rectilinear grid geometry. + +**Note that the unperturbed grid is where the *Feature Ids* actually live, but the perturbed locations are where the Cells are sampled from. Essentially, the *Feature Ids* are stored where the user *thinks* the sampling took place, not where it actually took place.** + +For the variant that samples onto a regular grid without positional uncertainty, see the sibling filter [Sample Triangle Geometry on Regular Grid](RegularGridSampleSurfaceMeshFilter.md), which shares the same grid (dimensions, origin, spacing) parameters. + +### Required Input Sources + +- **Triangle Geometry** -- the surface mesh to sample, typically produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** -- the per-face 2-component array identifying the **Features** on either side of each triangle, produced by the same surface-meshing filter. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/VerifyTriangleWindingFilter.md b/src/Plugins/SimplnxCore/docs/VerifyTriangleWindingFilter.md index d0a5c95f23..b19ee9fb86 100644 --- a/src/Plugins/SimplnxCore/docs/VerifyTriangleWindingFilter.md +++ b/src/Plugins/SimplnxCore/docs/VerifyTriangleWindingFilter.md @@ -2,35 +2,35 @@ ## Group (Subgroup) -Meshing (Cleanup) +Surface Meshing (Connectivity/Arrangement) ## Description -***WARNING***: *If your mesh contains multiple disconnected objects in it, you should run **Label Triangle Geometry** beforehand, and convert the output (region ids) into face labels. Recommended procedure for such is described below in **Multi-Object Meshes**.* +***WARNING***: *If your mesh contains multiple disconnected objects, you should run [Label CAD Geometry](LabelTriangleGeometryFilter.md) beforehand and convert the output (region ids) into face labels. The recommended procedure is described below in **Multi-Object Meshes**.* -This filter attempts to repair the windings for a mesh. This may not be possible due to the nature of how meshes are stored in the software. +This filter attempts to repair the **winding** of a mesh so that it is consistent across the surface. The *winding* is the order in which a triangle's three vertices are listed; that order determines which way the triangle's normal points (the triangle's "front" versus "back" face). Consistent winding means every triangle of a closed surface has its normal pointing the same way relative to the enclosed volume. Achieving fully consistent winding may not be possible because of how meshes are stored in the software. ### Key Nuances -While this filter doesn't modify anything more than the *Shared Faces List*, it has wider downstream implications for the mesh so it is recommended that it is executed as close to the start of the pipeline as possible. This ensures you don't have to recalculate extensive amounts of face data. This is especially pertinent in **Multi-Object Meshes**, where there are prerequisites to be satisfied as well. +While this filter modifies nothing more than the *Shared Faces List*, it has wider downstream implications for the mesh, so it is recommended to run it as close to the start of the pipeline as possible. This avoids recalculating extensive amounts of face data later. This is especially important for **Multi-Object Meshes**, which have additional prerequisites. -The meshes treat both sides of each triangle as valid, the upside to this is that the amount of space needed to store meshes is reduced, but it means that giving every feature the proper winding is impossible. The order of execution is based on feature label numbering, so randomizing order may lead to more visual distinction. +The meshes treat both sides of each triangle as valid. The upside is that less space is needed to store meshes, but it means giving every feature the proper winding is impossible. The order of execution is based on feature label numbering, so randomizing that order may lead to more visual distinction. -This filter requires that vertices are unique, well formed meshes should not have an issue with this. The filter will check this at runtime, returning an error if duplicates are found. If this happens, run *Identify Duplicate Vertices* followed by *Remove flagged Vertices* prior to this. +This filter requires that vertices are unique; well-formed meshes should not have an issue with this. The filter checks this at runtime and returns an error if duplicates are found. If this happens, run [Identify Duplicate Vertices](IdentifyDuplicateVerticesFilter.md) followed by [Remove Flagged Vertices](RemoveFlaggedVerticesFilter.md) prior to this filter. -This filter offers recalculating triangle normals as an option, however it is just a convience option. It simply calls Calculate Triangle Normals at the end. +This filter offers recalculating triangle normals as an option; this is a convenience that simply calls [Compute Triangle Normals](TriangleNormalFilter.md) at the end. -Both *Surface Nets* and *Quick Mesh* (the only synthetic mesh generating currently) already utilize this algorithm at the end of their execution. Thus this filter will be redundant to run on meshes generated from the software's integrated algorithms. +Both [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) and [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) (the only synthetic mesh generators currently available) already apply this algorithm at the end of their execution. This filter is therefore redundant when run on meshes generated by the software's integrated algorithms. -This filter detemines candidates for winding reversal feature by feature based on the volume of the feature. This means its possible you may input a mesh that contains a feature with negative volume (that is untounched during winding repair) that gets all of it's windings reversed as a result. However, to our knowledge there does not exist a case where the feature would not be "inside-out" prior to execution. Essentially, this filter will addtionally preform winding reversal for you if it contains invalid features. +This filter determines candidates for winding reversal feature by feature, based on the **volume** of each feature. A feature whose triangle windings are "inside-out" computes a **negative volume** (the signed volume comes out negative because the surface normals point inward instead of outward). It is possible to input a mesh containing a feature with negative volume that is left untouched during winding repair but then gets all of its windings reversed as a result. To our knowledge there is no case where such a feature would not already be "inside-out" prior to execution. Essentially, this filter will additionally perform winding reversal for you when the mesh contains invalid (inside-out) features. ### Multi-Object Meshes -If your mesh has more than one disconnected object in it, *Label Traingle Geometry* should be run beforehand. This can be confusing because the output of the filter is not a face labels array. To convert the output to face labels, you need to merge this array with another array of zeros (created with *Create Data Array*) using *Combine Attribute Arrays*. The order is not strictly enforced but the internal paradigm is to place the zeros array above the *region ids* array (Option A below). The difference n output is as follows: +If your mesh has more than one disconnected object, run [Label CAD Geometry](LabelTriangleGeometryFilter.md) beforehand. This can be confusing because the output of that filter is a region ids array, not a face labels array. To convert the output to face labels, merge that array with an array of zeros (created with [Create Data Array](CreateDataArrayFilter.md)) using [Combine Attribute Arrays](CombineAttributeArraysFilter.md). The order is not strictly enforced, but the internal convention is to place the zeros array above the *region ids* array (Option A below). The difference in output is as follows: **Option A**: -- Zero's array first +- Zeros array first - Region Ids array second ```console @@ -42,23 +42,28 @@ OR **Option B**: - Region Ids array first -- Zero's array second +- Zeros array second ```console {{1,0}, {1,0}, {1,0}, ...} ``` -The output of this combination will become your face labels for the mesh. +The output of this combination becomes the face labels for the mesh. -The relative pipeline for multiobject meshes should look something like this: +The pipeline for multi-object meshes should look something like this: -1. Identify Duplicate Vertices (optional) -2. Remove Flagged Vertices (optional) -3. Label CAD Geometry (LabelTriangleGeometry) -4. Create Data Array (fill with 0's) -5. Combine Attribute Arrays (make face labels [Zero Array + Region Ids]) +1. [Identify Duplicate Vertices](IdentifyDuplicateVerticesFilter.md) (optional) +2. [Remove Flagged Vertices](RemoveFlaggedVerticesFilter.md) (optional) +3. [Label CAD Geometry](LabelTriangleGeometryFilter.md) +4. [Create Data Array](CreateDataArrayFilter.md) (fill with 0's) +5. [Combine Attribute Arrays](CombineAttributeArraysFilter.md) (make face labels [Zeros Array + Region Ids]) 6. Verify Triangle Winding +### Required Input Sources + +- **Triangle Geometry** -- the surface mesh whose winding will be verified and repaired. +- **Face Labels (or Region Ids)** -- the per-face array identifying the **Features** on either side of each triangle, produced by a surface-meshing filter such as [Create Surface Mesh (Surface Nets)](SurfaceNetsFilter.md) or [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md), or assembled from region ids via [Label CAD Geometry](LabelTriangleGeometryFilter.md) as described above. + % Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/WriteASCIIDataFilter.md b/src/Plugins/SimplnxCore/docs/WriteASCIIDataFilter.md index f8a0aa968a..5a8fdcf1b0 100644 --- a/src/Plugins/SimplnxCore/docs/WriteASCIIDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteASCIIDataFilter.md @@ -2,15 +2,19 @@ ## Group (Subgroup) -IO (Output) (Write) (Export) (Text) (CSV) (ASCII) +IO (Output) ## Description -This filter will write the selected DataArrays to either individual files or as a single CSV style of file. +This filter will write the selected **Data Array**s to either individual files or as a single CSV style of file. The inputs are any existing **Data Array**s (numeric or string) that the user selects to export. + +### Maximum Tuples Per Line + +When writing to multiple files, the *Maximum Tuples Per Line* parameter controls how many tuples are printed on each row of an output file (units: tuples per row). For example, with a value of *1* each tuple is written on its own line; with a value of *10* up to ten tuples are written per line before a new line begins. This makes it possible to reshape long single-column output into a more compact block. The parameter does not apply to string arrays. ## String Data Array Caveats -- The "Maximum Tuples per Line" will not have any effect for that specific array. +- The "Maximum Tuples Per Line" will not have any effect for that specific array. - If the output is for a single file, then each String value will be enclosed in a set of Single Quotes (') characters. ### Multiple Files diff --git a/src/Plugins/SimplnxCore/docs/WriteAbaqusHexahedronFilter.md b/src/Plugins/SimplnxCore/docs/WriteAbaqusHexahedronFilter.md index 0ce78f3152..a8c8c93dbf 100644 --- a/src/Plugins/SimplnxCore/docs/WriteAbaqusHexahedronFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteAbaqusHexahedronFilter.md @@ -6,117 +6,100 @@ IO (Output) ## Description -***WARNING**: If you are not using this filter for stress - strain curves, be sure to disable `Write Dummy Node` or it may mess up mesh connectivity.* +This filter converts a voxel grid (an **Image Geometry**) into a hexahedral element mesh and writes it to a set of Abaqus input (`.inp`) files. **Abaqus** is a commercial *finite-element-analysis* (FEA) software package; FEA is a numerical technique that divides a body into many small, simple elements and solves for quantities such as stress and strain across them. By exporting the microstructure as an Abaqus mesh, the filter lets users run mechanical (stress/strain) simulations on a digital microstructure. -This **Filter** produces the basic five Abaqus .inp files for input into the Abaqus analysis tool. The files created are: xxx.inp (the master file), xxx_nodes.inp, xxx_elems.inp, xxx_elset.inp and xxx_sects.inp. This **Filter** is based on a Python script developed by Matthew W. Priddy (Ga. Tech., early 2015). +Each **Cell** (voxel) in the **Image Geometry** becomes one hexahedral (brick-shaped) element with 8 corner nodes. Nodes shared between neighboring voxels are written only once so the mesh is fully connected. The element type written is `C3D8`, Abaqus's standard 8-node linear brick element. Every element is assigned to an element set named after the **Feature** (grain) it belongs to, using the *Cell Feature Ids* array, so each grain can be given its own material in the simulation. + +![Fig. 1: Each voxel is exported as an 8-node C3D8 hexahedral element (nodes shared between neighbors written once), across five Abaqus .inp files.](Images/WriteAbaqusHexahedron_VoxelToHex.png) + +### Output Files + +The filter writes five plain-text files. The first is a master file that pulls in the other four using Abaqus's `*Include` directive, so the simulation is launched from the master file alone: + +- `.inp` — the master file. It `*Include`s the four files below. +- `_nodes.inp` — the node coordinates. +- `_elems.inp` — the element connectivity (which 8 nodes make up each element). +- `_elset.inp` — the element sets (one set per grain). +- `_sects.inp` — the section definitions assigning a material to each grain set. + +Node coordinates are written in the physical units of the **Image Geometry** (for example microns, if the geometry's spacing is in microns). Each node coordinate is the voxel-grid position scaled by the geometry spacing and offset by its origin. + +### Write Dummy Node + +When the *Write Dummy Node* parameter is enabled, the filter appends one extra "dummy" node at the end of the `_nodes.inp` file. This node is not attached to any element; it exists only as a reference point that some Abaqus stress/strain workflows require (for example, to apply or read periodic boundary conditions). If the export is not being used for stress/strain curves, this parameter should be disabled, because the unused node can interfere with mesh connectivity tools that expect every node to belong to an element. + +### Hourglass Stiffness + +The `_sects.inp` file includes an `*Hourglass Stiffness` value for each grain section. "Hourglass" modes are spurious, zero-energy deformation patterns that reduced-integration brick elements can exhibit; a small artificial stiffness suppresses them. The *Hourglass Stiffness Value* parameter sets this number (default *250*, a dimensionless solver-control value). + +### Required Input Sources + +- **Image Geometry** -- the voxel grid to export. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). One element set is written per Feature Id. ### Example Output +The headers in the snippets below read `DREAM3DLib Version 5.1.566`; these version strings are illustrative and will reflect the actual version that wrote the file. The filter is based on a Python script developed by Matthew W. Priddy (Georgia Tech, early 2015). + The master file: ```text - *Heading - Job 101 - ** Job name : Job 101 - ** Generated by : DREAM3DLib Version 5.1.566.e1e7b7f - *Preprint, echo = NO, model = NO, history = NO, contact = NO - ** - ** ----------------------------Geometry---------------------------- - ** - *Include, Input = 32x32x32_nodes.inp - *Include, Input = 32x32x32_elems.inp - *Include, Input = 32x32x32_elset.inp - *Include, Input = 32x32x32_sects.inp - ** - ** ---------------------------------------------------------------- - ** +*Heading +Job 101 +** Job name : Job 101 +** Generated by : DREAM3DLib Version 5.1.566 +*Preprint, echo = NO, model = NO, history = NO, contact = NO +** +** ----------------------------Geometry---------------------------- +** +*Include, Input = 32x32x32_nodes.inp +*Include, Input = 32x32x32_elems.inp +*Include, Input = 32x32x32_elset.inp +*Include, Input = 32x32x32_sects.inp ``` -The _nodes.inp file: +The `_nodes.inp` file (node ID followed by x, y, z in geometry units): ```text - ** Generated by : DREAM3DLib Version 5.1.566.e1e7b7f - ** ---------------------------------------------------------------- - ** - *Node - 1, 0.000000, 0.000000, 0.000000 - 2, 0.500000, 0.000000, 0.000000 - 3, 1.000000, 0.000000, 0.000000 - 4, 1.500000, 0.000000, 0.000000 - .. +*Node +1, 0.000000, 0.000000, 0.000000 +2, 0.500000, 0.000000, 0.000000 +3, 1.000000, 0.000000, 0.000000 + .. ``` -The _elset.inp file: +The `_elems.inp` file (element ID followed by its 8 node IDs): ```text - ** Generated by : DREAM3DLib Version 5.1.566.e1e7b7f - ** ---------------------------------------------------------------- - ** - ** The element sets - *Elset, elset=cube, generate - 1, 32768, 1 - ** - ** Each Grain is made up of multiple elements - ** - *Elset, elset=Grain1_set - 24126, 24127, 24128, 24159, 24160, 24191, 24192, 25085, 25086, 25087, 25117, 25118, 25119, 25120, 25149, 25150, - 25151, 25152, 25181, 25182, 25183, 25184, 25214, 25215, 25216, 25247, 25248, 26077, 26078, 26079, 26080, 26108, - 26109, 26110, 26111, 26112, 26140, 26141, 26142, 26143, 26144, 26172, 26173, 26174, 26175, 26176, 26204, 26205, - 26206, 26207, 26208, 26237, 26238, 26239, 26240, 26270, 26271, 26272, 26303, 26304, 27069, 27070, 27071, 27072, - 27100, 27101, 27102, 27103, 27104, 27131, 27132, 27133, 27134, 27135, 27136, 27163, 27164, 27165, 27166, 27167, - 27168, 27195, 27196, 27197, 27198, 27199, 27200, 27228, 27229, 27230, 27231, 27232, 27260, 27261, 27262, 27263, - 27264, 27294, 27295, 27296, 27326, 27327, 27328, 27359, 27360, 28093, 28094, 28095, 28096, 28123, 28124, 28125, - 28126, 28127, 28128, 28155, 28156, 28157, 28158, 28159, 28160, 28187, 28188, 28189, 28190, 28191, 28192, 28219, - 28220, 28221, 28222, 28223, 28224, 28252, 28253, 28254, 28255, 28256, 28284, 28285, 28286, 28287, 28288, 28317, - 28318, 28319, 28320, 28350, 28351, 28352, 28383, 28384, 28416, 29116, 29117, 29118, 29119, 29120, 29147, 29148, - 29149, 29150, 29151, 29152, 29179, 29180, 29181, 29182, 29183, 29184, 29211, 29212, 29213, 29214, 29215, 29216, - 29243, 29244, 29245, 29246, 29247, 29248, 29276, 29277, 29278, 29279, 29280, 29308, 29309, 29310, 29311, 29312, - 29341, 29342, 29343, 29344, 29374, 29375, 29376, 29407, 29408, 29440, 30140, 30141, 30142, 30143, 30144, 30171, - 30172, 30173, 30174, 30175, 30176, 30203, 30204, 30205, 30206, 30207, 30208, 30235, 30236, 30237, 30238, 30239, - 30240, 30267, 30268, 30269, 30270, 30271, 30272, 30300, 30301, 30302, 30303, 30304, 30332, 30333, 30334, 30335, - 30336, 30365, 30366, 30367, 30368, 30398, 30399, 30400, 30431, 30432, 31164, 31165, 31166, 31167, 31168, 31195, - 31196, 31197, 31198, 31199, 31200, 31227, 31228, 31229, 31230, 31231, 31232, 31259, 31260, 31261, 31262, 31263, - 31264, 31292, 31293, 31294, 31295, 31296, 31324, 31325, 31326, 31327, 31328, 31357, 31358, 31359, 31360, 31389, - 31390, 31391, 31392, 31422, 31423, 31424, 31455, 31456, 32188, 32189, 32190, 32191, 32192, 32220, 32221, 32222, - 32223, 32224, 32251, 32252, 32253, 32254, 32255, 32256, 32284, 32285, 32286, 32287, 32288, 32316, 32317, 32318, - 32319, 32320, 32348, 32349, 32350, 32351, 32352, 32381, 32382, 32383, 32384, 32413, 32414, 32415, 32416, 32447, - 32448 - *Elset, elset=Grain2_set - .. +*Element, type=C3D8 +1, 1091, 2, 1, 1090, 1124, 35, 34, 1123 +2, 1092, 3, 2, 1091, 1125, 36, 35, 1124 + .. ``` -The _elems.inp file: +The `_elset.inp` file (a "cube" set spanning all elements, then one set per grain — the full grain sets contain many element IDs and are abbreviated here): ```text - ** Generated by : DREAM3DLib Version 5.1.566.e1e7b7f - ** ---------------------------------------------------------------- - ** - *Element, type=C3D8 - 1, 1091, 2, 1, 1090, 1124, 35, 34, 1123 - 2, 1092, 3, 2, 1091, 1125, 36, 35, 1124 - 3, 1093, 4, 3, 1092, 1126, 37, 36, 1125 - 4, 1094, 5, 4, 1093, 1127, 38, 37, 1126 - 5, 1095, 6, 5, 1094, 1128, 39, 38, 1127 - 6, 1096, 7, 6, 1095, 1129, 40, 39, 1128 - .. +** The element sets +*Elset, elset=cube, generate +1, 32768, 1 +** +*Elset, elset=Grain1_set +24126, 24127, 24128, 24159, 24160, 24191, 24192, 25085, 25086, .. +*Elset, elset=Grain2_set + .. ``` -The _sects.inp file: +The `_sects.inp` file (one section per grain, each with its hourglass stiffness): ```text - ** Generated by : DREAM3DLib Version 5.1.566.e1e7b7f - ** ---------------------------------------------------------------- - ** - ** Each section is a separate grain - ** Section: Grain1 - *Solid Section, elset=Grain1_set, material=Grain_Mat1 - *Hourglass Stiffness - 250 - ** -------------------------------------- - ** Section: Grain2 - *Solid Section, elset=Grain2_set, material=Grain_Mat2 - - .. +** Section: Grain1 +*Solid Section, elset=Grain1_set, material=Grain_Mat1 +*Hourglass Stiffness +250 +** Section: Grain2 +*Solid Section, elset=Grain2_set, material=Grain_Mat2 + .. ``` % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/WriteAvizoRectilinearCoordinateFilter.md b/src/Plugins/SimplnxCore/docs/WriteAvizoRectilinearCoordinateFilter.md index 1280f50da4..8590261f7b 100644 --- a/src/Plugins/SimplnxCore/docs/WriteAvizoRectilinearCoordinateFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteAvizoRectilinearCoordinateFilter.md @@ -6,9 +6,17 @@ IO (Output) ## Description -This filter writes out a native Avizo Rectilinear Coordinate data file. Values should be present from segmentation of experimental data or synthetic generation and cannot be determined by this filter. Not having these values will result in the filter to fail/not execute. +This filter writes an **Image Geometry** and its **Cell** *FeatureIds* array to a file that can be read by **Avizo**. Avizo is a commercial 3D visualization and analysis package. Its native data format is **AmiraMesh**, a header-plus-data file (commonly given an `.am` extension). -### Example Output +The filter requires two inputs: an **Image Geometry**, and an Int32 *FeatureIds* **Cell** **Data Array** that labels which **Feature** (for example, which grain) each cell belongs to. The *FeatureIds* values are produced earlier in the pipeline by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md); this filter does not compute them. If no valid *FeatureIds* array is supplied, the filter will not execute. + +The data is written in the **rectilinear-coordinate** form: the file stores explicit per-axis coordinate arrays (the X, Y, and Z positions of the grid lines). This is the counterpart to the [Write Avizo Uniform Coordinate](WriteAvizoUniformCoordinateFilter.md) filter, which instead records a single uniform spacing and bounding box. Use the rectilinear variant when the per-axis coordinate values must be written out explicitly. + +The *Write Binary File* parameter selects the on-disk encoding: *false* (the default) writes the data section as ASCII text, while *true* writes it in little-endian binary, producing smaller files. + +**Units caveat:** the AmiraMesh header always records the coordinate units as `microns`, regardless of the actual units stored on the input **Image Geometry**. If the geometry uses different units, adjust them in Avizo after import. + +### Example AmiraMesh Header # AmiraMesh BINARY-LITTLE-ENDIAN 2.1 # Dimensions in x-, y-, and z-direction @@ -17,18 +25,21 @@ This filter writes out a native Avizo Rectilinear Coordinate data file. Values s Parameters { DREAM3DParams { Author "DREAM3D", - DateTime " . M o n J u n 1 1 0 : 0 1 : 1 4 2 0 1 5 " + DateTime "Mon Jun 1 10:01:14 2015" } Units { - Coordinates "microns" + Coordinates "microns" } - CoordType "rectilinear" + CoordType "rectilinear" } - Lattice { int FeatureIds } = @1 Coordinates { float xyz } = @2 # Data section follows - .. + +### Required Input Sources + +- **Image Geometry** -- the geometry whose dimensions and coordinates are written. +- **Cell Feature Ids** -- an Int32 per-cell label array, produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/WriteAvizoUniformCoordinateFilter.md b/src/Plugins/SimplnxCore/docs/WriteAvizoUniformCoordinateFilter.md index 42d9da60a1..1301d5a552 100644 --- a/src/Plugins/SimplnxCore/docs/WriteAvizoUniformCoordinateFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteAvizoUniformCoordinateFilter.md @@ -6,9 +6,17 @@ IO (Output) ## Description -This filter writes out a native Avizo Uniform Coordinate data file. Values should be present from segmentation of experimental data or synthetic generation and cannot be determined by this filter. Not having these values will result in the filter to fail/not execute. +This filter writes an **Image Geometry** and its **Cell** *FeatureIds* array to a file that can be read by **Avizo**. Avizo is a commercial 3D visualization and analysis package. Its native data format is **AmiraMesh**, a header-plus-data file (commonly given an `.am` extension). -### Example Output +The filter requires two inputs: an **Image Geometry**, and an Int32 *FeatureIds* **Cell** **Data Array** that labels which **Feature** (for example, which grain) each cell belongs to. The *FeatureIds* values are produced earlier in the pipeline by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md); this filter does not compute them. If no valid *FeatureIds* array is supplied, the filter will not execute. + +The data is written in the **uniform-coordinate** form: the file records a single uniform spacing together with the grid's bounding box (minimum and maximum X, Y, and Z), rather than listing per-axis coordinate values. This is the compact counterpart to the [Write Avizo Rectilinear Coordinate](WriteAvizoRectilinearCoordinateFilter.md) filter, which writes explicit per-axis coordinate arrays. Use the uniform variant when the grid has uniform spacing (the usual case for an **Image Geometry**). + +The *Write Binary File* parameter selects the on-disk encoding: *false* (the default) writes the data section as ASCII text, while *true* writes it in little-endian binary, producing smaller files. + +**Units caveat:** the AmiraMesh header always records the coordinate units as `microns`, regardless of the actual units stored on the input **Image Geometry**. If the geometry uses different units, adjust them in Avizo after import. + +### Example AmiraMesh Header # AmiraMesh BINARY-LITTLE-ENDIAN 2.1 # Dimensions in x-, y-, and z-direction @@ -17,19 +25,23 @@ This filter writes out a native Avizo Uniform Coordinate data file. Values shoul Parameters { DREAM3DParams { Author "DREAM3D", - DateTime + DateTime "Mon Jun 1 10:01:14 2015" } Units { - Coordinates "microns" + Coordinates "microns" } - Content " int, uniform coordinates", - # Bounding Box is xmin xmax ymin ymax zmin zmax - BoundingBox , - CoordType "uniform" + Content "int, uniform coordinates", + # Bounding Box is xmin xmax ymin ymax zmin zmax + BoundingBox 0 64 0 64 0 64, + CoordType "uniform" } Lattice { int FeatureIds } = @1 # Data section follows - .. + +### Required Input Sources + +- **Image Geometry** -- the geometry whose dimensions and bounding box are written. +- **Cell Feature Ids** -- an Int32 per-cell label array, produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/WriteBinaryDataFilter.md b/src/Plugins/SimplnxCore/docs/WriteBinaryDataFilter.md index d422016ea4..574404f110 100644 --- a/src/Plugins/SimplnxCore/docs/WriteBinaryDataFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteBinaryDataFilter.md @@ -6,17 +6,37 @@ IO (Output) (Write) (Export) (Binary) ## Description -This **Filter** accepts DataArray(s) as input, extracts the data, and writes each array to a separate binary file in the specified output directory +This filter writes each selected **Data Array** to its own raw binary file in the chosen output directory. One file is written per selected array. + +### How It Works + +For each array, the filter writes the array's numeric values straight to disk as raw bytes. **No header is written** — the file contains only the array values with no metadata describing the data type, dimensions, byte order, or component layout. Because of this, the user must independently record the data type (for example *float32*, *int32*, *uint8*), the tuple and component dimensions, and the endianness chosen below. That information is required later to read the file back correctly. + +The values are written in the same order they are stored in memory: tuple by tuple, with the components of each tuple written together (interleaved). For example, a 3-component array is written as `t0c0, t0c1, t0c2, t1c0, t1c1, t1c2, ...`. + +### File Naming + +Each output file is named after the array it contains, followed by the value of the *File Extension* parameter, and is placed in the *Output Path* directory. For example, an array named `Confidence Index` written with the default extension `.bin` produces a file named `Confidence Index.bin` in the output directory. + +### Reading the Files Back + +These raw binary files can be read back into DREAM3D-NX with the [Read Raw Binary](ReadRawBinaryFilter.md) filter. Because no header was written, the user must supply the data type, dimensions, and endianness to that filter manually — they must match the values used when the file was written. ### Endianess The *Endianess* parameter controls the byte order used when writing numeric values to the binary file: -- **Little Endian [0]**: The least significant byte is stored first. This is the native byte order for x86 and ARM processors and is the most common choice for files consumed on modern desktop systems. -- **Big Endian [1]**: The most significant byte is stored first. This byte order is used by some network protocols and legacy systems. +- *Little Endian*: The least significant byte is stored first. This is the native byte order for x86 and ARM processors and is the most common choice for files consumed on modern desktop systems. +- *Big Endian*: The most significant byte is stored first. This byte order is used by some network protocols and legacy systems. + +## Required Input Sources + +The arrays to export are user-selected **Data Arrays** from anywhere in the **Data Structure**; there is no specific upstream producer filter required. % Auto generated parameter table will be inserted here +## Example Pipelines + ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/SimplnxCore/docs/WriteDREAM3DFilter.md b/src/Plugins/SimplnxCore/docs/WriteDREAM3DFilter.md index 24e258f4d9..7ce5d70186 100644 --- a/src/Plugins/SimplnxCore/docs/WriteDREAM3DFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteDREAM3DFilter.md @@ -1,5 +1,9 @@ # Write DREAM3D-NX File +## Group (Subgroup) + +IO (Output) + ## Description This **Filter** writes the current `DataStructure` to disk as an HDF5 file with the `.dream3d` extension. The file contains every `DataArray`, geometry, attribute matrix, and group in the pipeline, along with the pipeline itself so the work can be re-run or inspected later. @@ -34,6 +38,10 @@ The `.xdmf` file does not contain a copy of the data — it is a metadata wrappe Enabling XDMF costs almost nothing (the file is small and fast to write) and is the recommended setting whenever visualization outside DREAM3D-NX is a possibility. It can safely be left off for intermediate pipeline outputs that will only be re-read by DREAM3D-NX itself. +### Required Input Sources + +None — this filter writes whatever currently exists in the **DataStructure** to the output file. If the file already exists it is overwritten. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/WriteFeatureDataCSVFilter.md b/src/Plugins/SimplnxCore/docs/WriteFeatureDataCSVFilter.md index a1ff8e7b8d..39c80d7ce1 100644 --- a/src/Plugins/SimplnxCore/docs/WriteFeatureDataCSVFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteFeatureDataCSVFilter.md @@ -6,10 +6,12 @@ IO (Output) ## Description -This **Filter** writes the data associated with each **Feature** to a file name specified by the user in *CSV* format. Every array in the **Feature** map is written as a column of data in the *CSV* file. The user can choose to also write the neighbor data. Neighbor data are data arrays that are associated with the neighbors of a **Feature**, such as: list of neighbors, list of misorientations, list of shared surface areas, etc. These blocks of info are written after the scalar data arrays. Since the number of neighbors is variable for each **Feature**, the data is written as follows (for each **Feature**): Id, number of neighbors, value1, value2,...valueN. +A **Feature** is a grouped region of the data, such as a grain. This **Filter** writes the data associated with each **Feature** to a file name specified by the user in *CSV* format. Every array in the **Feature** map is written as a column of data in the *CSV* file. The user can choose to also write the neighbor data. Neighbor data are data arrays that are associated with the neighbors of a **Feature**, such as: list of neighbors, list of misorientations, list of shared surface areas, etc. These blocks of info are written after the scalar data arrays. Since the number of neighbors is variable for each **Feature**, the data is written as follows (for each **Feature**): Id, number of neighbors, value1, value2,...valueN. ### Example Output +In the examples below, the very first line of the output (here `5414`) is the total **Feature** count — the number of Features whose data follows. + The *CSV* file: 5414 @@ -49,6 +51,14 @@ The *Delimiter* parameter selects the character used to separate values within e - **Colon [3]**: Values are separated by a colon (`:`). - **Tab [4]**: Values are separated by a tab character. +## Required Input Sources + +The per-feature columns come from any feature-level **Data Array**s present in the selected Feature **Attribute Matrix** (for example feature phases, sizes, or average orientations). When *Write Neighbor Data* is enabled, the additional neighbor blocks require: + +- **Number of Neighbors** and the contiguous **Neighbor List** -- produced by [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md). +- **Shared Surface Area List** -- produced by [Compute Feature Neighbors](ComputeFeatureNeighborsFilter.md). +- **Neighbor Misorientation List** -- produced by [Compute Feature Neighbor Misorientations](../OrientationAnalysis/ComputeFeatureNeighborMisorientationsFilter.md). + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/WriteImageFilter.md b/src/Plugins/SimplnxCore/docs/WriteImageFilter.md index c47a160161..8a2c898fee 100644 --- a/src/Plugins/SimplnxCore/docs/WriteImageFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteImageFilter.md @@ -91,6 +91,10 @@ the padded size. - **Interaction with *Flip Output Image***: the flip applies to the image data only; the band and its bar remain upright at the bottom of the written file. +### Required Input Sources + +- **Image Data** -- a `uint8` (or `uint16`/`float32` for TIFF) **Cell Data** array on an **Image Geometry**, produced by an image reader such as [Read Image](ReadImageFilter.md) / [Read Images [3D Stack]](ReadImageStackFilter.md), or by any upstream image-processing filter. + % Auto generated parameter table will be inserted here ## Example Pipelines diff --git a/src/Plugins/SimplnxCore/docs/WriteLAMMPSFileFilter.md b/src/Plugins/SimplnxCore/docs/WriteLAMMPSFileFilter.md index 1447639280..f7ec695b39 100644 --- a/src/Plugins/SimplnxCore/docs/WriteLAMMPSFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteLAMMPSFileFilter.md @@ -6,13 +6,40 @@ IO (Output) ## Description -This **Filter** is used to create an atomistic representation of microstructure from image data. The data file produced by this **filter** can be used for initializing the atomic coordinates in LAMMPS package. +This filter writes atom coordinates from a **Vertex Geometry** (a point cloud, where each point is one atom) into an input file for **LAMMPS**. LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is an open-source molecular-dynamics code from Sandia National Laboratories that simulates the motion of atoms and molecules. -This **filter** should be used in conjunction with another **filter** named "Insert Atoms". Given a microstructure, the "Insert Atoms" filter follows the orientation of different features to insert atoms in them and saves the configuration of atoms in a **Vertex Data Container**. The "Export LAMMPS Filter" uses this **Vertex Data Container** to create an input file for LAMMPS. +The typical workflow first builds an atomistic representation of a microstructure with the *Insert Atoms* filter. Given a microstructure, *Insert Atoms* follows the crystallographic orientation of each **Feature** (grain) to place atoms inside it and stores the resulting atom positions in a **Vertex Geometry**. This **Write LAMMPS File** filter then reads that **Vertex Geometry** and writes a LAMMPS data file that LAMMPS can use to initialize the atom coordinates of a simulation. -% Auto generated parameter table will be inserted here +Atom coordinates are written in the physical units of the **Vertex Geometry** (the same units as the vertex positions, typically Angstroms or nanometers for atomistic data). The *Atom Feature Labels* array assigns each atom an atom type, so atoms belonging to different grains can be distinguished in the simulation. + +### Example Output + +A LAMMPS data file begins with header lines giving the atom and type counts and the simulation box bounds, followed by an `Atoms` section listing, for each atom, its ID, type, and x/y/z coordinates: + +```text +Number of Atoms + +8000 atoms +25 atom types + +0.0 100.0 xlo xhi +0.0 100.0 ylo yhi +0.0 100.0 zlo zhi -## Example Pipelines +Atoms + +1 1 0.000000 0.000000 0.000000 +2 1 1.500000 0.000000 0.000000 +3 2 3.000000 0.000000 0.000000 + .. +``` + +### Required Input Sources + +- **Vertex Geometry** -- the atom positions to export, typically produced by the *Insert Atoms* filter. +- **Atom Feature Labels** -- a per-atom integer array (one value per vertex) giving each atom's type, also produced by *Insert Atoms*. + +% Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/WriteLosAlamosFFTFilter.md b/src/Plugins/SimplnxCore/docs/WriteLosAlamosFFTFilter.md index 2b40aa11b1..e62a7fe75b 100644 --- a/src/Plugins/SimplnxCore/docs/WriteLosAlamosFFTFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteLosAlamosFFTFilter.md @@ -6,40 +6,36 @@ IO (Output) ## Description -This **Filter** will create the directories along the path to the file if possible. +This filter writes per-**Cell** data from an **Image Geometry** to a plain-text file formatted for Ricardo Lebensohn's FFT-based simulation codes[1]. That code is a full-field micromechanical *crystal-plasticity* simulation: it predicts how a polycrystalline microstructure deforms by solving the mechanical equations on the voxel grid using a Fast Fourier Transform (FFT) method, with one material point per voxel. -This **Filter** writes out **CellData** from an **Image Geometry** to a file that is appropriate to use as an input into Ricardo Lebensohn's FFT 3D simulation codes[1]. +Each line of the output describes a single **Cell** and combines its crystallographic orientation, its grid location, and its **Feature** (grain) and phase membership. The orientation is given as three **Euler angles** — three angles (in the Bunge Z-X-Z convention) that together specify how a crystal is rotated relative to the sample reference frame. -The format of the file is an ASCII text file with the following space delimited information: +If possible, the filter creates any missing directories along the path to the output file. + +The format of the file is an ASCII text file with the following space-delimited information: Phi1 Phi Phi2 X Y Z Feature_ID Phase_ID The Euler angles are in degrees. X, Y, Z are integer indices into the **Image** geometry. Feature ID & Phase ID are the integer values for the feature and phase **Starting at One (1)**. +### Required Input Sources + +- **Image Geometry** -- the voxel grid to export. +- **Cell Euler Angles** -- a 3-component, per-cell orientation array (Bunge Z-X-Z, in degrees), typically read from EBSD data via [Read EDAX EBSD Data (.ang)](../OrientationAnalysis/ReadAngDataFilter.md), [Read Oxford Instr. EBSD Data (.ctf)](../OrientationAnalysis/ReadCtfDataFilter.md), or [Read H5EBSD File](../OrientationAnalysis/ReadH5EbsdFilter.md). +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). +- **Cell Phases** -- a per-cell phase index, read alongside the Euler angles from the EBSD readers above. + ### Example Output -The output file: +The output file (columns: Phi1, Phi, Phi2, X, Y, Z, Feature_ID, Phase_ID): 90.000 0.000 0.000 1 1 1 0 1 - 90.000 0.000 0.000 2 1 1 0 1 - 90.000 0.000 0.000 3 1 1 0 1 + 90.000 0.000 0.000 2 1 1 0 1 + 90.000 0.000 0.000 3 1 1 0 1 90.000 0.000 0.000 4 1 1 0 1 - 90.000 0.000 0.000 5 1 1 0 1 - 90.000 0.000 0.000 6 1 1 0 1 - 90.000 0.000 0.000 7 1 1 0 1 - 90.000 0.000 0.000 8 1 1 0 1 - 90.000 0.000 0.000 9 1 1 0 1 - 90.000 0.000 0.000 10 1 1 0 1 - 90.000 0.000 0.000 11 1 1 0 1 - 90.000 0.000 0.000 12 1 1 0 1 - 90.000 0.000 0.000 13 1 1 0 1 - 90.000 0.000 0.000 14 1 1 0 1 - 90.000 0.000 0.000 15 1 1 0 1 - 90.000 0.000 0.000 16 1 1 0 1 - 90.000 0.000 0.000 17 1 1 0 1 - 135.009 55.304 295.274 18 1 1 1742 1 - 90.000 0.000 0.000 19 1 1 0 1 - .. + 135.009 55.304 295.274 18 1 1 1742 1 + 90.000 0.000 0.000 19 1 1 0 1 + .. % Auto generated parameter table will be inserted here @@ -47,8 +43,6 @@ The output file: [1] R.A. Lebensohn, 2001. N-site modeling of a 3D viscoplastic polycrystal using Fast Fourier Transform. Acta mater. 49, 2723-2737. -## Example Pipelines - ## License & Copyright Please see the description file distributed with this **Plugin** diff --git a/src/Plugins/SimplnxCore/docs/WriteNodesAndElementsFilesFilter.md b/src/Plugins/SimplnxCore/docs/WriteNodesAndElementsFilesFilter.md index 280fda67ba..1c6d4b9f91 100644 --- a/src/Plugins/SimplnxCore/docs/WriteNodesAndElementsFilesFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteNodesAndElementsFilesFilter.md @@ -8,7 +8,7 @@ IO (Output) This **Filter** exports node based geometries into structured text files. It allows users to save the following: -1. Node Data (Vertices): Export the coordinates of points that define the geometry. +1. Node Data (Vertices): Export the coordinates of points that define the geometry. The coordinates are written in the geometry's physical units (the same units as the geometry's vertex coordinates). 2. Element Data (Connectivity): Export the node indices that make up the edges, faces, or volumes of the geometry. The filter gives the user the option to export a node file, element file, or both. It also allows the user to decide whether or not to number the nodes and elements and whether or not to include headers for the node and element files. @@ -40,7 +40,7 @@ In this example output, the following filter parameter options have been selecte The output is listed below where column 1 is controlled by the `Number Elements/Cells` parameter and line #2 is controlled by the `Include Element/Cell File Header` parameter. -Some explanation as to the columns is requried for this output. +Some explanation as to the columns is required for this output. - Column #1 is just the index of the element - Column #2 is the number of vertices in this element. in this output, 3 since this was exported from a Triangle Geometry @@ -73,6 +73,10 @@ ELEMENT_NUM NUM_VERTS_IN_ELEMENT V0_Index V1_Index V2_Index | Hexahedral | 8 | +## Required Input Sources + +- **Node-based Geometry** -- any node-based geometry (**Vertex**, **Edge**, **Triangle**, **Quadrilateral**, **Tetrahedral**, or **Hexahedral Geometry**), produced by a surface-meshing filter such as [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md) or a geometry-creation filter such as [Create Geometry](CreateGeometryFilter.md). + % Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/WriteSPParksSitesFilter.md b/src/Plugins/SimplnxCore/docs/WriteSPParksSitesFilter.md index 443adeba36..7cc8629520 100644 --- a/src/Plugins/SimplnxCore/docs/WriteSPParksSitesFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteSPParksSitesFilter.md @@ -4,39 +4,50 @@ IO (Output) -## Description ## - -This **Filter** writes to a data file in a format used by [SPPARKS Kinetic Monte Carlo Simulator](http://spparks.sandia.gov/). - -+ The "Values" section is a pair of numbers where the first number is the site ID and the second number is the actual value of the **Feature** Id at that site. -+ LINE 4 evidently must be what is shown in the example file. -+ LINE 3 is the total number of **Cells**. -+ LINES 5, 6 and 7 are the dimensions of the volume. - -More information can be found at the [SPParks web site.](http://spparks.sandia.gov/doc/read_sites.html) or [http://spparks.sandia.gov/doc/dump.html](http://spparks.sandia.gov/doc/dump.html) - -**This filter will write an SPParks _Sites_ file format** - -## Example Output ## - - [LINE 1] - - [LINE 2] 3 dimension - [LINE 3] 8000000 sites - [LINE 4] 26 max neighbors - [LINE 5] 0 200 xlo xhi - [LINE 6] 0 200 ylo yhi - [LINE 7] 0 200 zlo zhi - [LINE 8] - [LINE 9] Values - [LINE 10] - 1 944 - 2 944 - 3 944 - 4 944 - 5 509 - 6 509 - 7 509 - .. +## Description + +This filter writes a data file in the format used by [SPPARKS](http://spparks.sandia.gov/). **SPPARKS** (Stochastic Parallel PARticle Kinetic Simulator) is an open-source Kinetic Monte Carlo code from Sandia National Laboratories used to simulate microstructure evolution, such as grain growth. + +SPPARKS represents the microstructure as a set of **sites**. In this export each site corresponds to one **Cell** (voxel) of the input **Image Geometry**, and the value stored at each site is that cell's **Feature** Id (the grain it belongs to). The `Values` section of the file is therefore a list of pairs: the first number in each pair is the site ID (running from *1*), and the second number is the Feature Id at that site. + +The header lines describe the lattice the sites live on: + +- **LINE 1** is intentionally left blank (a separator). +- **LINE 2** records the spatial dimension (always `3 dimension` for a 3D **Image Geometry**). +- **LINE 3** is the total number of **Cells** (sites). +- **LINE 4** is the maximum number of neighbors per site. For a 3D cubic lattice this is `26 max neighbors` (the 26 surrounding cells), and SPPARKS expects exactly this value for this lattice type. +- **LINES 5, 6, and 7** give the box extents along x, y, and z. These pairs (for example `0 200`) are **cell-index** extents — dimensionless counts of cells along each axis — not physical lengths in microns. +- **LINE 8** is a blank separator before the `Values` keyword. + +More information can be found in the SPPARKS documentation for [read_sites](http://spparks.sandia.gov/doc/read_sites.html) and [dump](http://spparks.sandia.gov/doc/dump.html). + +### Required Input Sources + +- **Image Geometry** -- the voxel grid whose cells become SPPARKS sites. +- **Cell Feature Ids** -- produced by a segmentation filter such as [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). The Feature Id at each cell becomes that site's value. + +### Example Output + +```text +[LINE 1] +[LINE 2] 3 dimension +[LINE 3] 8000000 sites +[LINE 4] 26 max neighbors +[LINE 5] 0 200 xlo xhi +[LINE 6] 0 200 ylo yhi +[LINE 7] 0 200 zlo zhi +[LINE 8] +[LINE 9] Values +[LINE 10] +1 944 +2 944 +3 944 +4 944 +5 509 +6 509 +7 509 + .. +``` % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/WriteStlFileFilter.md b/src/Plugins/SimplnxCore/docs/WriteStlFileFilter.md index 302c9dfa18..9e41cff946 100644 --- a/src/Plugins/SimplnxCore/docs/WriteStlFileFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteStlFileFilter.md @@ -6,21 +6,26 @@ IO (Output) ## Description -***WARNING:*** The filter now provides implict overflow capabilities for very large datasets, but **this will lead to many duplicated vertices being produced**. Be sure to run a cleaning algorithm when importing these files into DREAM3DNX or other software. For more info see below. +***WARNING:*** The filter now provides implicit overflow capabilities for very large datasets, but **this will lead to many duplicated vertices being produced**. Be sure to run a cleaning algorithm when importing these files into DREAM3DNX or other software. For more info see below. -This **Filter** can generate a single or multiple binary STL (StereoLithography) files for a given Triangle Geometry. +This **Filter** can generate a single or multiple binary STL (StereoLithography) files for a given **Triangle Geometry**. The vertex coordinates written to each STL file are in the **Triangle Geometry**'s physical units. ### File Grouping Type The *File Grouping Type* parameter provides the following choices: -- **Features [0]**: The user must supply a 2-component Int32 array where the values are the 2 features that each triangle belongs to. One STL file is written per feature. +- **Features [0]**: The user must supply a 2-component Int32 array (a **FaceLabels**-style array) where the two values for each triangle are the **Feature** IDs on either side of that triangle. One STL file is written per feature. - **Phases and Features [1]**: The same 2-component array as Features, plus a single-component array representing a higher-order grouping such as a phase or part number. - **Single File [2]**: The entire Triangle Geometry is saved as a single STL file. - **Part Index [3]**: The user must supply a single-component Int32 array at the triangle level that indicates which part each triangle belongs to. This filter supports overflow capabilities for all of the "File Grouping Type"(s) (including single file). This means if you have over the maximum number of triangles for a single STL file (2,147,483,647), the remaining triangles will be written to "overflow files" which will follow the following syntax `{filename}_overflow_{count}`. *Warnings will be emitted during preflight if it is known or a possibility this will occur.* Due to the nature of STL files containing all the vertices relative to the triangles in the file, **duplicate vertices will be written between the files**. For single file overflow, the files will be written in parallel with the number of additional tasks being equivalent to `({number of triangles in Geometry} / 2,147,483,647) + 1`. For multiple files, the existing tasks handling the grouping write out are also responsible for creating/writing any overflow files. +## Required Input Sources + +- **Triangle Geometry** -- a surface mesh produced by a surface-meshing filter such as [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). +- **Face Labels** (only when grouping by feature) -- a 2-component array, on the triangle/face data, holding the two **Feature** IDs on either side of each triangle. This is produced by the same surface-meshing step, for example [Create Surface Mesh (QuickMesh)](QuickSurfaceMeshFilter.md). + % Auto generated parameter table will be inserted here ## License & Copyright diff --git a/src/Plugins/SimplnxCore/docs/WriteVtkRectilinearGridFilter.md b/src/Plugins/SimplnxCore/docs/WriteVtkRectilinearGridFilter.md index 1a275277be..39612f039c 100644 --- a/src/Plugins/SimplnxCore/docs/WriteVtkRectilinearGridFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteVtkRectilinearGridFilter.md @@ -6,7 +6,20 @@ I/O Filters ## Description -This Filter writes a VTK legacy file with a Dataset type of `RECTILINEAR_GRID`. The user can select which arrays from the Image Geometry will be written to the file. +This filter writes the selected data to a **VTK legacy file**. A VTK legacy file is the older, human-readable file format used by the Visualization Toolkit (VTK); it can be opened directly by common scientific visualization tools such as **ParaView** and **VisIt**. + +The file is written with a dataset type of `RECTILINEAR_GRID`. A rectilinear grid stores three explicit per-axis coordinate arrays (one list of X positions, one of Y positions, and one of Z positions). The grid lines are axis-aligned but the spacing along each axis may vary. + +Although the input to this filter is an **Image Geometry** (which has a single uniform spacing along each axis), the output is written in the rectilinear-grid form: the filter expands the image's uniform spacing into the explicit per-axis coordinate arrays that the `RECTILINEAR_GRID` format requires. If the output only needs uniform spacing, the smaller [Write Vtk Structured Points](WriteVtkStructuredPointsFilter.md) format may be preferable. + +The user selects which **Cell** **Data Array**s from the **Image Geometry** are written into the file. Each selected array becomes a cell-data field in the VTK file. + +The *Write Binary File* parameter controls the on-disk encoding. When *false* (the default), the data is written as plain ASCII text, which is portable and easy to inspect but larger and slower to read. When *true*, the data is written in VTK's binary form, producing smaller files that load faster. + +### Required Input Sources + +- **Image Geometry** -- the geometry whose dimensions and spacing define the grid. +- **Cell Data Array(s) to write** -- any per-cell arrays on the **Image Geometry**. A common choice is a *FeatureIds* array produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here diff --git a/src/Plugins/SimplnxCore/docs/WriteVtkStructuredPointsFilter.md b/src/Plugins/SimplnxCore/docs/WriteVtkStructuredPointsFilter.md index 5c7808dcb6..3ad3e1e31c 100644 --- a/src/Plugins/SimplnxCore/docs/WriteVtkStructuredPointsFilter.md +++ b/src/Plugins/SimplnxCore/docs/WriteVtkStructuredPointsFilter.md @@ -6,9 +6,24 @@ I/O Filters ## Description -This Filter writes a VTK legacy file with a Dataset type of `STRUCTURED_POINTS`. The user can select which arrays from the Image Geometry will be written to the file. +This filter writes the selected data to a **VTK legacy file**. A VTK legacy file is the older, human-readable file format used by the Visualization Toolkit (VTK); it can be opened directly by common scientific visualization tools such as **ParaView** and **VisIt**. -Note: This filter only writes cell data to the VTK file. +The file is written with a dataset type of `STRUCTURED_POINTS`. A structured-points dataset describes a regular grid with uniform spacing along each axis: the grid is fully defined by its origin, its per-axis spacing, and its dimensions, so no explicit coordinate arrays are stored. This makes it the most compact VTK form for image data. + +The user selects which **Cell** **Data Array**s from the **Image Geometry** are written into the file. + +**Note:** This filter only writes cell data to the VTK file. + +### When to use this filter vs Write Vtk Rectilinear Grid + +Use **Write Vtk Structured Points** when the **Image Geometry** has uniform spacing (the usual case) and a compact file is desired. Use [Write Vtk Rectilinear Grid](WriteVtkRectilinearGridFilter.md) when the output must store explicit per-axis coordinate arrays (for example, to interoperate with a tool that expects a `RECTILINEAR_GRID` dataset). + +The *Write Binary File* parameter controls the on-disk encoding. When *false* (the default), the data is written as plain ASCII text, which is portable and easy to inspect but larger and slower to read. When *true*, the data is written in VTK's binary form, producing smaller files that load faster. + +### Required Input Sources + +- **Image Geometry** -- the geometry whose origin, spacing, and dimensions define the grid. +- **Cell Data Array(s) to write** -- any per-cell arrays on the **Image Geometry**. A common choice is a *FeatureIds* array produced by [Segment Features (Scalar)](ScalarSegmentFeaturesFilter.md). % Auto generated parameter table will be inserted here