Skip to content

ENH: Check the C-Axis Reference Misalignments inputs only in preflight - #1975

Open
joeykleingers wants to merge 1 commit into
BlueQuartzSoftware:developfrom
joeykleingers:topic/caxis-preflight-only
Open

joeykleingers wants to merge 1 commit into
BlueQuartzSoftware:developfrom
joeykleingers:topic/caxis-preflight-only

Conversation

@joeykleingers

Copy link
Copy Markdown
Contributor

Summary

The Compute C-Axis Reference Misalignments filter now checks each input one time, in preflight. This applies the knowledge-base rule "Run a filter, not its algorithm" (PR #1959) to the only filter that still followed the previous rule. IFilter::execute() always runs preflight before executeImpl(). Thus the input checks that the algorithm repeated through its static ComputeCAxisReferenceMisalignments::ValidateInputs() checked the same inputs a second time on every run. 5 files changed, +213 / −470 lines.

1. Input checks in the filter

  • src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/ComputeCAxisReferenceMisalignmentsFilter.cpp: the preflight input checks.
  • src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/ComputeCAxisReferenceMisalignmentsFilter.hpp: the preflight error codes and k_MinReferenceDirectionNorm.

preflightImpl() keeps only the checks that the parameters cannot make:

  • The reference direction has finite components and a length greater than 1.0e-12 (-98710).
  • Each selected array is a DataArray of the required type: Input Quaternions (-98715), Phases (-98717), Mask when Use Mask is on (-98719) and Crystal Structures (-98721). ArraySelectionParameter applies its type list only to an IDataArray, so a StringArray selection gets to preflightImpl().
  • Phases and the enabled mask have one tuple per quaternion (-98711).
  • The output name is not the name of an input array (-98726).

These codes now belong to ComputeCAxisReferenceMisalignmentsFilter. Their values do not change.

2. The algorithm relies on preflight

  • src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/Algorithms/ComputeCAxisReferenceMisalignments.{hpp,cpp}

The algorithm no longer checks its inputs or the output array that the preflight CreateArrayAction creates. Its @pre lines give the preconditions. It keeps the checks that preflight cannot make: a phase value that is not an index into Crystal Structures (-98712), the non-hexagonal warning (-98713), and the result of each read and write.

3. Removed error codes

No path through the filter can return these codes, so they are removed:

  • -98714: the reference direction does not have three components. VectorParameter rejects this before preflight.
  • -98716, -98718, -98720, -98722: an input with the wrong component shape. The AllowedComponentShapes of each ArraySelectionParameter reject this before preflight.
  • -98723, -98724, -98725: an output array with the wrong type, component shape or tuple count. The preflight CreateArrayAction creates the output as float32 with component shape {1} and the quaternion tuple shape.

The filter was added after the DREAM3D-NX 7.4.2 release, so no released error code changes. The filter documentation lists no error codes and does not change.

4. Tests

  • src/Plugins/OrientationAnalysis/test/ComputeCAxisReferenceMisalignmentsTest.cpp

The tests that called the algorithm directly are removed. Each input check is reached through the filter. The StringArray preflight test now selects a StringArray for each of the four arrays and asserts the type error code of that array.

Test plan

  • All 19 ComputeCAxisReferenceMisalignments tests pass in an in-core Release build (SIMPLNX_TEST_ALGORITHM_PATH=0) on macOS arm64.
  • All 19 ComputeCAxisReferenceMisalignments tests pass in an out-of-core Release build (DREAM3DNX_ENABLE_OOC=ON, SIMPLNX_TEST_ALGORITHM_PATH=1) on macOS arm64.
  • Each of the 7 remaining preflight error codes has a test that reaches it through the filter and asserts its code.
  • CI passes on all platforms.

Related Issue

Closes #1966

@joeykleingers joeykleingers self-assigned this Nov 13, 2026
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

IFilter::execute() always runs preflight before executeImpl(), so the
input checks that ComputeCAxisReferenceMisalignments::operator()()
repeated through the static ValidateInputs() only checked the same
inputs a second time on every run. This change applies the
knowledge-base rule "Run a filter, not its algorithm" to this filter.

* The input checks move into the filter. Preflight keeps only the checks
  that the parameters cannot make: the reference direction is finite and
  not near zero, each selected array is a DataArray of the required type
  (ArraySelectionParameter does not stop a StringArray), Phases and the
  enabled mask have one tuple per quaternion, and the output path is
  not an input path.
* The algorithm no longer checks its inputs or the output array that
  preflight creates. It keeps the phase range check (-98712) and the
  non-hexagonal warning (-98713). Its @pre lines give its preconditions.
* Error codes -98714, -98716, -98718, -98720 and -98722 to -98725 are
  removed, because no path through the filter can return them. The
  remaining preflight codes move to the filter class.
* The tests that called the algorithm directly are removed. The
  StringArray preflight test now reaches the type checks of all four
  selected arrays (-98715, -98717, -98719, -98721) through the filter.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
@joeykleingers
joeykleingers force-pushed the topic/caxis-preflight-only branch from d45c7ec to ea9b052 Compare November 13, 2026 20:43

@imikejackson imikejackson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of PR #1975 at ea9b052

Verdict: REQUEST CHANGES. One Critical finding (2.1): some preflight code repeats checks that ArraySelectionParameter already makes. Everything else is Minor or Nit.

The PR does what #1966 asks. Each claim in the description holds against the code:

  • VectorParameter rejects a wrong-size vector, so -98714 could never be returned.
  • The AllowedComponentShapes of each selection reject a wrong shape, so -98716, -98718, -98720 and -98722 could never be returned.
  • The preflight CreateArrayAction fixes the output type, shape and tuple count, so -98723, -98724 and -98725 could never be returned.

Validation: I built OrientationAnalysisUnitTest in an in-core Release DREAM3D-NX build on macOS arm64 with no warnings. All 19 ComputeCAxisReferenceMisalignments tests pass with ctest -j 1. clang-format 19.1.1 is clean on all 5 files. I did not run clang-tidy or an out-of-core build.


1. Solves the issue with good design

  • 1.1 The algorithm no longer repeats any input check. It keeps only the checks that need array values: the phase index (-98712) and the non-hexagonal warning (-98713). The @pre lines document the preconditions.
  • 1.2 The tuple-count check between sibling arrays in preflight has not changed, so this PR adds no new rejection of placeholder counts.
  • 1.3 [Nit] ComputeCAxisReferenceMisalignments.hpp:74: the @pre text hard-codes 1.0e-12. Name the constant instead: ComputeCAxisReferenceMisalignmentsFilter::k_MinReferenceDirectionNorm.

2. Error handling and defensive programming

  • 2.1 [Critical] ComputeCAxisReferenceMisalignmentsFilter.cpp: the preflight helpers repeat checks that ArraySelectionParameter::validatePath already makes before preflightImpl() runs:

    • MakeArrayTypeError (line 71) has a "path does not exist" branch. The parameter already rejects a missing path (k_Validate_Does_Not_Exist).
    • DescribeObjectType (line 50) has an IDataArray branch. It and the mask condition getDataType() != DataType::boolean && != DataType::uint8 (line 181) check the element type of a DataArray. The parameter's AllowedTypes already rejects a DataArray of the wrong type (k_Validate_AllowedType_Error).

    No path through the filter can reach these branches. The tests that covered their messages were deleted in this PR. Removing this kind of repeated check is the point of #1966.

    Fix: keep a single check that does not throw, and that fails only for a selected IArray that is not an IDataArray. Message: " path '' has type '<getTypeName()>', but a DataArray of type is required." Then:

    • remove the null branch and the IDataArray branch of DescribeObjectType;
    • reduce the mask check to getDataAs<IDataArray>(maskPath) == nullptr;
    • remove the TypesUtility.hpp include if it is no longer used.
  • 2.2 [Minor] A NeighborList reaches the same checks: INeighborList derives from IArray, not from IDataArray. The comment at line 82, the PR description and the test at ComputeCAxisReferenceMisalignmentsTest.cpp:712 name only StringArray. Fix: add a NeighborList<float32> row to that test, or change the wording to "an array that is not a DataArray (StringArray, NeighborList)".

  • 2.3 [Nit] The type checks that remain (-98715, -98717, -98719, -98721) are temporary guards. They exist because ArraySelectionParameter does not yet enforce the array kind. That parameter fix is tracked in #1833, which follows #1821; the summary issue #1869 also points to it. #1869 asks that each such local guard link #1833 in a code comment, so it can be removed when the parameter takes over. Fix: add a comment such as // Temporary guard until #1833 makes ArraySelectionParameter enforce the array kind. above ValidateArrayType and in the doc comment of ValidateInputs.

  • 2.4 [Minor] The merge order matters with #1991, which moves NaN and infinity rejection into VectorParameter. After #1991 merges:

    • the isfinite part of -98710 can no longer be reached. Under the same rule as 2.1, it then repeats a parameter check;
    • the NaN and infinity rows of the invalid reference test (...Test.cpp:608) will get a parameter error code instead.

    Whichever of the two PRs merges second removes the isfinite part, keeps the length check, and updates that test.

  • 2.5 [Nit] The filter's error codes are now declared in two classes: -98712 and -98713 in the algorithm, the rest in the filter. That split is correct. Add a one-line comment in each header that points to the other.

3. Work beyond the issue

  • 3.1 Nothing goes beyond the issue. Moving the codes and k_MinReferenceDirectionNorm into the filter follows directly from the rule.

4. Documentation and tests

  • 4.1 ComputeCAxisReferenceMisalignmentsFilter.md lists no error codes. Its description of the behavior is still accurate, so it needs no change.
  • 4.2 Deleting the direct-algorithm test loses no coverage of code the filter can reach. These are all still exercised through the filter:
    • uint8 and bool masks;
    • valid inputs (the oracle tests);
    • phase out of range (-1, 5 and INT32_MAX);
    • Phases and Mask tuple-count mismatch;
    • all 7 preflight codes, each asserted.
  • 4.3 [Nit] The test plan says the out-of-core run used DREAM3DNX_ENABLE_OOC=ON. #1995 and DREAM3DNX#1255 rename that option to DREAM3D_ENABLE_OOC. Consider writing "DREAM3D-NX out-of-core build" so the description stays correct after the rename. This does not affect the C-Axis tests, which OrientationAnalysisOocStoreContracts does not include.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ENH: Check the C-Axis Reference Misalignments inputs only in preflight

2 participants