Skip to content

BUG: Validate morphology kernel radii and bound equalization loops - #1947

Merged
imikejackson merged 6 commits into
BlueQuartzSoftware:developfrom
joeykleingers:bug/c14-morphology-and-equalization
Nov 13, 2026
Merged

imikejackson merged 6 commits into
BlueQuartzSoftware:developfrom
joeykleingers:bug/c14-morphology-and-equalization

Conversation

@joeykleingers

@joeykleingers joeykleingers commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Sixteen ImageProcessing morphology filters now reject a Kernel Radius that the code cannot represent, in preflight, instead of narrowing it to int32 and running with an empty or corrupt structuring element. Adaptive Histogram Equalization now clips each neighbor loop to the image, so a very large Radius no longer makes the filter run for hours while producing the same output. The simplnx coding knowledge base gains one rule for NaN and infinity, decided by where the value comes from, and two extensions that record the lessons of these fixes. 61 files changed, +2264 / −161 lines.

1. Kernel Radius validation in 16 morphology filters

  • src/simplnx/Utilities/ImageProcessing/StructuringElement.hpp — ValidateKernelRadius(), MakeCheckedStructuringElement() and safe signed arithmetic in MakeStructuringElement().
  • src/simplnx/Utilities/ImageProcessing/MorphologyEngine.hpp — ValidateMorphologyLayout(), the flat-offset eligibility check and the packed-word end clamp.
  • src/simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp — layout checks with the Image Geometry path at every morphology execution entry point.
  • src/simplnx/Utilities/ImageProcessing/ObjectMorphologyEngine.hpp — layout checks before object-morphology scratch allocation.
  • The 16 filters in src/Plugins/ImageProcessing/src/ImageProcessing/Filters/ and their documentation pages.

Kernel Radius is a UInt32 vector that preflight did not check. Execute cast each component to int32, so a radius of 2147483648 or more became negative; the structuring element was empty and the filter copied its input, or wrote zeros for the top-hats and the gradient. Large radii also overflowed the element count, the Safe Border padded size and the signed coordinate arithmetic.

Each filter now validates the radius in preflight and builds its structuring element through MakeCheckedStructuringElement() in execute. Preflight is the one place the radius is checked; the structuring-element and layout helpers document a validated radius as a precondition:

  • Each radius component must be at most 2147483646 cells (the largest value whose adjacent offset still fits int32), and the element count (2X+1)(2Y+1)(2Z+1) must fit the offset vector. There is no workload or memory cap; a representable radius larger than the image remains valid.
  • ValidateMorphologyLayout() checks the Safe Border padded extents and the signed coordinate, plane, volume and byte counts derived from the image dimensions and the radius, before any kernel construction or scratch allocation. Preflight, each filter's execute and each shared execution entry point call it, and every layout error names the selected Image Geometry.
  • An allocation failure while building a representable element is returned as an error instead of an exception.
  • The flat-offset fold is used only when its offsets and staged indices fit int64; otherwise the coordinate-based path runs. The packed binary word end is clamped without overflow.
  • MakeStructuringElement() returns an empty element for a negative radius before any negation and uses int64 loops and shell arithmetic.

New error codes -88000 to -88009 identify the radius length, range, element count, capacity, construction failure and the five layout conditions. Output for every previously valid radius is unchanged.

Affected filters: Binary Dilate, Binary Erode, Binary Morphological Closing, Binary Morphological Opening, Binary Opening By Reconstruction, Black Top Hat, Closing By Reconstruction, Dilate Object Morphology, Erode Object Morphology, Grayscale Dilate, Grayscale Erode, Grayscale Morphological Closing, Grayscale Morphological Opening, Morphological Gradient, Opening By Reconstruction and White Top Hat.

2. Adaptive Histogram Equalization neighbor traversal

  • src/simplnx/Utilities/ImageProcessing/AdaptiveHistogramEqualizationEngine.hpp — clipped loop bounds in the generic and lookup-table plane bodies and 2D block bodies.

Each neighbor loop walked the whole -r..r box and skipped the neighbors outside the image, so a radius near UINT32_MAX cost billions of empty iterations per voxel. The four loop nests now intersect the radius window with the image bounds, using signed arithmetic, before iterating. The skipped iterations are exactly the ones that were skipped before, in the same order, so the accumulated sum, the in-bounds count and every output value are unchanged. The linear uint8 paths already bounded their traversal and are unchanged.

3. Coding knowledge base

  • docs/Coding_Knowledge_Base.md

  • New entry Decide NaN and infinity handling by where the value comes from, which replaces "Let the user choose whether a NaN input value is an error or is skipped". Parameters reject NaN and reject infinity unless the filter documents a meaning for it; values stored into floating-point arrays may be NaN or infinity; file readers reject nonfinite values where the format requires finite ones; input array values that reach a comparison, range, histogram, threshold, color map, search, index or integer conversion get a Nonfinite Input Handling choice (Error by default, or Warn and Continue); element-wise floating-point math passes IEEE results through and documents them; an undefined result for degenerate input is a documented NaN. The choice name, its key nonfinite_input_handling_index and its two values follow BUG: Fix selected ImageProcessing numeric conversions and ranges #1888.

  • Write floating-point output through a saturating cast: a computed NaN or infinity for an integer output is now an error that names the index and output type, and clipping finite values reports a warning, instead of NaN becoming 0.

  • Validate every parameter value in preflight: validate derived representations (widths, signed limits, padded extents, element and byte counts), check an index against every domain it selects with index < count, avoid rounded floating-point maxima for integer bounds, check relations after conversion, and normalize directions with arithmetic that cannot overflow for finite values.

  • Check for cancel in every long loop: clip a neighborhood traversal to the contributing domain before iterating, unless the omitted positions contribute clamped boundary samples.

Family entries fixed

This pull request fixes these entries of #1873; the issue stays open for the other parameter classes:

Entry Fix
WhiteTopHatImageFilter#1, BinaryDilateImageFilter#2, BinaryErodeImageFilter#1, BinaryMorphologicalClosingImageFilter#1, BinaryMorphologicalOpeningImageFilter#1, DilateObjectMorphologyImageFilter#1, ErodeObjectMorphologyImageFilter#1, GrayscaleDilateImageFilter#1, GrayscaleErodeImageFilter#1, GrayscaleMorphologicalClosingImageFilter#1, GrayscaleMorphologicalOpeningImageFilter#1, MorphologicalGradientImageFilter#1, OpeningByReconstructionImageFilter#1 Kernel Radius validation (section 1)
Kernel Radius entries for BlackTopHatImageFilter, ClosingByReconstructionImageFilter and BinaryOpeningByReconstructionImageFilter Kernel Radius validation (section 1)
AdaptiveHistogramEqualizationImageFilter#1 (traversal workload) Clipped traversal (section 2)

Not part of this pull request: the foreground/background relation in BinaryOpeningByReconstructionImageFilter (#1867), cancellation polling in these loops (#1876), the Alpha and Beta values of Adaptive Histogram Equalization (a later #1873 pull request) and the ComputeNeighborhoods traversal (#1908).

Test plan

  • New tests reproduce each defect on unmodified develop and pass with the fix: a radius of UINT32_MAX or 2147483647 is accepted by preflight and crashes or yields an empty element before the fix, and is rejected with a code that names the axis and value after it; the last valid radius 2147483646 passes preflight; direct validator and builder tests cover each error code, an injected allocation failure, the layout limits (with metadata only, no large allocation), the flat-offset fallback and ordered offsets for Box, Cross, Ball and Annulus elements against hand-derived lists; the Adaptive Histogram Equalization huge-radius cases time out at 60 s before the fix and match the clipped-window result exactly after it, and exact comparisons against an unclipped reference traversal cover all four loop bodies.
  • Affected tests, in-core Release: 236/236 on Linux (Ubuntu 24.04), Windows 11 and macOS.
  • Affected tests, out-of-core Release (DREAM3DNX_ENABLE_OOC=ON, SIMPLNX_TEST_ALGORITHM_PATH=1) on macOS: 258/258.
  • Full out-of-core suite on macOS, ctest -L "^ooc$" -LE benchmark: 713/716. The three failures also fail on develop and are fixed in other open pull requests: ReadH5OimDataFilter: Multi Scan actual OOC output parity (BlueQuartzSoftware/SimplnxOoc#23), OrientationAnalysisOocStoreContracts (the ReadH5OinaData fixture, TEST: Add test profile isolation and shared Catch runners #1930) and HDF5ChunkedStore deferred zero fill (BlueQuartzSoftware/SimplnxOoc#26). The run used SimplnxOoc at the head of BlueQuartzSoftware/SimplnxOoc#34 so that develop's feature-phases fixture compiles.
  • CI passes.

Related Issue

Related to #1873

@joeykleingers joeykleingers added the bug Something isn't working label Nov 9, 2026
@joeykleingers joeykleingers self-assigned this Nov 9, 2026

@jmarquisbq jmarquisbq 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.

Reviewed all 61 changed files at commit 0251f345566628a31c1ad5169ad368fcc52bcc4d against develop at aacedb4dc5c009d21045d715ac8f09a0d213d42e.

Please address the following before merge.

  • [Minor, CONFIRMED] Restore the nonfinite skip rule for reductions and neighborhoods.
    File: docs/Coding_Knowledge_Base.md:693-695.
    The new Warn and Continue policy specifies finite ranges and per-element replacement results. It removes the previous explicit skip rule for reductions and neighborhoods. For a mean over {NaN, 1, 3}, the contributing values and denominator must be clear. Add: "For reductions and neighborhood operations, exclude nonfinite values from the contributing samples and counts." Keep the documented replacement-output rule for per-element decisions.

  • [Nit, CONFIRMED] Resolve the static-analysis diagnostics introduced by the new code.
    Files: AdaptiveHistogramEqualizationEngine.hpp:704-705, also lines 776-777; MorphologyEngine.hpp:91-95 and the new guard helpers.
    A scoped clang-tidy 19.1.5 run with the repository configuration fails on new identifier-length, local-constant naming, and variable-indexed std::array diagnostics. Use names such as signedX and signedY, camelCase local constants, and checked array access. Rerun the configured checks on the changed code. Some diagnostics on edited lines concern pre-existing names or safe conversions; do not expand this cleanup to unrelated code.

The runtime architecture preserves the existing algorithm dispatch, storage access, and working-memory arrangements. The shared validators and the allocation-failure seam introduce no new global state. The clipped equalization bounds preserve the order of contributing neighbors.

The broader floating-output and degenerate-input policies need an explicit compatibility decision. Future implementations can change output array types and failure behavior under these rules. Separate these policies for focused review, or document their compatibility scope before adopting them as repository-wide requirements.

Validation performed for this head:

  • All 43 changed C++ files pass clang-format 19.1.1 with the repository-root style.
  • An isolated MSVC 19.44 probe passes through serial CTest in Release and Debug, with one test in each configuration. It covers kernel limits, checked construction failure, Safe Border overflow, flat-fold fallback, packed endpoints, and huge-radius execution in all four changed equalization bodies.
  • Clang-tidy covers changed header lines reachable through that probe. It is not a full translation-unit or template-instantiation analysis of the PR.
  • The comment audit ran on all 43 changed C++ files. Its one changed-line diagnostic is a false positive on a constant.
  • The full affected-filter suites, real out-of-core execution, and other platforms were not rerun. The test counts in the PR description were not independently reproduced.

No Critical or Important runtime defect was found in the reviewed source. That result does not establish full runtime validation.

REQUEST CHANGES — clarify the numerical policy and resolve the new-code static-analysis diagnostics before merge.

@jmarquisbq jmarquisbq 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.

Reviewed all 61 changed files against develop at e5a2bf8.

No actionable in-scope findings. The architecture pass found no current architectural problems or actionable future risks. Public filter execution validates the radius through preflight before kernel construction. The equalization bounds preserve contributing samples and accumulation order.

Validation:

  • Focused C++20 header probes passed in Release and Debug. They cover radius limits, allocation failures, layout overflow, flat-offset fallback, packed endpoints, and all four large-radius equalization bodies.
  • Clang-format 19.1.1 passed on all 43 changed C++ files.
  • Scoped clang-tidy exited nonzero with 24 diagnostics. Manual inspection found inherited naming/style warnings and safe bounded conversions. Coverage was limited to the probe translation unit.
  • Documentation checks found no actionable issues.

Full filter suites, real out-of-core execution, sanitizers, and broader Debug coverage remain unverified in this review. GitHub reports no checks for this head. Earlier CI results cover 45f8cfa.

APPROVE within the reviewed scope, with these validation limits.

@joeykleingers

Copy link
Copy Markdown
Contributor Author

/azp run

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

@joeykleingers
joeykleingers force-pushed the bug/c14-morphology-and-equalization branch from e5a2bf8 to f35b519 Compare November 12, 2026 18:56
@joeykleingers

Copy link
Copy Markdown
Contributor Author

/azp run

joeykleingers and others added 6 commits November 12, 2026 19:02
Kernel Radius is a UInt32 vector that preflight never checked. Execute
narrowed each component to int32, so a radius of 2147483648 or more
became negative, the structuring element came out empty and the filter
copied its input (top-hats and the gradient wrote zeros). Large radii
also overflowed the element-count and Safe Border size arithmetic.

- Add ValidateKernelRadius() and MakeCheckedStructuringElement() to
  StructuringElement.hpp: each radius must be at most 2147483646 and
  the element count must fit the offset vector. Allocation failures are
  returned as errors.
- Add ValidateMorphologyLayout() to MorphologyEngine.hpp. It checks the
  Safe Border padded extents and the signed coordinate, plane, volume
  and byte counts derived from the image and the radius. Preflight and
  every execution entry point call it before allocating.
- Use the flat-offset fold only when its offsets and staged indices fit
  int64, and clamp the packed binary word end without overflow.
- Negative radii in MakeStructuringElement() return an empty element
  before any negation, and its loops and shell arithmetic use int64.

Fixed filters: BinaryDilateImageFilter, BinaryErodeImageFilter,
BinaryMorphologicalClosingImageFilter,
BinaryMorphologicalOpeningImageFilter,
BinaryOpeningByReconstructionImageFilter, BlackTopHatImageFilter,
ClosingByReconstructionImageFilter, DilateObjectMorphologyImageFilter,
ErodeObjectMorphologyImageFilter, GrayscaleDilateImageFilter,
GrayscaleErodeImageFilter, GrayscaleMorphologicalClosingImageFilter,
GrayscaleMorphologicalOpeningImageFilter,
MorphologicalGradientImageFilter, OpeningByReconstructionImageFilter,
WhiteTopHatImageFilter.

Part of BlueQuartzSoftware#1873.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
Replace the knowledge-base entry that let the user choose only how a
NaN input value is handled with one rule for NaN and both infinities,
decided by where the value comes from. It follows the handling in
BlueQuartzSoftware#1888:

- Parameters: preflight rejects NaN, and rejects infinity unless the
  filter documentation gives it a meaning. Values stored into a
  floating-point array may be NaN or infinity.
- Values read from a file: the reader rejects nonfinite values where
  the format requires finite ones.
- Input array values that reach a comparison, range, histogram,
  threshold, color map, search, index or integer conversion: a
  Nonfinite Input Handling choice, Error (default) or Warn and
  Continue.
- Element-wise floating-point math passes IEEE results through and
  documents them.
- A computed nonfinite value for an integer output is an error naming
  the index and output type; finite out-of-range values are clipped
  with a warning, instead of NaN becoming 0.
- An undefined result for degenerate input is a documented NaN.

Update the saturating-cast and parameter-validation entries to match.

Part of BlueQuartzSoftware#1873.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
The Radius of AdaptiveHistogramEqualizationImageFilter is a UInt32
vector, and every neighbor loop walked the whole -r..r box and skipped
the neighbors outside the image. A radius near UINT32_MAX made each
voxel run billions of empty iterations, so the filter did not finish.

Each of the four neighbor loops (the generic and lookup-table plane
bodies and the generic and lookup-table 2D block bodies) now computes
its bounds clipped to the image before it iterates. The skipped
iterations are exactly the ones that were skipped before, in the same
order, so the accumulated sum, the in-bounds count and every output
value are unchanged. The linear uint8 paths already bounded their
traversal and are unchanged.

Part of BlueQuartzSoftware#1873.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
- Coding knowledge base: Warn and Continue excludes nonfinite values
  from the contributing samples and counts of reductions and
  neighborhood operations. The nonfinite-handling rules apply to new
  filters and to filters a change already fixes; bringing an existing
  filter's output type or failure behavior in line is a breaking change
  that its pull request names.
- Adaptive histogram equalization: rename the signed coordinates xi
  and yi to signedX and signedY.
- Morphology and structuring-element guards: camelCase local
  constants, checked std::array access, a kernel parameter name in the
  two new layout helpers, an explicit int64 slice product and
  parentheses in the bounding-box extents.

No behavior change.
Filter preflight is the one place a filter's inputs are checked; the
shared morphology helpers do not repeat those checks.

- MakeCheckedStructuringElement() and ValidateMorphologyLayout() no
  longer re-run ValidateKernelRadius(); they document a validated radius
  as a precondition. The structuring element still converts allocation
  failures to an error, and the layout checks on the final geometry
  dimensions still run in preflight and execute.
- The kernel-radius tests also execute each filter with an invalid
  radius and check that it fails with the preflight code, creates no
  output and leaves the input unchanged. The test that called the
  helper directly with an invalid radius is removed.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>
@imikejackson
imikejackson force-pushed the bug/c14-morphology-and-equalization branch from f35b519 to 54424d4 Compare November 13, 2026 00:10
@imikejackson

Copy link
Copy Markdown
Contributor

/azp run

@imikejackson
imikejackson enabled auto-merge (squash) November 13, 2026 00:10
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 1 pipeline(s).

@imikejackson
imikejackson merged commit 0cd2009 into BlueQuartzSoftware:develop Nov 13, 2026
5 checks passed
@imikejackson
imikejackson deleted the bug/c14-morphology-and-equalization branch November 13, 2026 02:09
imikejackson added a commit to joeykleingers/simplnx that referenced this pull request Nov 13, 2026
PR BlueQuartzSoftware#1947 added ValidateMorphologyLayout preflight checks to the morphology filters. They reached it through ImageProcessingFilterUtilities.hpp, which no longer includes MorphologyEngine.hpp. Move the two overloads and their error codes, unchanged, into MorphologyLayout.hpp so the filters can include them without the morphology engine.

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>
imikejackson added a commit that referenced this pull request Nov 13, 2026
* COMP: Compile each ImageProcessing filter executor once

The NXImageProcessing filters included one 5,891-line header that held
all of the executor templates and 23 engine headers. Each filter
compiled again the executor code that it shared with other filters.
For example, five morphology filters each compiled the same 2.3 MB of
machine code. This change gives each executor family one translation
unit in the NXImageProcessing plugin.

* Move the 30 executors that use only their default type set to
  exported functions in NXImageProcessing/utils/ImageFilterExecutors.hpp
  with one .cpp file for each engine family.
* Move the 7 executors whose template arguments change with the caller
  to NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp.
* Move the helpers that more than one family or a test uses to
  NXImageProcessing/utils/ImageFilterExecutorDetail.hpp.
* Move MorphOp, ObjectMorphOp, ReconstructOp and RegionalExtremaOp to
  the new ImageProcessingOperationTypes.hpp. The engine headers include
  it, so their users see the same enums.
* Keep only the shared preflight helpers, input checks and type-set
  policies in ImageProcessingFilterUtilities.hpp (770 lines).
* Add ImageFilterExecutorsLinkTest, which references each exported
  executor, so a missing export fails the link on every platform.
* Remove StreamBinaryThreshold, which had no caller.

The executor bodies, type sets, error codes and messages do not change.

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>

* DOC: Point test comments at the new SafeBorderPadRadius location

SafeBorderPadRadius moved to NXImageProcessing/utils/ImageFilterExecutorDetail.hpp.

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>

* COMP: Move morphology layout checks into a small header

PR #1947 added ValidateMorphologyLayout preflight checks to the morphology filters. They reached it through ImageProcessingFilterUtilities.hpp, which no longer includes MorphologyEngine.hpp. Move the two overloads and their error codes, unchanged, into MorphologyLayout.hpp so the filters can include them without the morphology engine.

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>

---------

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>
Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>
Co-authored-by: Michael Jackson <mike.jackson@bluequartz.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants