Repository navigation
BUG: Validate morphology kernel radii and bound equalization loops - #1947
Conversation
There was a problem hiding this comment.
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-indexedstd::arraydiagnostics. Use names such assignedXandsignedY, 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
left a comment
There was a problem hiding this comment.
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.
|
/azp run |
|
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. |
e5a2bf8 to
f35b519
Compare
|
/azp run |
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>
f35b519 to
54424d4
Compare
|
/azp run |
|
Azure Pipelines: Successfully started running 1 pipeline(s). |
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>
* 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>
Summary
Sixteen ImageProcessing morphology filters now reject a Kernel Radius that the code cannot represent, in preflight, instead of narrowing it to
int32and 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 inMakeStructuringElement().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.src/Plugins/ImageProcessing/src/ImageProcessing/Filters/and their documentation pages.Kernel Radius is a
UInt32vector that preflight did not check. Execute cast each component toint32, 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: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.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 usesint64loops 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..rbox and skipped the neighbors outside the image, so a radius nearUINT32_MAXcost 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 linearuint8paths already bounded their traversal and are unchanged.3. Coding knowledge base
docs/Coding_Knowledge_Base.mdNew 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_indexand 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:
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#1AdaptiveHistogramEqualizationImageFilter#1(traversal workload)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
UINT32_MAXor 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.DREAM3DNX_ENABLE_OOC=ON,SIMPLNX_TEST_ALGORITHM_PATH=1) on macOS: 258/258.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) andHDF5ChunkedStore 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.Related Issue
Related to #1873