[imikejackson]

Summary

This change makes filter parameters declare the component shape or DataType that their algorithms read. Before, these filters accepted a DataArray with any component shape and then read it with a fixed stride, so the result was wrong output, a read past the end of an array, or a crash. Parameter validation now rejects such a DataArray before the filter runs. Where a fixed parameter shape cannot express the requirement, preflight checks it. Each fix has its own commit and a regression test. No test data archive is added or changed.

Behavior changes

Saved pipelines that select one of the inputs below with another shape or DataType now fail parameter validation or preflight. In most cases such an input was read incorrectly or crashed. The shape check is exact, so a {1,1} or {1,3} DataArray is now also rejected, even though the algorithm read it correctly. This follows the usual simplnx convention.

• ComputeVertexToTriangleDistances: Triangle Normals must have 3 components (−208).
• ComputeShapesTriangleGeom: Face Feature Centroids must have 3 components (−208).
• ComputeShapes and ComputeFeaturePhasesBinary: Cell Feature Ids must have 1 component (−208).
• ComputeKMeans and ComputeKMedoids: when the mask is used, the mask DataArray must have 1 component (−208) and the same number of tuples as Attribute Array to Cluster (ComputeKMeans −7588, ComputeKMedoids −7589, preflight).
• ComputeNumFeatures: Feature Phases must be a 1-component int32 DataArray (−208, −207). Any other DataType made execute dereference a null pointer. Execute now returns −9740 when a feature's phase is negative or not less than the Ensemble Attribute Matrix tuple count, instead of writing past the end of the output.
• ComputeGBCDPoleFigure (−34645) and WriteGBCDGMTFile (−96713): preflight requires the GBCD DataArray to have 6 component dimensions: 5 positive bin dimensions and a final dimension of 2. Before, another shape read past the end of the shape vector or of the data.
• DBSCAN: with Use Mask Array on, Cell Mask Array must have 1 component (−208) and the same number of tuples as Attribute Array to Cluster (−7587, preflight). The Direct algorithm read such a mask by flat element, while the Scanline algorithm rejected it at execute; both now behave the same. The Scanline out-of-core check that compared the component count with the selected dimensionality is removed, because it could not fail. Its dimensionality (−54060) and mask (−54062) checks stay, because the algorithm can be called without the filter; their messages now give the actual counts, and a new test calls the algorithm directly to reach them.
• DBSCAN, ComputeKMeans, ComputeKMedoids: a StringArray mask with the wrong number of tuples now returns the tuple-count error. Before the fix in this PR's follow-up commits, building that error message threw std::bad_cast. (The mask parameter itself still accepts a StringArray; that is an older gap in ArraySelectionParameter and is left for a separate fix.)

Test plan

• Each new regression test passes. The rejection tests fail on develop because preflight accepts the wrong shape, DataType or tuple count, or because the out-of-range phase is not rejected. The ComputeNumFeatures valid-phase case also passes on develop; it guards against over-rejection.
• The DBSCAN tests pass in both in-memory algorithm scenarios.
• The full test suite passes.
• The example pipelines that use the changed filters preflight without new errors.
• CI passes on all supported platforms.

[joeykleingers]

Reviewed at 25ba5f78. The fixes are right; the changes below are small.

Requested changes

1. A StringArray mask now makes preflight throw (DBSCAN, ComputeKMeans, ComputeKMedoids).
ArraySelectionParameter::validatePath accepts any IArray and only runs the type and component-shape checks on an IDataArray, so a StringArray passes the bool/uint8 {1} declaration. When its tuple count differs from Attribute Array to Cluster, CheckArraysHaveSameTupleCount detects it (it reads IArray), but the new error message calls getDataRefAs<IDataArray>(maskPath), which throws std::bad_cast. IFilter::preflight does not catch it.

• src/Plugins/SimplnxCore/src/SimplnxCore/Filters/DBSCANFilter.cpp:159
• src/Plugins/SimplnxCore/src/SimplnxCore/Filters/ComputeKMeansFilter.cpp:135
• src/Plugins/SimplnxCore/src/SimplnxCore/Filters/ComputeKMedoidsFilter.cpp:140

Fix: use getDataRefAs<IArray> in those three messages. (The StringArray gap in ArraySelectionParameter itself predates this PR and can be a separate fix.)

2. DBSCAN documentation.

• src/Plugins/SimplnxCore/docs/DBSCANFilter.md:191 states the 1-component rule unconditionally and omits the new tuple-count rule (the KMeans and KMedoids pages include it). Suggested text: "When Use Mask Array is enabled, Cell Mask Array must have 1 component and the same number of tuples as Attribute Array to Cluster."
• src/Plugins/SimplnxCore/vv/deviations/DBSCANFilter.md:138 names the tests SimplnxCore::DBSCANFilter: Reject …; the registered names are SimplnxCore::DBSCAN: Reject multi-component mask in preflight and SimplnxCore::DBSCAN: Reject short mask in preflight (DBSCANTest.cpp:681, :705).
• The PR says the DBSCAN V&V documents now reference 6.5.171 only, but the linked src/Plugins/SimplnxCore/vv/provenance/dbscan_test.md:106 still describes a 6.5.172 comparison.

3. PR description.

• The diff is +649/−30, not +535/−30.
• Behavior changes omits the ComputeKMeans (−7588) and ComputeKMedoids (−7589) mask tuple-count checks.
• "Each new test fails on develop" is too broad: the valid-phase counting case in ComputeNumFeaturesTest.cpp passes on develop.
• AllowedComponentShapes{{1}} / {{3}} compare shapes exactly, so {1,1} and {1,3} arrays are now rejected although the algorithms read them correctly. That matches the usual simplnx convention, but "each of these inputs was already read incorrectly" is not strictly true; a sentence noting it would cover it.

Checked and correct

• The {1} and {3} constraints match the strides the algorithms read.
• Mask validation is skipped when masking is off, including an empty mask path; bool and uint8 masks are still accepted.
• The GBCD shape check tests the rank before indexing dimension 5 and matches the layout Compute GBCD produces.
• ComputeNumFeatures −9740 rejects negative phases and phases ≥ the Ensemble tuple count, skips feature 0, and runs before any counts are written.
• The removed DBSCANScanline guards are unreachable through the filter: Attribute Array to Cluster is limited to {2}/{3} and the mask shape and tuple count are now checked in preflight.
• New error codes do not collide; no parameter-version bump is needed; no checked-in example pipeline or Python example is broken by the new rules.
• All changed C++ files match clang-format 19.1.1.

Pre-existing gaps (not from this PR; possible follow-up issue)

• WriteGBCDGMTFile.cpp:155 indexes Crystal Structures with Phase of Interest without checking that array's length or a negative phase.
• GBCD dimension products are computed in int32 and overflow for a large but valid shape (e.g. {1024,1024,1024,1,1,2}).
• Unchecked tuple counts between related inputs: normals vs. triangles (ComputeVertexToTriangleDistances), centroids vs. the output Feature Attribute Matrix (ComputeShapesTriangleGeom), Feature Ids vs. mask (ComputeFeaturePhasesBinary), Feature Ids vs. the geometry's cell count (ComputeShapes).
• ComputeNumFeatures: the int32 counter can overflow, and neither loop checks cancellation or reports progress.

Not verified: no build or test run was done for this review, so the test-plan items (local suite, failure on develop, CI) rely on the PR's own evidence.

[imikejackson]

@joeykleingers All items are fixed as requested

[joeykleingers]

Re-reviewed at 65a3038e. The three StringArray fixes and their tests are right, and the DBSCAN page, test names and PR description are fixed. One item still needs a change; the rest are small.

Requested change

The DBSCAN provenance record now names a legacy version the evidence does not support.
src/Plugins/SimplnxCore/vv/provenance/dbscan_test.md:101 and :106 relabel the August 5 comparison from 6.5.172 to 6.5.171. Everywhere else, the DBSCAN report describes that run as a local legacy proof build:

• src/Plugins/SimplnxCore/vv/DBSCANFilter.md:22
• the Legacy runner line in its Phase 9 setup
• src/Plugins/SimplnxCore/vv/deviations/DBSCANFilter.md:22

docs/vv_templates/report_gates.md:27 says to describe a patched local build exactly that way and not to give it a release version. As written, the record says a stock 6.5.171 binary produced those results. (My last review only noted the mismatch; correcting the version in this direction isn't supported.)

Fix: use version-neutral wording, e.g. "The historical local legacy proof build, using the DREAM3DReview DBSCAN filter, was run against the same six sklearn datasets.", with a matching heading.

Small items

• src/Plugins/SimplnxCore/vv/DBSCANFilter.md:20: Tests today says 14 tests plus 1 hidden. There are now 15 plus 1 hidden, and SimplnxCore::DBSCAN: Reject short StringArray mask in preflight is not in the coverage table (it belongs with the tuple-count row, Reject short mask in preflight).
• src/Plugins/SimplnxCore/docs/ComputeKMeansFilter.md:15 and src/Plugins/SimplnxCore/docs/ComputeKMedoidsFilter.md:67 still state the 1-component rule unconditionally, the same wording just fixed in DBSCANFilter.md. Suggested text: "When Use Mask Array is enabled, Cell Mask Array (KMedoids: Mask Array) must have 1 component and the same number of tuples as Attribute Array to Cluster."
• PR description, Note for reviewers: #1763 is already in the base (8bed04ce9), so "conflicts will be resolved when those merge" no longer applies to it.

Checked and correct

• The rebase onto the current develop kept both develop's #1763 changes and this PR's additions in the ComputeKMeans page, filter and tests. The 12 original commits are otherwise unchanged.
• getDataRefAs<IArray> is safe at all three call sites: parameter validation rejects missing paths and non-arrays before preflightImpl runs.
• The three new tests reach the branch that threw at 25ba5f78, and they are deterministic.
• Each of −7587, −7588, −7589, −9740, −34645 and −96713 is emitted at exactly one place in the source.
• The diff is 34 files, +743/−32, matching the description.

Separate follow-up (not this PR)

A StringArray mask with the right number of tuples still passes preflight, as it does on develop. Execute then returns an error in most paths, but ComputeKMeans Scanline treats it as no mask and silently ignores it. That fits with the existing ArraySelectionParameter StringArray gap as a separate fix.

Correction to my last review: WriteGBCDGMTFile preflight does reject a negative phase. A short Crystal Structures array is still unchecked there.