DOC: Update filter documentation with figures and easier to read descriptions#1589
Open
imikejackson wants to merge 24 commits into
Open
DOC: Update filter documentation with figures and easier to read descriptions#1589imikejackson wants to merge 24 commits into
imikejackson wants to merge 24 commits into
Conversation
imikejackson
force-pushed
the
topic/documentation_update
branch
3 times, most recently
from
9b8844e to
c843a5a
Compare
imikejackson
force-pushed
the
topic/documentation_update
branch
from
c843a5a to
d02723b
Compare
imikejackson
force-pushed
the
topic/documentation_update
branch
from
8aff31f to
8aea5bc
Compare
ComputeGBCDMetricBasedFilter -- Broke up the dense paragraph about metrics into a numbered two-stage explanation (misorientation selection, then normal probing). Added a sentence explaining why metric-based avoids discretization artifacts vs binning. ComputeGBPDMetricBasedFilter -- Added a clear opening that explains what GBPD is and how it differs from GBCD (2D plane normals only vs full 5D). Added MRD interpretation (1.0 = random, >1.0 = preferred). Restructured the metric-based approach description. ComputeShapesTriangleGeomFilter -- Moved the caveats into a cleaner "Differences from the Image Geometry Version" section. Consolidated the watertight warning and Euler characteristic info into a single "Mesh Quality Requirements" section. Cross-referenced the Image Geometry version for output descriptions to avoid duplication.
- Add "Required Input Sources" section to filters with non-obvious upstream
dependencies, naming the specific filter that produces each required input.
- Convert inline filter name mentions to MyST markdown links
([Filter Name](FilterFile.md)) so they render as clickable cross-references
in the Sphinx-generated documentation.
- Remove redundant "Outputs" listing in ComputeFeatureNeighborCAxisMisalignments
(auto-generated parameter table already covers it).
- Replace existing {ref} directive in ComputeGBPDMetricBased with a simpler
MyST link.
…e-style Reference material extracted from the vv-filter-documentation skill so the lookup table can be grown by separate agents and the figure style guide is versioned with the project. - docs/upstream-filter-sources.md: input array → producing filter table with conventions for growing the table and a stub for future graph representation. - docs/filter-figure-style.md: canonical font, color palette, callout box, file format, and naming conventions for filter doc figures.
Triaged Geometry Creation / Manipulation batch (15 filters): - Tier 1 (Critical): 0 - Tier 2 (Important): 8 filters (CreateGeometry, ApplyTransformationToGeometry, RotateSampleRefFrame, ResampleImageGeom, ResampleRectGridToImageGeom, PadImageGeometry, QuickSurfaceMesh, InitializeImageGeomCellData) - Tier 3 (Polish): 7 filters (CreateImageGeometry, CombineTransformationMatrices, SetImageGeomOriginScaling, CropImageGeometry, AppendImageGeometry, PartitionGeometry, ComputeCoordinatesImageGeom) Added 14 Real-World Visualization Wishlist entries with priorities, and 3 new concept-page candidates (Geometry Types, Transformation Matrices, Sample vs Crystal Reference Frame).
Tier 2 (8 filters): CreateGeometry, ApplyTransformationToGeometry, RotateSampleRefFrame, ResampleImageGeom, ResampleRectGridToImageGeom, PadImageGeometry, QuickSurfaceMesh, InitializeImageGeomCellData. Tier 3 (7 filters): CreateImageGeometry, CombineTransformationMatrices, SetImageGeomOriginScaling, CropImageGeometry, AppendImageGeometry, PartitionGeometry, ComputeCoordinatesImageGeom. Each rewrite applied the established conventions: Required Input Sources section naming upstream producers, MyST cross-reference links, explicit units on numeric parameters, no duplication of the auto-generated parameter table. Notable structural changes: - CreateGeometry: trimmed and reorganized; promoted geometry-type taxonomy to a navigable table. - ApplyTransformationToGeometry: removed duplicate transformation-type listing; added explicit cross-reference to CombineTransformationMatrices. - RotateSampleRefFrame: prominent verified-only-for-axis-aligned banner; explicit distinction from ApplyTransformation. - QuickSurfaceMesh: deprecation banner promoted with explicit recommendation to use Surface Nets. - CropImageGeometry: documented voxels-vs-physical-bounds parameter explicitly. - PadImageGeometry: expanded Default Value semantics and Update Origin behavior. Build verified clean (no new Sphinx warnings).
- Tier 1 (Critical): 0 - Tier 2 (Important): 10 (CreateAttributeMatrix, CreateDataGroup, DeleteData, RenameDataObject, MoveData, CopyFeatureArrayToElementArray, CreateFeatureArrayFromElementArray, ConditionalSetValue, ConvertColorToGrayScale, ReshapeDataArray) - Tier 3 (Polish): 11 (CreateDataArray, CreateDataArrayAdvanced, CopyDataObject, CombineAttributeArrays, ConcatenateDataArrays, SplitDataArrayByComponent, SplitDataArrayByTuple, ExtractComponentAsArray, ConvertData, ArrayCalculator, InitializeData)
Tier 2 (10 filters): CreateAttributeMatrix, CreateDataGroup, DeleteData, RenameDataObject, MoveData, CopyFeatureArrayToElementArray, CreateFeatureArrayFromElementArray, ConditionalSetValue, ConvertColorToGrayScale, ReshapeDataArray. Tier 3 (11 filters): CreateDataArray, CreateDataArrayAdvanced, CopyDataObject, CombineAttributeArrays, ConcatenateDataArrays, SplitDataArrayByComponent, SplitDataArrayByTuple, ExtractComponentAsArray, ConvertData, ArrayCalculator, InitializeData. Notable structural changes: - CreateAttributeMatrix and CreateDataGroup: added 'What is X?' sections with explicit guidance on when to choose one over the other. - DeleteData: documented cascade-delete behavior across container types. - RenameDataObject: warning about downstream parameter references. - MoveData: explained tuple-count vs tuple-shape compatibility. - CreateFeatureArrayFromElementArray: promoted 'last element copied' footgun to a Warning section; cross-linked ComputeArrayStatistics. - ConditionalSetValue: split the two modes (mask vs value-match) into their own subsections. - ReshapeDataArray: critical 'does not move data in memory' warning promoted to top-level with safe-vs-dangerous examples. - InitializeData: restructured from rambly bullets into clean per-mode subsections. Build verified clean (no new Sphinx warnings).
imikejackson
force-pushed
the
topic/documentation_update
branch
from
8aea5bc to
2836ec0
Compare
Triaged all read/write filters across SimplnxCore and OrientationAnalysis
(24 readers + 20 writers). The design spec estimated ~15; the actual count
is 44 once the full EBSD/HDF5 reader set and format-specific exporters are
included.
Tier 1 (2): ReadH5OinaData (missing auto-table marker + hand-duplicated
parameter tables), WriteGBCDGMTFile (thin stub, undefined GBCD/GMT/pole
figure).
Tier 2 (24): format-specific readers/writers and EBSD readers needing
domain-term definitions, Required Input Sources sections, and fixes for
recurring defects (broken-bold "Ensemble Attribute Matrix**" across 5 EBSD
readers; {ref} -> MyST link conversions; legacy "Data Container" wording).
Tier 3 (15): polish — units, cross-links, typos. Notable: ReadNIfTIFile
hand-duplicates the auto parameter table (must remove); ReadImageStack
title mismatch ("Read Image Stack" vs humanName "Read Images [3D Stack]").
Tier 4 (3): ReadRawBinary, WriteImage, WriteDREAM3D — adequate as-is.
Also updated the stale branch reference in the tracker header, refreshed
the Progress Summary row, and appended Batch 7 entries to the Real-World
Visualization Wishlist and Concept Pages Needed tables.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two critical I/O filter docs rewritten:
- WriteGBCDGMTFile: expanded from a one-sentence stub. Added plain-language
"What is a GBCD Pole Figure?" (grain boundary, GBCD, misorientation, pole
figure, MRD), "What This Filter Does" (GMT is an external toolkit; this
filter only writes its .dat input), Parameter Guidance (now documents the
previously-undocumented Misorientation Axis-Angle parameter with units),
and a Required Input Sources section. Fixed the stale GMT URL.
- ReadH5OinaData: fixed structural defect — removed the hand-written
Parameters and Created Objects tables and inserted the missing auto
parameter-table marker so the real table renders. Replaced the stale
type table with a plain-language "What This Filter Produces" paragraph.
Fixed the phi2 +30 degree bullet that wrongly referenced ".ctf" files;
converted {ref} directives and bold-only filter mentions to MyST links.
Tracker updated: Tier 1 marked Done; Batch 7 now In Progress.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrote 24 I/O filter docs (SimplnxCore + OrientationAnalysis), grouped by
sub-theme. Common improvements: defined the external tool / file format on
first use; converted bold-only filter mentions and legacy {ref} directives
to MyST links; added "Required Input Sources" sections naming the producer
filters; stated explicit units; removed empty "Example Pipelines" headings.
Core data I/O: ReadHDF5Dataset (fixed internally-inconsistent worked
examples), WriteBinaryData (documented one-file-per-array no-header output;
cross-linked Read Raw Binary).
Geometry/volume readers: ReadStlFile (binary-only caveat; typo fix),
ReadVtkStructuredPoints (legacy "Data Container" -> Image Geometry; point
vs cell data), ReadVolumeGraphicsFile (defined Volume Graphics; normalized
group).
Simulation exporters: WriteAbaqusHexahedron, WriteLAMMPSFile,
WriteSPParksSites, WriteLosAlamosFFT, ReadDeformKeyFileV12 — defined each
external tool (Abaqus/LAMMPS/SPPARKS/FFT/DEFORM) and the produced/consumed
data.
VTK/Avizo/dream3d: WriteVtkRectilinearGrid, WriteVtkStructuredPoints,
WriteAvizoRectilinearCoordinate, WriteAvizoUniformCoordinate (defined
VTK/Avizo formats; cleaned garbled example headers), ReadDREAM3D
(documented selective/partial import).
EBSD readers: ReadEnsembleInfo, ReadAngData, ReadCtfData, ReadChannel5Data,
ReadH5Ebsd, ReadH5EspritData, ReadH5OimData — fixed the recurring broken
"Ensemble Attribute Matrix**" bold, {ref}->MyST links, defined EBSD jargon,
stated micron units; ReadH5Ebsd now documents its Import-to-H5EBSD input
dependency; fixed the Channel5 ".ctf" copy-paste error.
OA writers: WriteGBCDTriangleData (fixed column-legend numbering; added
Required Input Sources), WritePoleFigure (defined pole figure/Lambert/Laue;
converted the input-array list into Required Input Sources).
All 24 verified: titles match humanName(), exactly one auto-table marker
each, no leftover {ref}/hand tables, all MyST link targets resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tier 3 polish (15): targeted fixes on docs that were already mostly clear.
- ReadCSVFile / ReadStringDataArray / ReadTextDataArray: typo fixes, quoted
"Read CSV Filter" -> MyST links, descriptive image alt-text.
- WriteASCIIData: cleaned the cluttered Group line; documented Maximum
Tuples Per Line.
- WriteFeatureDataCSV: defined Feature; explained the feature-count line;
added Required Input Sources.
- ReadImage / ReadImageStack: fixed the ReadImageStack title to match
humanName ("Read Images [3D Stack]"); cross-linked the two; added a
file-list/slice-ordering subsection; stated units.
- ReadNIfTIFile: removed the hand-written Parameters table that duplicated
the auto-table (kept Caveats); glossed sform/qform/pixdim/etc.
- ReadZeissTxmFile / ReadBinaryCTNorthstar: defined xCT/CT; normalized
group/headings; named outputs; noted inclusive voxel subvolume bounds.
- WriteNodesAndElementsFiles / WriteStlFile: Required Input Sources; typo
fixes; clarified the 2-component FaceLabels array.
- ReadGrainMapper3D: GrainMapper3D/XNovo gloss; mm-vs-microns caveat.
- WriteINLFile: per-column units; explained the symmetry codes.
- WriteStatsGenOdfAngleFile: expanded ODF; Required Input Sources.
Tier 4 adequate (3): minor consistency touches only.
- ReadRawBinary / WriteImage: added Required Input Sources.
- WriteDREAM3D: added the missing Group (Subgroup) header + Required Input
Sources note.
All 18 verified: titles match humanName(), one auto-table marker each, no
{ref}/hand tables, all MyST links resolve. Batch 7 (44 filters) complete.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The written data row has 10 columns (1-3 right-hand orientation, 4-6 left-hand orientation, 7-9 triangle normal, 10 surface area), but the file header labeled surface area as "Column 8", which collides with the triangle-normal columns. Corrected to "Column 10" to match the actual output. The filter documentation was already corrected in Batch 7. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Triaged the catch-all of SimplnxCore filters not covered by Batches 1-7 (statistics, feature geometry, clustering/point-cloud, triangle/mesh compute, surface meshing/smoothing, mesh editing, thresholding/color, utilities). The ITK plugin (Batch 8) is deferred. Tier split: T1=4, T2=35, T3=31, T4=3. Tier 1 (Critical): FlyingEdges3D, TriangleDihedralAngle, NearestPointFuseRegularGrids, PointSampleEdgeGeometry — stubs or stale "Data Container" terminology. Recurring defects flagged for the rewrite phase: two more hand-duplicated parameter tables (HierarchicalSmooth; CreatePythonSkeleton, which also lacks the auto-table marker), a legacy @ref directive (ComputeBoundingBoxStats), Doxygen math/@image artifacts (Silhouette, FeatureFaceCurvature, PointSampleTriangleGeometry), more legacy "Data Container" wording, and many bold-only filter mentions to convert to MyST links. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Four critical SimplnxCore stubs rewritten: - FlyingEdges3D: defined isosurface/contour and the isovalue; contrasted with Surface Nets/Quick Surface Mesh; documented units + inputs. - TriangleDihedralAngle: explained minimum-interior-angle as a mesh-quality metric; stated degrees (0-60); added Required Input Sources. - NearestPointFuseRegularGrids: replaced legacy "Data Container" with Image Geometry; explained Reference vs Sampling and nearest-cell assignment. - PointSampleEdgeGeometry: added missing Group header; defined Edge Geometry / scan vector; stated Sampling Spacing is in millimeters. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrote 35 SimplnxCore filter docs across six sub-themes (statistics,
feature analysis, clustering/point-cloud, triangle/mesh compute, surface
meshing/smoothing, mesh editing/sampling). Common improvements: defined
domain jargon on first use (RDF, Voronoi, isosurface, winding, Face Labels,
triple line/quad point, gradient magnitude, curvature); stated explicit
units (areas length^2, volumes length^3, curvature 1/length, distances,
fractions [0,1], degrees); added Required Input Sources naming producers;
converted bold-only/italic/{ref}/@ref/@image/Doxygen-math to MyST links and
MyST math.
Notable fixes: removed hand-duplicated content; reconciled
ComputeVolumeFractions' count-vs-volume-fraction wording; corrected the
RobustAutomaticThreshold producer (Find Derivatives no longer exists ->
ITK Gradient Magnitude); fixed the RemoveFlaggedTriangles Vertices->Triangles
copy-paste; corrected several stale "DREAM3D Review" group lines; fixed the
ComputeKMeans/KMedoids broken "Ensemble Attribute Matrix" bold; converted
SilhouetteFilter Doxygen math to MyST.
All 35 verified: titles match humanName(), one auto-table marker each, no
{ref}/@ref/Doxygen/hand tables, all MyST link targets resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tier 3 polish (31): targeted fixes — defined jargon (mode, aliasing,
Ensemble, winding, STL, RDF context), stated units (1/length ratios,
square/physical areas, physical coordinates vs voxel indices, degrees),
added Required Input Sources, and converted bold-only/italic mentions to
MyST links. Structural fixes: removed the hand-duplicated Parameters table
in HierarchicalSmooth; added the missing auto-table marker and removed the
hand-written parameter list in CreatePythonSkeleton; added missing Group
headers (CreateColorMap, CropEdgeGeometry, ExtractPipelineToFile) and the
missing Help footer (ExtractPipelineToFile); replaced legacy "Data
Container" wording (RemoveFlaggedVertices). Trimmed the oversized data dump
in ComputeArrayHistogram.
Tier 4 adequate (3): minor touches — Required Input Sources for
ComputeFeatureSizes and ComputeBoundaryCells (plus its 0-6 output range),
and a MyST link + Required Input Sources for ComputeGroupingDensity.
All 34 verified: titles match humanName(), one auto-table marker each, no
{ref}/@ref/Doxygen/hand tables, all MyST link targets resolve. Batch 9
(73 filters) complete.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.