Skip to content

BUG: Accept rounding in ImageOrientationPatient when ordering series - #7177

Open
hjmjohnson wants to merge 1 commit into
InsightSoftwareConsortium:mainfrom
hjmjohnson:bug-gdcm-ippsorter-dircos-tolerance
Open

hjmjohnson wants to merge 1 commit into
InsightSoftwareConsortium:mainfrom
hjmjohnson:bug-gdcm-ippsorter-dircos-tolerance

Conversation

@hjmjohnson

@hjmjohnson hjmjohnson commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

GDCMSeriesFileNames (since its gdcm::IPPSorter backend, 50dfb13) sorts with IPPSorter's default direction-cosine tolerance of 0, which demands byte-identical ImageOrientationPatient strings. That is more stringent than ITK 5.4.8, whose SerieHelper took the slice normal from the first file and ordered every slice along it. Real GE MR series with independently rounded direction cosines now fail geometric ordering: the read throws, or with FailOnAmbiguousOrdering(false) falls back to Instance Number order and can produce a left-handed volume with reversed slices. This keeps the exact-match sort first and, only when it fails, accepts the series if every slice's unit row and column cosines are within 1 - cos <= 1e-6 (about 0.08 deg) of the first slice's. No release-5.4 backport is needed: 5.4 does not use IPPSorter.

Real data: where this was found

A 155-session clinical stroke MR test set from four vendors, read on current main with the settings dcm-classifier uses (SetUseSeriesDetails(true), FailOnAmbiguousOrdering(false)). Series rejected by IPPSorter only because their IOP strings differ by rounding:

Scanner Series Sessions
GE Genesis Signa 7 2
GE SIGNA Voyager 4 1

All other fallbacks were legitimate (multi-volume series with duplicate positions; localizers and other series with genuinely different planes); no other vendor's series failed this way.

Example (GE Genesis Signa, 2005): five 20-slice axial series, uniform 7.0 mm spacing, no gantry-tilt tag, one frame of reference, three distinct IOP strings per series differing by at most 1.6e-8. ITK 5.4.8: right-handed, ascending. main: IPPSorter fails, GetDidUseAmbiguousOrdering() is true, and the Instance Number fallback yields det(direction) = -1 with the slice axis reversed (physically consistent because of 5fdb32d, but a different voxel order than 5.4.8, which changed downstream CNN results). The new contract test reproduces this rounding pattern; re-reading these clinical series with the fix is still to be done.

Why 1e-6, measured

For small angles 1 - cos(theta) ~ theta^2 / 2, so 1e-6 admits at most 1.4 mrad (0.081 deg): 0.18 mm at 128 mm off-center, below one voxel at clinical MR resolutions (1e-4 would admit 0.81 deg, 1.8 mm).

On the 155-session set, every series with more than one IOP string, worst slice, 1 - n . n0 on unit normals:

Series Count Range
rounding only 11 0 to 4.8e-13
genuinely different orientation 100 7.6e-5 to 2

1e-6 sits more than six orders of magnitude above the largest rounding value and 76x below the smallest genuine difference. The check applies the same bound to the row and the column cosine separately, so an in-plane rotation or a flipped normal is rejected too (a normals-only check would accept the former).

Compared with 5.4.8: equivalent for rounding; stricter for mixed orientations, which 5.4.8 ordered without checking.

Change and tests
  • itkGDCMSeriesFileNames.cxx: SortByPosition(files, 0.0) as before; if it fails, OrientationsAgree() scans ImageOrientationPatient, normalizes each slice's row and column cosines, and requires 1 - r . r0 <= 1e-6 and 1 - c . c0 <= 1e-6; if so, SortByPosition(files, 1e-3) with a fresh IPPSorter. A nonzero IPPSorter tolerance compares unnormalized normals, so a flat 1e-6 there would reject identical six-decimal orientations whose normal's squared length is about 1.2e-6 to 1.5e-6 off one (found by Greptile on the first push); the loose retry only absorbs that length error after ITK has applied the real bound. Gantry-tilt, frame-of-reference, and duplicate-position checks in IPPSorter are unchanged.

  • itkGDCMSeriesFileNamesContractGTest.cxx (orientations derived from the test series' own oblique plane, slices taken in sorted name order):

    • OrientationRoundingStillOrdersGeometrically: alternate slices' IOP off by 1e-8 (the GE pattern) must order geometrically, right-handed.
    • IdenticalUnnormalizedOrientationOrders, RoundedUnnormalizedOrientationOrders: the plane rotated 45 deg in-plane at six decimals (and six vs seven) must order.
    • SlightlyTiltedSliceIsAmbiguous: a 0.5 deg tilt (1 - cos = 3.8e-5, accepted by the loose retry alone) must be rejected.
    • InPlaneRotatedSliceIsAmbiguous: same normal, rows and columns rotated 90 deg, must be rejected.
    • DifferentPlaneSliceIsAmbiguous: a sagittal slice must be rejected.
    • Each rejection test checks both the default throw and, with FailOnAmbiguousOrdering(false), GetDidUseAmbiguousOrdering().
  • Local run (Linux, GCC, Release; ITK main 772f60f with this PR's two files):

    Source Contract tests Failing
    main 13/15 the two rounding tests
    first revision (normals only) 14/15 InPlaneRotatedSliceIsAmbiguous
    this PR all 109 GDCM tests pass none

@github-actions github-actions Bot added type:Bug Inconsistencies or issues which will cause an incorrect result under some or all circumstances type:Testing Ensure that the purpose of a class is met/the results on a wide set of test cases are correct area:IO Issues affecting the IO module labels Nov 16, 2026
@hjmjohnson
hjmjohnson marked this pull request as ready for review November 16, 2026 03:47
@greptile-apps

This comment was marked as resolved.

@hjmjohnson
hjmjohnson force-pushed the bug-gdcm-ippsorter-dircos-tolerance branch from 775aa21 to 6dc3c16 Compare November 16, 2026 03:56
gdcm::IPPSorter's default tolerance of 0 demands byte-identical
ImageOrientationPatient strings, stricter than ITK 5.4's SerieHelper.
GE MR series with per-slice rounded direction cosines then failed
geometric ordering and threw, or fell back to Instance Number order and
could produce a left-handed volume with reversed slices.

Keep the exact-match sort first. When it fails, accept the series if
every slice's unit row and column cosines are within 1e-6 (1 - cos,
about 0.08 degrees) of the first slice's, and sort again with a loose
IPPSorter tolerance, which compares unnormalized normals.
@hjmjohnson
hjmjohnson force-pushed the bug-gdcm-ippsorter-dircos-tolerance branch from 6dc3c16 to 93228d0 Compare November 16, 2026 04:05
@hjmjohnson
hjmjohnson marked this pull request as draft November 16, 2026 04:06
@hjmjohnson
hjmjohnson marked this pull request as ready for review November 16, 2026 04:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:IO Issues affecting the IO module type:Bug Inconsistencies or issues which will cause an incorrect result under some or all circumstances type:Testing Ensure that the purpose of a class is met/the results on a wide set of test cases are correct

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant