VV: ComputeFaceIPFColor is completely V&V'ed

[imikejackson]

Dependencies

• depends on V&V: WritePoleFigure fully V&V'ed #1647

Summary

Full V&V of ComputeFaceIPFColoringFilter, which fixes the latent mixed-phase mis-coloring bug tracked in #1635 and lands the verification deliverables (report, deviations, provenance). Also bumps EbsdLib to 3.1.0, which is now treated as the canonical IPF-color authority.

Fixes #1635

The fix (deviation D1)

The Phase-2 branch of CalculateFaceIPFColoring::generate indexed m_CrystalStructures[phase1] in both the crystal-symmetry validity guard and the IPF-operator lookup, while correctly reading feature2's Euler angles and the flipped face normal. It therefore applied Phase 1's symmetry operators to Phase 2's orientation. Changed the two indices to phase2 (matching the legacy 6.5.172 backport 1c96b3b8e) and removed the // KNOWN BUG block.

Two manifestations are corrected:

• Mixed Laue groups (cubic on one side, hex on the other): the Phase-2 side was colored with the wrong symmetry — output stayed in the IPF triangle so it looked valid but was wrong.
• feature1-invalid boundary faces (label ≤ 0): the buggy guard read the unknown-phase sentinel and failed, leaving the second color black. This affects even single-phase data.

Verification (Class 1 analytical oracle)

• New test Class 1 Oracle - mixed-phase analytical: a hand-built 4-face cubic/hex mesh whose expected colors are the closed-form IPF standard-triangle corner primaries (cubic <100>→red, <111>→blue; hex c-axis→red, basal→green with red-channel exactly 0). Independent of any DREAM3D/EbsdLib implementation. Verified to fail when the phase1→phase2 fix is reverted.
• Retired the prior Valid filter execution test: it compared against a SurfaceMeshFaceIPFColors array baked into 6_6_Small_IN100_GBCD — the filter's own pre-fix output (a circular oracle that encoded the bug). Real-data exercise is retained by the Color-Key plumbing test, which runs on the full Small IN100 GBCD mesh.

Legacy A/B (three-way: 6.5.171 / 6.5.172 / SIMPLNX)

Run on a legacy-native cubic/hex fixture authored with the legacy_dream3d Python writer, plus SIMPLNX-vs-baked on the real 756,474-face mesh:

• D1 confirmed on real binaries. 6.5.171 reproduces the buggy oracle exactly (mixed-phase face → wrong cubic color; boundary face → black). 6.5.172 and SIMPLNX both apply the hex operator. On the real mesh, SIMPLNX-fixed vs the buggy baseline differs on exactly 120,000 feature1 ≤ 0 boundary faces and nowhere else.
• D2 — new finding (library, resolved). Where both fixed implementations apply the hex operator, EbsdLib (SIMPLNX) colors the hex basal direction green (0,255,0); legacy DREAM3D's older EbsdLib colors it blue (0,0,255). Cubic coloring is identical across all three. EbsdLib is canonical and 3.0.0 and 3.1.0 agree on green (the Class 1 oracle passes unchanged on a from-source 3.1.0 build), so legacy's blue is the deviation — trust SIMPLNX. Migration note: hexagonal IPF hues change vs. legacy DREAM3D; this is expected and correct.

EbsdLib 3.1.0

Bumps the EbsdLib dependency to 3.1.0 (canonical IPF-color reference). The ComputeFaceIPFColoring tests pass identically under EbsdLib 3.0.0 and 3.1.0.

Note: compiling against EbsdLib 3.1.0 also requires the WritePoleFigure API migration (labels → poleFigureNames, etc.), which lives on topic/write_pole_figure_fixes. That change is intentionally not in this PR; it should land first (or be merged together) so develop compiles against 3.1.0.

Deliverables

• src/Plugins/OrientationAnalysis/vv/ComputeFaceIPFColoringFilter.md — V&V report (Status: READY FOR REVIEW)
• src/Plugins/OrientationAnalysis/vv/deviations/ComputeFaceIPFColoringFilter.md — D1 (bug, fixed) + D2 (library, resolved)
• src/Plugins/OrientationAnalysis/vv/provenance/…-circular-oracle.md — documents the retired circular exemplar
• vv_work/face_ipf/ — reproducible legacy/NX pipelines, fixture builder, and the legacy-comparison summary

Test Plan

• ComputeFaceIPFColoring tests pass (in-core build, EbsdLib 3.0.0)
• ComputeFaceIPFColoring tests pass on a from-source EbsdLib 3.1.0 build
• Class 1 analytical oracle verified to fail when the bug is reintroduced
• Legacy three-way A/B run (6.5.171 / 6.5.172 / nxrunner); D1 confirmed, D2 documented
• No regressions in GBCD/IPF/pipeline tests (20 related tests pass)
• CI green once topic/write_pole_figure_fixes is in develop (required for the 3.1.0 build)

Follow-ups (separate issues)

• NX → legacy surface-mesh read gap: DREAM3D-NX writes triangle connectivity as DataArray<size_t>, which legacy DataContainerReader cannot parse, so NX-written surface meshes don't read back in legacy DREAM3D.
• D2 user-facing migration note: hexagonal IPF colors differ between DREAM3D-NX (EbsdLib) and legacy DREAM3D.

[nyoungbq]

All looks good. Was the vv_work directory meant to be left in, if yes I will approve it to go in Tuesday morning otherwise remove. If yes I can also dump what I used for the v&v A/B Fill Bad Data in a directory in my PR too