[hjmjohnson]

Stop building image iterators over images that have no pixel buffer, which offset a null pointer (undefined behavior that UBSan reports as pointer overflow). Each replacement visits the same indices, or draws the same random indices, in the same order, so results are unchanged. Closes #7039.

Commit	Code path
BUG: Compute scanline neighbor offsets …	ScanlineFilterCommon::SetupLineOffsets (connected-component and label filters)
BUG: Iterate virtual-domain indices …	v4 metric GetValueAndDerivative and joint-histogram threaders; REGULAR sampling in ImageRegistrationMethodv4
ENH: Draw ImageRandomConstIteratorWithIndex positions …	detail::RandomIndexInRegion, the iterator's index draw, usable without an image
BUG: Draw RANDOM metric samples …	RANDOM sampling in ImageRegistrationMethodv4
BUG: Scan the ANTS correlation window …	ANTS neighborhood-correlation threader, dense and sparse
BUG: Sample the scales-estimator virtual domain …	RegistrationParameterScalesEstimator region and random sampling
ENH: Test v4 registration paths …	GoogleTest running every path above

What changed

1. Scanline offsets come from ConnectedImageNeighborhoodShape, which generates the face- or fully-connected offsets without an image, in the same ascending order setConnectivity() / setConnectivityPrevious() produce; the "previous" neighbors are the first half of the symmetric set.
2. Dense threaders and REGULAR sampling read only the index, so they iterate ImageRegionIndexRange over the same region.
3. RANDOM sampling (registration method and scales estimator) calls detail::RandomIndexInRegion, which ImageRandomConstIteratorWithIndex::RandomJump now also calls, with a MersenneTwisterRandomVariateGenerator created and seeded at the same point as the iterator's, so the drawn indices are the same.
4. The ANTS threader scanned with a ConstNeighborhoodIterator. A small protected nested iterator provides what the scan reads (center and neighbor indices, whether a neighbor is inside the buffered region, the window size, the region start) from the region and a Neighborhood of the same radius.
5. Includes of the replaced iterators stay, guarded by !ITK_LEGACY_REMOVE && !ITK_FUTURE_LEGACY_REMOVE, because downstream code relies on them transitively (ANTs' antsAI.cxx uses both region iterators without including them).

Testing

• UBSan: a reproducer covering every path (scanline filter, MeanSquares, JointHistogramMutualInformation, and ANTS metrics, registration with NONE/REGULAR/RANDOM sampling, scales estimator with central-region and random sampling), compiled with -fsanitize=undefined against one ITK build: 16 reports at 13 sites with main's headers, 0 with this branch's, and identical printed values (metric values, derivatives, registration results).
• Local: macOS arm64, conda clang, Release; every commit builds with 0 warnings; the 999 tests labeled ITKCommon, ITKImageLabel, ITKLabelMap, ITKConnectedComponents, ITKMetricsv4, ITKRegistrationMethodsv4, and ITKOptimizersv4 pass; ANTs' antsAI.cxx compiles against these headers with ITK_LEGACY_REMOVE; the new GoogleTest also compiles with ITK_LEGACY_REMOVE; pre-commit run --all-files passes.
• Downstream forest (ITK with every default module and Python wrapping, consumers built against it), with this PR and BUG: Invert scaled and skewed versor transforms without throwing #7056 merged (BRAINSTools needs BUG: Invert scaled and skewed versor transforms without throwing #7056 to pass on main): ANTs builds and passes 179/179, BRAINSTools builds and passes 458/458. An earlier run caught ANTs relying on the iterator includes, which is why they stay.

AI assistance (Claude Code) found the defect with a UBSan build of BRAINSTools, wrote the reproducer and the changes, and ran the tests; the author reviewed every line.

[dzenanz]

This partly duplicates code. I guess it is unavoidable.

[hjmjohnson]

Two force-pushes: 4227060c8d6...3d537d24fb5 is a plain rebase on main (patches unchanged); 3d537d24fb5...bb6cb8e6142 is the content. The second removes the duplicated connectivity code (ConnectedImageNeighborhoodShape now supplies the scanline offsets), covers two more paths that iterated the unallocated virtual image (the ANTS neighborhood-correlation threader and RegistrationParameterScalesEstimator), splits RANDOM sampling into its own commit, and adds a GoogleTest. ANTs and BRAINSTools build and pass all their tests with it (and #7056).

[hjmjohnson]

@dzenanz The duplication is gone: the scanline offsets now come from ConnectedImageNeighborhoodShape, which generates the same connected offsets in the same order without an image. What remains is RANDOM sampling repeating the iterator's few-line random draw, which uses ImageRegion::ComputeOffsetTable and ImageHelper::ComputeIndex for the index mapping.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes reach registration metrics, optimizers, and image-label filtering.

The PR appears safe to merge, with a non-blocking improvement to random-sampling tests.

Findings

1.  Wrong samples can pass ▶

Summary

Replaces pixel-buffer iterators with index-only traversal where images have no allocated pixels.

• Scanline filters get neighbor offsets directly from the connectivity shape.
• Registration metrics process virtual grids without reading virtual pixels.
• Registration sampling selects virtual-domain points without pixel iterators.
• Scale estimation samples virtual domains without pixel iterators.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  R[Image region without allocated pixels] --> D[Dense traversal]
  R --> S[Random sampling]
  R --> N[Neighborhood traversal]
  D --> I[ImageRegionIndexRange]
  S --> G[Random position]
  G --> C[ImageHelper ComputeIndex]
  N --> O[Region bounds and neighborhood offsets]
  I --> P[Indices and physical points]
  C --> P
  O --> P

Loading

_{Reviews (1) · Last reviewed commit: "ENH: Test v4 registration paths that vis..." · Reviewed by Greptile}

[hjmjohnson]

Two force-pushes: bb6cb8e6142...e3839839b42 is content only (a one-line comment on the ANTS scan iterator, a corrected one-line test comment, commit bodies wrapped at 72 columns); e3839839b42...2ea9e4c877d is a plain rebase on main (patches unchanged).

[hjmjohnson]

Force-push 2ea9e4c877d → e9644689f25 is content only (same base, ffda1aac7d0). It applies the three remaining review suggestions:

• the iterator includes kept for downstream code are now guarded by !ITK_LEGACY_REMOVE && !ITK_FUTURE_LEGACY_REMOVE instead of carrying a comment;
• the ANTS threader's nested VirtualNeighborhoodScanIterator and ScanIteratorType are protected;
• a new commit moves the random iterator's index draw into detail::RandomIndexInRegion, which RandomJump, RANDOM registration sampling, and the scales estimator now share.

Testing

Every commit builds with 0 warnings; 999 tests (ITKCommon plus the six affected modules) pass; ANTs' antsAI.cxx still compiles against these headers with ITK_LEGACY_REMOVE; pre-commit run --all-files passes.