[imikejackson]

Summary

This PR adds the Compute C-Axis Reference Misalignments filter. The filter calculates the angle between the hexagonal c-axis of each orientation and a reference direction in the sample frame. Use the angle to find "hard" HCP grains (c-axis nearly parallel to the loading direction) and "soft" HCP grains (c-axis nearly perpendicular to it).

This PR replaces #1761. That PR used a 3-component c-axis array as its input, so the filter also accepted Euler angles and other 3-component arrays and gave incorrect angles. This filter uses quaternions as its input.

• The input is a quaternion array, a Phases array with the same tuple count, and a Crystal Structures array. The filter works on cell Quats, feature AvgQuats, or other quaternion arrays. The output array is created next to the input array.
• The filter accepts only Hexagonal_High and Hexagonal_Low phases. Other phases get NaN. A warning gives the number of unmasked tuples with a known non-hexagonal phase. Tuples with UnknownCrystalStructure do not add to this number.
• An optional mask (bool or uint8) sets NaN on the masked tuples.
• A zero quaternion or a quaternion with a NaN or infinite component gets NaN. The filter normalizes every other quaternion and moves it to the positive hemisphere before it uses it, so the input quaternions do not need to be unit length.
• Preflight rejects a reference direction that has a length of 1e-12 or less, or a value that is not finite. Preflight also rejects quaternion and phase arrays, and the mask when it is enabled, that have different tuple counts.
• The filter reads the arrays in chunks of a fixed size with bulk I/O. It does not allocate temporary arrays of the full size.
• The output angles are in degrees, from 0 to 90. The c-axis has antipodal symmetry, so the filter uses the absolute value of the dot product.

Test Plan

• 16 unit tests for the new filter pass in OrientationAnalysisUnitTest (ci-macos-arm64, run serially). The expected values come from the closed-form c-axis for Bunge Euler angles, (sin φ1 sin Φ, −cos φ1 sin Φ, cos Φ), and not from the filter. The tests cover:
  • fixed cases, references that are not unit vectors, and a sweep with a fixed random seed
  • cell and feature levels
  • bool and uint8 masks, and masked non-hexagonal tuples that must not add to the warning
  • mixed phases, chunk boundaries, empty input and cancellation
  • zero, non-finite and scaled quaternions
  • error paths and a rejected Euler-angle input
  • real out-of-core stores (see below)
• Each test runs with both in-memory store scenarios of the same implementation.
• The ComputeAvgCAxes, ComputeIPFColors and ComputeCAxisLocations tests still pass (37 of 37 tests in total, in both builds below).
• A pipeline on a Ti EBSD data set (882,318 cells, 623 features) gives the same angles as an independent Python calculation. The maximum difference is 2.0e-5° for cells and 3.8e-6° for features. The NaN tuples are the same.
• Out-of-core: the test "out-of-core stores" forces out-of-core storage before it creates the arrays. It uses 12,305 tuples (three full chunks and a partial chunk), bool and uint8 masks, a phase pattern that changes between chunks, and a zero quaternion. In a DREAM3D-NX build with DREAM3DNX_USE_OOC=ON, the test requires that the quaternion, phase, crystal structure, mask and output stores use the HDF5-OOC format. All 37 tests pass in that build and in the ci-macos-arm64 build.
• The Ti EBSD pipeline in a DREAM3D-NX out-of-core build, with out-of-core storage forced for all arrays, gives output that is identical bit for bit to the in-core output.

Related Issue

Closes #992
Related to #1891

[joeykleingers]

Approved. I pushed one review commit (fdc9b9977) on top of your filter commit and rebased the branch on develop (705a1b7f2). These are the changes from the review:

Behavior

• A zero-length quaternion gave 90°, which reads as a "soft" orientation. A quaternion with a non-finite component, or with a length of 1e-6 or less, now gives NaN.
• The algorithm class now checks its own inputs, as the new code guidelines (#1889) require for a direct call: the type and component shape of each array, the tuple counts of Phases and the mask, and the output array. Before, a 5-component quaternion array was read with the wrong stride and a wrong array type threw.
• Preflight runs the same input checks. A StringArray selection passes ArraySelectionParameter (#1833, #1821) and made preflight throw std::bad_cast. Now preflight returns an error.
• Preflight rejects an output name that is the name of an input array.
• The filter tag is "Statistics", like the other c-axis filters.

Error codes and messages

• Each failure branch has its own named code (-98710 to -98726). The reference-direction size check no longer shares -98710.
• The messages give the path, the actual value or type, and an action. The non-hexagonal warning now tells the user how to suppress it.

Tests (15, all pass)

• Direct algorithm calls for each input check, a StringArray and output-name check in preflight, and scaled, negated, non-finite and near-zero quaternions.
• Zero tuples and inputs inside a DataGroup.
• Every error test asserts its code, and tests that share a code also assert the message. The "hexagonal phases only" test now runs through the store scenarios.
• The tests use float64 and do not call UnitTest::LoadPlugins().

Docs

• The page names the filters that create the Phases and Crystal Structures inputs and states the NaN rules.

The PR description is updated to match. The out-of-core run in the test plan is still open.

[joeykleingers]

Approved on 64e3f64b3. Mike's push replaced my review commit, so I put the review changes back on top of his five commits. Where the changes overlapped, I kept his version:

• NaN rule: his rule is kept. A zero quaternion or a quaternion with a NaN or infinite component gets NaN. My earlier comment said "a length of 1e-6 or less". That cutoff is not in the code, because it failed his 1e-30 scale test.
• His tests for masked non-hexagonal tuples, zero, non-finite and scaled quaternions, empty input and cancellation are kept. They now run without UnitTest::LoadPlugins() and through the store scenarios. I removed my tests that his tests duplicated.
• His header and documentation text is kept. I added the paragraph that names the filters that create the Phases and Crystal Structures inputs.

The review commit also routes all input checks through one ValidateInputs() function. Preflight and the algorithm both call it, and preflight converts its result with ConvertResultTo. The rest of my earlier comment still applies. The 20 ComputeCAxisReferenceMisalignments tests and the 80 CAxis and ComputeIPFColors tests pass.

[imikejackson]

@joeykleingers I incorporated your suggestions into this PR.