diff --git a/CMakeLists.txt b/CMakeLists.txt index ab3dbf3cbd..8f6ed30c95 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -414,6 +414,7 @@ set(SIMPLNX_HDRS ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/CoreDataIOManager.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/DataIOCollection.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/IExternalSort.hpp + ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/ITemporaryRecordStore.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/IDataFactory.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/IDataIOManager.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IO/Generic/IDataStoreFormatResolver.hpp @@ -507,6 +508,7 @@ set(SIMPLNX_HDRS ${SIMPLNX_SOURCE_DIR}/DataStructure/IArray.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IDataArray.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IDataStore.hpp + ${SIMPLNX_SOURCE_DIR}/DataStructure/IDataStoreWritePreparation.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/IListStore.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/INeighborList.hpp ${SIMPLNX_SOURCE_DIR}/DataStructure/LinkedPath.hpp @@ -603,8 +605,18 @@ set(SIMPLNX_HDRS ${SIMPLNX_SOURCE_DIR}/Utilities/MemoryUtilities.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/CacheMemoryBudgetManager.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ColorToGrayScale.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ConnectedComponentEngine.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/HistogramEngine.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ImageGeometryCrop.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ImageGeometryResample.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ImageProcessingOperationTypes.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ImageTransferResult.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/OtsuImageEngine.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/PointwiseEngine.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/StreamingStatistics.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/SweepTemporaryStore.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/TerminalImageConversion.hpp + ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ThresholdMaximumConnectedComponentsEngine.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/WorkingMemory.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ProgressEstimator.hpp ${SIMPLNX_SOURCE_DIR}/Utilities/ThrottledMessageHandler.hpp @@ -764,6 +776,7 @@ set(SIMPLNX_SRCS ${SIMPLNX_SOURCE_DIR}/DataStructure/DataStructureGraphViz.cpp ${SIMPLNX_SOURCE_DIR}/DataStructure/DataStructureJson.cpp ${SIMPLNX_SOURCE_DIR}/DataStructure/DataStructureText.cpp + ${SIMPLNX_SOURCE_DIR}/DataStructure/IDataStoreWritePreparation.cpp ${SIMPLNX_SOURCE_DIR}/DataStructure/INeighborList.cpp ${SIMPLNX_SOURCE_DIR}/DataStructure/LinkedPath.cpp ${SIMPLNX_SOURCE_DIR}/DataStructure/Metadata.cpp @@ -1175,6 +1188,7 @@ if(SIMPLNX_ENABLE_PACKAGING) endif() if(SIMPLNX_BUILD_TESTS) + target_sources(simplnx PRIVATE "${SIMPLNX_SOURCE_DIR}/Utilities/ImageProcessing/ConnectedComponentPolicyObserver.cpp") target_compile_definitions(simplnx PUBLIC "SIMPLNX_BUILD_TESTS=1") add_subdirectory(test) endif() diff --git a/docs/Coding_Knowledge_Base.md b/docs/Coding_Knowledge_Base.md index 3174a7a8ac..102e353648 100644 --- a/docs/Coding_Knowledge_Base.md +++ b/docs/Coding_Knowledge_Base.md @@ -746,11 +746,20 @@ Reset a prior fixed notation explicitly with `std::defaultfloat`. For printf, us ### Write floating-point output through a saturating cast -**Rule:** a filter whose output type can be an integer type (for example an output type that follows the input type) -writes each computed finite floating-point value through `ImageProcessing::detail::SaturateCastFromDouble()`, which -clamps it to the range of `U`, and reports one warning with the number of clipped values. A NaN or an infinity computed -for an integer output is an error that names the value's index and the output type; it is never written as 0. The -general rule is in the numeric-correctness reference of `cpp-best-practices`. +**Rule:** select the conversion helper that matches the algorithm's output and diagnostic requirements. + +- Use `ImageProcessing::detail::ConvertTerminalImageValue` when a filter must report clipping or reject nonfinite + integer output. Finite integer conversions truncate toward zero, then clip if the integer is out of range. The + result status identifies clipping. A nonfinite value for an integer output returns `NonFinite` and leaves the + destination untouched. A floating output can retain NaN and infinity. Report one clipping warning with the + total number clipped. For a nonfinite integer result, report one error with the total rejected and the output + path and type. Include the flat index only when exactly one result was rejected. If a transfer failure or + cancellation interrupts conversion, identify any reported counts as partial. +- Use `ImageProcessing::detail::SaturateCastFromDouble()` for intentional clamping when only the converted value + is needed. For an integer destination, NaN maps to zero and the infinities map to the native bounds. Apply these + mappings only when the caller's nonfinite policy permits them. A converted value alone cannot identify clipping. + +See the numeric-correctness reference of `cpp-best-practices`. **Example of the broken rule:** `ExpImageFilter` casts `exp(double(value))` straight to the integer output, and `LogImageFilter`, `SquareImageFilter` and `TanImageFilter` do the same: `log(0)`, the `uint8` square of 16 and the @@ -760,9 +769,9 @@ general rule is in the numeric-correctness reference of `cpp-best-practices`. **What to look for:** `static_cast(floatingExpression)` where `U` can be integral. -**Pattern to use:** `SaturateCastFromDouble()` in -`simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp` for finite values; the nonfinite integer-output -error and the clipping warning of `SmoothingRecursiveGaussianImageFilter` and `CurvatureFlowImageFilter` (PR #1888). +**Pattern to use:** Curvature Flow and Smoothing Recursive Gaussian use `ConvertTerminalImageValue` for the +final conversion (PR #1888). They report one warning if clipping occurred and return an error for a nonfinite +integer result. Intensity Windowing uses `SaturateCastFromDouble` to clamp values to the destination type. ### Decide NaN and infinity handling by where the value comes from @@ -773,23 +782,13 @@ error and the clipping warning of `SmoothingRecursiveGaussianImageFilter` and `C to store in a floating-point array (a fill value or a replacement value) may be NaN or infinity. - **Values read from a file:** the reader rejects a nonfinite value where the format requires a finite one, with an error that names the file and the field. -- **Input array values** that would change a result other than their own element's output, or would reach a - comparison, an ordering, a range, a histogram, a threshold, a color map, a search, an index or an integer conversion. - This covers reductions (sums, means, standard deviations, extrema and data ranges, histograms, medians, modes and - unique-value counts, per feature or per region), neighborhood operations on floating-point data (smoothing, median and - gradient filters, morphology) and decisions made from a value (thresholds, segmentation tolerances, bin and index - selection). The filter has a choice parameter **Nonfinite Input Handling** (key - `nonfinite_input_handling_index`) with two choices, **Error** (the default) and **Warn and Continue**. - - **Error** stops at the first nonfinite value, before any output is written. The message names the array and the - tuple and says that **Warn and Continue** handles these values instead. - - **Warn and Continue** computes ranges and bounds from finite values only, gives each nonfinite element the result - that the filter documentation states (for example "first bin" or "Outside Value"), and reports one warning with - the number of nonfinite values. For reductions and neighborhood operations, exclude nonfinite values from the - contributing samples and counts. - - The in-core and out-of-core algorithms use one shared test and rule. The parameter has no effect on integer arrays. -- **Element-wise floating-point math**, where one element in gives the same element out and no other element changes, - lets the IEEE result pass through. The filter documentation lists what NaN, infinity, zero and out-of-domain inputs - produce. When integer input can produce a fraction or NaN, the output type is floating point. +- **Floating-point input arrays.** The caller is responsible for supplying data suitable for the filter. Do not add a + parameter, validation pass, warning or error solely to detect or report NaN or infinity in the user's array. + Keep the checks required to compute valid indices and perform safe conversions. When an algorithm needs a finite + range, use finite samples in its existing range calculation and handle the case where none are available. + Apply the same arithmetic on in-memory and out-of-core paths. +- **Element-wise floating-point results.** Element-wise math can produce an IEEE result such as NaN from the square + root of a finite negative value. When integer input can produce a fraction or NaN, the output type is floating point. - **A computed value written to an integer output:** see [Write floating-point output through a saturating cast](#write-floating-point-output-through-a-saturating-cast). - **A result that is undefined for degenerate input** (a zero-length vector, an all-zero quaternion) is NaN in a @@ -806,23 +805,29 @@ Histogram** groups values with the same equality test, and the shared statistics and `HistogramUtilities.hpp` sort and key floating-point values with `operator<`. `ComputeArrayMinMax` is not NaN-aware (issue #1874). **Invert Intensity Image** accepts a NaN **Maximum** and writes 0 to every integer pixel (issue #1873). -**Why:** every comparison with NaN is false. `operator<` is then not a strict weak ordering, so `std::sort`, -`std::stable_sort` and `std::map` keys are undefined; a threshold or a bin search puts NaN on one side without saying -so; an equality test written as "neither is less than the other" groups NaN with every value; and a cast of NaN or an -infinity to an integer is undefined behavior. Whether a nonfinite input value means "bad data" or "no measurement" -depends on the user's data, so input array values get a choice; parameters and file values do not. +**Why:** ordered comparisons with NaN are false. A minimum and maximum seeded with NaN can therefore stay NaN +even when the rest of the image is finite. Sorting a mixture of NaNs and finite values with ordinary less-than +comparisons can violate the ordering the sort requires. Converting NaN or infinity to an integer is undefined +behavior. Guard these operations where they occur. **What to look for:** - `std::sort`, `std::stable_sort`, `std::map`, `std::set` or `std::unique` over floating-point input values; - an equivalence written as `!(a < b) && !(b < a)` on floating-point values; -- a running minimum, maximum or sum over input values with no finiteness test; +- a finite range seeded from the first pixel when that pixel can be NaN; - a threshold, tolerance or bin index computed from an input value with no finiteness test; - a parameter check written as `value < 0` or `value <= 0`, which NaN passes. -**Pattern to use:** **Nonfinite Input Handling** in `ThresholdMaximumConnectedComponentsImageFilter` and -`WriteImageFilter` (PR #1888); the Upper Boundary of `ThresholdMaximumConnectedComponentsImageFilter` for a documented -meaning of infinity (PR #1888). +**Pattern to use (issue #1874):** + +- Otsu Multiple Thresholds fits the histogram using finite, mask-selected samples. Test the labels of the finite + samples with a NaN first and with it later. The filter makes no guarantee about the label of a nonfinite input. +- Threshold Maximum Connected Components uses finite intensities for its search bounds and assigns Outside Value to + nonfinite pixels. If no finite samples exist, fill with Outside Value. Upper Boundary is a filter parameter with + documented meanings for positive and negative infinity. +- Write Image preserves raw floating-point pixels. In color-table mode, finite values establish the palette range. + Masked pixels use the mask color. Unmasked nonfinite pixels use the first palette color, including when there are + no finite samples. ### Copy every field that sets behavior when you clone an object diff --git a/src/Plugins/NXImageProcessing/CMakeLists.txt b/src/Plugins/NXImageProcessing/CMakeLists.txt index 90c6f8bb2d..7bef20a849 100644 --- a/src/Plugins/NXImageProcessing/CMakeLists.txt +++ b/src/Plugins/NXImageProcessing/CMakeLists.txt @@ -130,6 +130,8 @@ if(MSVC) endif() set(PLUGIN_EXTRA_SOURCES + "${${PLUGIN_NAME}_SOURCE_DIR}/src/${PLUGIN_NAME}/Filters/Algorithms/WriteImageColorUtilities.hpp" + "${${PLUGIN_NAME}_SOURCE_DIR}/src/${PLUGIN_NAME}/utils/MathOutputUtilities.hpp" "${${PLUGIN_NAME}_SOURCE_DIR}/src/${PLUGIN_NAME}/utils/ImageFilterExecutors.hpp" "${${PLUGIN_NAME}_SOURCE_DIR}/src/${PLUGIN_NAME}/utils/ImageFilterTemplateExecutors.hpp" "${${PLUGIN_NAME}_SOURCE_DIR}/src/${PLUGIN_NAME}/utils/ImageFilterExecutorDetail.hpp" diff --git a/src/Plugins/NXImageProcessing/docs/AcosImageFilter.md b/src/Plugins/NXImageProcessing/docs/AcosImageFilter.md index a6042bbe1c..44b2c6ca76 100644 --- a/src/Plugins/NXImageProcessing/docs/AcosImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/AcosImageFilter.md @@ -1,19 +1,52 @@ # Acos Image Filter -Computes the arccosine of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `acos(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Acos Image Filter. +Computes the **principal arccosine**, `acos(x)`, for each value in the input image. The input is a dimensionless cosine value. The output is an angle in **radians**, from 0 to pi for valid input. It is not an angle in degrees or a normalized angle. + +Values in the closed interval `[-1, 1]` have a real angle. Values outside this interval, including positive and negative infinity, produce NaN (not a number). Incoming NaN also produces NaN. The filter does not clamp, replace or reject these values. + +| Input cosine | Output angle (radians) | +|---|---| +| -1 | pi, approximately 3.14159265 | +| 0 | pi/2, approximately 1.57079633 | +| 1 | 0 | +| 2 | NaN | + +### Output Type and Precision + +| Input type | Output type | Output bytes per value | +|---|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float32 | 4 | +| float32 | float32 | 4 | +| float64 | float64 | 8 | + +Integer inputs need floating output because their valid values `-1`, `0` and `1` produce pi, pi/2 and 0 radians. Integer output would lose the fractional part of these angles and could not store NaN. With unsigned integer input, only `0` and `1` are in the valid domain. + +The calculation uses double precision, then stores the result in the output type. For valid integer inputs, float32 introduces at most about `8.74e-8` radians of representation error. The filter preserves the input tuple shape and component shape. It processes each component separately. + +For integer input, output storage is four times the size of an 8-bit input, twice the size of a 16-bit input, equal to a 32-bit input, and half the size of a 64-bit input. Floating input keeps its existing storage width. + +### Migration and Downstream Use + +Existing pipelines with integer input now receive float32 angles. Previously, integer output discarded fractional angles: for example, `acos(0)` became 1 rather than pi/2 radians. Check downstream filters that require integer input and thresholds that relied on that truncation. For example, `acos(-1)` is pi and exceeds a threshold of 3.1 radians; the old integer result of 3 did not. This is a constructed example. + +Before converting the result to an integer type later in a pipeline, handle NaN and check the destination range. An unchecked conversion can reintroduce the unsafe behavior this floating output avoids. For valid integer inputs, direct zero/nonzero status is unchanged. + +## Algorithm + +The filter evaluates each value independently. Resident arrays use direct memory views. Out-of-core arrays use serial bulk reads and writes through working batches; parallel calculation uses owned buffers. Batch sizes follow the pointwise engine's memory target and store layout. A small image can fit in one batch. The output belongs to the input geometry. An explicit input storage format also applies to the output. When the input uses automatic storage, the storage resolver uses the output type and size. A uint8 image in memory can therefore produce a float32 array large enough to use disk storage. % Auto generated parameter table will be inserted here ## Example Pipelines +`16_Phase_and_Angle_Field_Transforms.d3dpipeline` uses this filter to convert *Normalized Response* into *Inverse Cosine*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/AsinImageFilter.md b/src/Plugins/NXImageProcessing/docs/AsinImageFilter.md index cc94ce7f36..9e7e597e96 100644 --- a/src/Plugins/NXImageProcessing/docs/AsinImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/AsinImageFilter.md @@ -1,19 +1,54 @@ # Asin Image Filter -Computes the arcsine of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `asin(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Asin Image Filter. +Computes the **principal arcsine**, `asin(x)`, for each value in the input image. The input is a dimensionless sine value. The output is an angle in **radians**, from -pi/2 to pi/2 for valid input. + +Values in the closed interval `[-1, 1]` have a real angle. Values outside this interval, including positive and negative infinity, produce NaN (not a number). Incoming NaN also produces NaN. The filter does not clamp, replace or reject these values. + +| Input sine | Output angle (radians) | +|---|---| +| -1 | -pi/2, approximately -1.57079633 | +| 0 | 0 | +| 1 | pi/2, approximately 1.57079633 | +| 2 | NaN | + +### Output Type and Precision + +| Input type | Output type | Output bytes per value | +|---|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float32 | 4 | +| float32 | float32 | 4 | +| float64 | float64 | 8 | + +Integer inputs need floating output because their valid values `-1`, `0` and `1` produce -pi/2, 0 and pi/2 radians. Integer output would lose the fractional part of these angles and could not store NaN. With unsigned integer input, only `0` and `1` are in the valid domain. + +The calculation uses double precision, then stores the result in the output type. For valid integer inputs, float32 introduces at most about `4.37e-8` radians of representation error. The filter preserves the input tuple shape and component shape. It processes each component separately. + +For integer input, output storage is four times the size of an 8-bit input, twice the size of a 16-bit input, equal to a 32-bit input, and half the size of a 64-bit input. Floating input keeps its existing storage width. + +### Migration and Downstream Use + +Existing pipelines with integer input now receive float32 angles. Previously, integer output discarded fractional angles: for example, `asin(1)` became 1 rather than pi/2 radians. Check downstream filters that require integer input and thresholds that relied on that truncation. For valid integer inputs, direct zero/nonzero status is unchanged. + +For example, an Asin result passed to [Acos Image Filter](AcosImageFilter.md) can change from the old quantized `1` to pi/2. Acos then produces NaN because pi/2 is outside its input domain `[-1, 1]`. This is a constructed composition example; it does not represent a reproduced user pipeline. Check the units and domain before using a radian angle as a dimensionless trigonometric input. + +Before converting the result to an integer type later in a pipeline, handle NaN and check the destination range. An unchecked conversion can reintroduce unsafe behavior. + +## Algorithm + +The filter evaluates each value independently. Resident arrays use direct memory views. Out-of-core arrays use serial bulk reads and writes through working batches; parallel calculation uses owned buffers. Batch sizes follow the pointwise engine's memory target and store layout. A small image can fit in one batch. The output belongs to the input geometry. An explicit input storage format also applies to the output. When the input uses automatic storage, the storage resolver uses the output type and size. A uint8 image in memory can therefore produce a float32 array large enough to use disk storage. % Auto generated parameter table will be inserted here ## Example Pipelines +`16_Phase_and_Angle_Field_Transforms.d3dpipeline` uses this filter to convert *Normalized Response* into *Inverse Sine*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/ConnectedComponentImageFilter.md b/src/Plugins/NXImageProcessing/docs/ConnectedComponentImageFilter.md index 5f0a3644fa..ec06c0c5f1 100644 --- a/src/Plugins/NXImageProcessing/docs/ConnectedComponentImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/ConnectedComponentImageFilter.md @@ -8,35 +8,48 @@ NXImageProcessing (Segmentation) ## Description -Labels the objects in the input image: non-zero input voxels are considered foreground, zero-valued voxels are considered background. Each distinct foreground object is assigned a unique label. Objects that are reached earlier by a raster-order (X fastest, then Y, then Z) scan receive a lower label, so labels start at 1 and are consecutive; background voxels are always labeled 0. +Labels connected foreground objects. Nonzero input voxels are foreground. Input voxels with value 0 are background. +The input must have one component and can use any signed or unsigned integer type. -The input array must be single-component (scalar) and may be **any integer type** (signed or unsigned). The output is a fixed **uint32** label image regardless of the input element type. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK Connected Component Image Filter, and matches it exactly (byte-identical label values). +The output uses uint32 labels (4 bytes per voxel). Below the run ID limit, background has label 0 and each object has +a unique label. The filter assigns labels in scan order, starting at 1 and stepping along X first, then Y, then Z. +These labels match the legacy ITK filter below the run ID limit. ### Fully Connected -Set/Get whether the connected components are defined strictly by face connectivity or by face+edge+vertex connectivity. Default is FullyConnectedOff. For objects that are 1 pixel wide, use FullyConnectedOn. +**Fully Connected** is off by default. The filter joins voxels that share a face. Enable it to also join voxels that +touch at an edge or vertex. -## Algorithm - -The filter scans the image in X-fastest order. It encodes each foreground run along X. A union-find table joins runs that have the selected connectivity. +### Provisional Label Limit Handling -After the first pass, the filter maps each provisional label to a consecutive label. The first output label is one. Each table entry represents a run, not a voxel. +The filter assigns one provisional ID to each uninterrupted foreground run along X. Multiple runs can join to form one +object. For example, a bridge can connect several stripes. The limit counts runs. -For OOC 3D data, the filter first requests memory for the complete working state. A complete grant uses one input read and one output write. +- **Error** (default) accepts provisional ID 4,294,967,295. The filter stops if another run needs an ID. +- **Warn and Continue (Legacy Behavior)** reports one warning at the first overflow and continues. The first overflowing + ID becomes background 0. Later IDs reuse existing labels, starting at 1. -If this request is not complete, the filter requests memory for the uint32 provisional-label volume. A complete second grant keeps that volume in memory. +In Warn mode, a wrapped 0 in the previous row can cause scanline processing to label an adjacent object as background. +Tiled processing skips that previous-row 0, so the two routes can give different labels. In either route, foreground can +disappear and distinct objects can merge. These changes can affect object counts, sizes, and measurements. -If the second grant is not complete, the filter uses bounded replay. Pass 1 reads each input plane once. It encodes independent rows in parallel and keeps only adjacent-plane run data. +Saved pipelines without this choice use **Error**. Select **Warn and Continue (Legacy Behavior)** only if you need the +old overflow behavior and can accept its effects. A memory or file error can stop either choice. -After union resolution, pass 2 reads adjacent plane groups. It counts and maps independent rows in parallel. The group size uses at most one-twentieth of the complete replay working set, with a one-plane minimum. The shared cache budget can reduce this size. +## Algorithm -The bounded 3D route uses two full input reads and one full output write. Grouping changes the number of transfers, not the logical I/O. The route does not store a complete provisional-label volume. +The filter finds runs along X and joins neighboring runs with an equivalence table. A final pass assigns consecutive +labels. -For true 2D data (`Z=1`), a checked scheduler uses at most 64 MiB for blocks. An extremely wide row uses X tiles. +For out-of-core 3D data, the filter keeps as much working data in memory as the available budget allows. If it can +keep the complete state in memory, it reads the input once. With less memory it can keep provisional labels in memory. +If the labels also do not fit, it reads the input twice and writes the output once in bounded groups. -The tiled first pass can use temporary records for previous-row labels. The final pass rereads bounded input tiles and writes bounded output tiles. +For 2D data, wide rows can be processed in tiles. Temporary files can hold the previous row's labels. The final pass +reads input tiles and writes output tiles in bounded groups. -All routes create labels at the same raster run starts. They preserve the same union order and consecutive-label order. +All routes keep equivalence tables in memory. Memory use grows with the number of provisional runs. Three uint32 tables +at the ID limit need at least 48 GiB, before other working data. A memory allocation can fail before the ID limit is reached. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/CurvatureFlowImageFilter.md b/src/Plugins/NXImageProcessing/docs/CurvatureFlowImageFilter.md index 0a8337318d..97f362ec6b 100644 --- a/src/Plugins/NXImageProcessing/docs/CurvatureFlowImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/CurvatureFlowImageFilter.md @@ -16,7 +16,15 @@ where kappa is the curvature of the iso-brightness contour passing through each The evolution is computed with a multi-threaded finite-difference solver: at every iteration, an update is computed at each voxel from a frozen (Jacobi) neighborhood of the current image using a zero-flux Neumann (edge-clamp) boundary condition, and then `Output = Output + TimeStep * Update` is applied everywhere. The per-axis image spacing is used when computing derivatives, so the result depends on the Image Geometry's spacing. -The input array must be single-component (scalar) and may be **any** scalar type (signed/unsigned integer or floating point). The output has the **same type as the input** (type-preserving); for an integer input, each iteration's update is truncated to the input type exactly as the legacy filter does. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK Curvature Flow Image Filter, and matches it exactly (bit-exact for integer types; exact/near-exact for floating point). +The input array must be single-component (scalar). It can use any signed integer, unsigned integer, float32, or float64 type. The output has the **same type and tuple shape as the input**. All working iterations use float64 values. Integer values are converted only once, after the last iteration; they are not truncated after each update. + +For integer output, each final value must be finite. The filter truncates the value toward zero, then clips it to the output type's range if needed. For example, 93.75 becomes 93. For uint8 output, -0.5 becomes 0 without clipping, while -1.5 clips to 0. One warning gives the number of clipped values. A nonfinite computed value causes an error for integer output. The error gives the number of nonfinite values and the flat index if exactly one value was found. If a transfer fails or the filter stops before completing conversion, the diagnostics identify partial counts. Completed blocks can remain in the output. + +Floating output retains NaN and infinity behavior. When narrowing to float32, a value just above the largest finite magnitude can still round to that magnitude. Values at or beyond the overflow midpoint round to signed infinity. float64 output retains the float64 result. Input and working precision still limit accuracy: ordinary evolution can lose integer detail above 2^53, even for int64 and uint64 output. Changing the output type does not restore that detail. + +Time Step must be finite and nonnegative. Spacing on each active axis must be finite and nonzero; finite negative spacing remains accepted. X and Y are active in a 2D image. Z is active only when the Z dimension is greater than one. Unused Z spacing is ignored in 2D. The filter checks Time Step during preflight and checks the final geometry spacing during execution, including a no-op request. A zero Time Step or zero Number Of Iterations then copies input values exactly, including native 64-bit integers, without float64 conversion. + +Pipelines that previously produced an out-of-range integer cast now receive clipped values and a warning, or an error for a nonfinite integer result. Clipping can create plateaus, change masks, and merge segmented regions. Check downstream thresholds and segmentation when the warning occurs. Clipping does not correct an unstable evolution. The timestep should be small enough to ensure numerical stability. Stability is guaranteed when the timestep meets the CFL (Courant-Friedrichs-Levy) condition; broadly speaking, this condition ensures that each contour does not move more than one grid position per timestep. The timestep typically must be manually tuned to the application. @@ -26,9 +34,11 @@ For resident arrays, the solver keeps its intermediate and update images residen For a 3D image with an out-of-core input or output, the solver first asks the shared cache budget for the complete input, output, intermediate, update, and conversion-plane state. A complete grant reads the input once, runs the same resident Jacobi calculation, and writes the output once. A partial grant or allocation failure uses the bounded fallback: a three-plane rolling neighborhood plus two raw temporary-record working stores, with initial/final conversions and updates transferred one Z plane at a time. For true 2D, the existing checked row-block and X-tile plan remains bounded to 64 MiB. +The final conversion uses the existing resident, plane, or tile buffers. It does not add a full-image resident temporary to the bounded routes. Exact no-op copies use a transfer buffer of at most 1 MiB. Output storage size does not increase. + ### Time Step -The timestep between iteration updates. Default is 0.05. +The timestep between iteration updates. It must be finite and nonnegative. Default is 0.05. Zero copies the input exactly after control validation. The filter does not choose an automatic stability cutoff or adapt this value. ### Number Of Iterations diff --git a/src/Plugins/NXImageProcessing/docs/ExpImageFilter.md b/src/Plugins/NXImageProcessing/docs/ExpImageFilter.md index 98e431cd2e..49686f81b2 100644 --- a/src/Plugins/NXImageProcessing/docs/ExpImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/ExpImageFilter.md @@ -1,19 +1,49 @@ # Exp Image Filter -Computes the exponential of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `exp(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Exp Image Filter. +Computes the natural exponential, `exp(x) = e^x`, for each input value. The input and output are dimensionless. Positive inputs describe growth. Negative inputs give positive decay values below 1. Each component is processed separately. The output keeps the input tuple and component shapes. + +### Output type and precision + +| Input type | Output type | Output bytes per value | +|---|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float64 | 8 | +| float32 | float32 | 4 | +| float64 | float64 | 8 | + +Integer input uses float64 because an exponential can have fractional decay or large growth. For example, integer input -1 gives about 0.3678794412. Integer input 100 gives the finite float64 value about 2.6881171418 × 10^43. Float32 input 100 keeps float32 output and gives positive infinity. Output promotion depends on the input type, not its value. + +Float32 has about 7 significant decimal digits; float64 has about 16. Floating results are rounded to the output type. Float64 covers the full int8 and uint8 exponential range, but no finite output type covers all possible input values. Integer input 255 gives about 5.5602316477 × 10^110, which exceeds the float32 range. + +### Numeric limits + +- NaN (not a number) produces NaN. +- Positive infinity produces positive infinity. Negative infinity produces positive zero. +- Positive and negative zero both produce 1. +- Growth beyond the finite output range produces positive infinity. Finite double results above the float32 range are handled explicitly before conversion. +- Very small decay results can be **subnormal** values, which are positive values below the smallest normal floating value. Further underflow produces zero. Float32 input -128 produces zero; float64 or integer input -128 gives about 2.5722093726 × 10^-56. + +### Storage and downstream use + +For integer inputs, the 8-byte output uses 8, 4, 2, or 1 times the bytes of an 8-, 16-, 32-, or 64-bit input value. One billion uint8 input values require 1 GB, and their output values require 8 GB, before other storage. Floating input keeps its existing output width. + +Earlier integer output truncated positive decay values below 1 to zero. These values now remain positive until floating underflow occurs. Review thresholds and zero/nonzero masks that depended on that integer truncation. Downstream filters that accept only integers can reject the float64 output. An unchecked conversion back to integer can again lose decay values or exceed the integer range. + +## Algorithm + +The filter applies the same exponential operation to resident and disk-backed arrays. Buffered processing targets 64 MiB of transfer scratch by default, but each batch must contain at least one complete storage slab formed by the trailing tuple dimensions, such as an XY slice for Z/Y/X storage. A slab can exceed that target or cover the entire array. Bulk input and output transfers are serial. The calculation runs in parallel on owned buffers. Exp adds no separate full-volume scratch array beyond those transfer buffers. Output storage still requires the bytes shown above. % Auto generated parameter table will be inserted here ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Exponential Response*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/ExpNegativeImageFilter.md b/src/Plugins/NXImageProcessing/docs/ExpNegativeImageFilter.md index 6cca66b243..40051b2403 100644 --- a/src/Plugins/NXImageProcessing/docs/ExpNegativeImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/ExpNegativeImageFilter.md @@ -1,19 +1,53 @@ # Exp Negative Image Filter -Computes the negative exponential of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `exp(-x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Exp Negative Image Filter. +Computes the negative exponential, `exp(-x) = e^(-x)`, for each input value. The input and output are dimensionless. Positive inputs give positive decay values below 1. Negative inputs produce growth. Each component is processed separately. The output keeps the input tuple and component shapes. + +### Output type and precision + +| Input type | Output type | Output bytes per value | +|---|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float64 | 8 | +| float32 | float32 | 4 | +| float64 | float64 | 8 | + +Integer input uses float64 to preserve quantitative decay and a wider growth range. Input 1 gives about 0.3678794412. Input 255 gives about 1.7984862203 × 10^-111, which is positive in float64 but below the float32 range. Input -128 gives about 3.8877084060 × 10^55, which also requires the float64 range. Output promotion depends on the input type, not its value. + +Float32 has about 7 significant decimal digits; float64 has about 16. Results are rounded to the output type. Float64 represents every int8 and uint8 negative-exponential result as a finite positive value, but the larger integer types can still produce underflow or overflow. Converting a 64-bit integer argument to float64 can round that argument before the calculation. Floating input keeps its existing type: float32 input -128 produces positive infinity, while float64 or integer input -128 has the finite result above. + +### Numeric limits + +- NaN (not a number) produces NaN. +- Positive infinity produces positive zero. Negative infinity produces positive infinity. +- Positive and negative zero both produce 1. +- Growth beyond the finite output range produces positive infinity. Finite float64 results above the float32 range are handled explicitly before conversion. +- Very small decay results can be **subnormal** values, which are positive values below the smallest normal floating value. Further underflow produces positive zero. Float32 input 128 produces zero; float64 or integer input 128 gives about 2.5722093726 × 10^-56. + +The argument is converted to float64 before its sign changes. A signed integer minimum is therefore not negated in its integer type. + +### Storage and downstream use + +For integer inputs, the 8-byte output uses 8, 4, 2, or 1 times the bytes of an 8-, 16-, 32-, or 64-bit input value. One billion uint8 input values require 1 GB, and their output values require 8 GB, before other storage. Floating input keeps its existing output width. + +Earlier integer output truncated decay values to zero: integer input 1 or 255 gave zero. These results now remain positive until floating underflow occurs. Every uint8 input from 0 through 255 has a positive float64 output. A later output-not-equal-to-zero mask can therefore select every cell. Review masks and thresholds that depended on the earlier integer truncation. + +Downstream filters that accept only integers can reject the float64 output. Adjust the pipeline to accept floating data and reconsider its thresholds. If an integer conversion is necessary, choose an explicit range and rounding policy. An unchecked conversion can lose decay values or exceed the integer range. + +## Algorithm + +The filter applies the same negative-exponential operation to resident and disk-backed arrays. The shared streaming path targets 64 MiB of transfer scratch space, with a minimum of one complete slab across the trailing tuple dimensions, such as an XY slice for Z/Y/X tuple order. A slab can exceed that target or cover the whole array. Bulk reads and writes are serial; the calculation can run in parallel on owned buffers. Exp Negative adds no separate full-volume scratch array. Output storage still requires the bytes shown above. % Auto generated parameter table will be inserted here ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Negative Exponential*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/HConvexImageFilter.md b/src/Plugins/NXImageProcessing/docs/HConvexImageFilter.md index d7785caa5d..f6264122ea 100644 --- a/src/Plugins/NXImageProcessing/docs/HConvexImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/HConvexImageFilter.md @@ -10,15 +10,29 @@ NXImageProcessing (Morphology) Computes the *h-convex* transform of a grayscale image: **HConvex(f, h) = f − HMaxima(f, h)**. Each regional maximum of the input is replaced by its own height (its contrast to the surrounding level), **capped at the Height parameter**, while everything that is not part of a maximum becomes zero. A regional maximum of contrast `c` therefore maps to `min(c, h)`. +Here HMaxima denotes mathematical reconstruction by dilation. With 64-bit integer intensities above 2^53, +the separate H Maxima filter can round its marker through Float64. Subtracting that filter's output from the +input can therefore give a different value. For example, an isolated peak at 2^54 and Height 1 has exact +marker intensity 2^54 − 1 in H Convex. + This isolates bright "domes" and measures their prominence: peaks taller than `Height` all map to `Height`, while shallower peaks map to their true contrast. It is a common pre-step for peak detection and marker extraction. -Internally the filter reconstructs the input by dilation of the `input − Height` marker (the H Maxima result) and then subtracts that result from the input. Because the reconstruction result never exceeds the input, the difference is always non-negative and stays within the input type's range. +Internally the filter reconstructs the `input − Height` marker by dilation under the original input, then subtracts that reconstruction from the input. The reconstruction cannot exceed an integer input, so the integer contrast is nonnegative. A nonnegative contrast can still exceed a signed output type's maximum. The filter returns an execution error in that case. -The input array must be single-component (scalar); the output element type matches the input element type. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK H Convex Image Filter, and matches it exactly for integer and float types. +The input array must have one component per tuple (a **scalar image**). Output type, tuple dimensions and component dimensions match the input. Output storage does not increase automatically. Resident and disk-backed arrays use the same numeric rules. ### Height -The height (contrast) cap. Regional maxima taller than this value are reported at this value; shallower maxima are reported at their true height. +**Height** is a contrast offset in the input's intensity units. It must be finite and nonnegative. + +- Integer images require a whole-number Height. A fractional value, such as *2.5*, fails preflight. Choose an intentional whole value, or explicitly convert the image to a floating type before using a fraction. +- Floating images allow fractional Height and keep their existing floating arithmetic and precision. +- With integer images, the marker is the exact native value minus Height, saturated at the input type's minimum. Native 64-bit image values do not pass through floating point. Height *0* preserves the marker and reconstruction exactly; the HConvex output is therefore zero everywhere. +- Height is stored as a float64 parameter. Above *2^53*, float64 cannot distinguish every consecutive integer Height. The filter uses the whole value represented by that parameter. A Height of *2^64* or more lowers every integer marker value to the type minimum. + +If the actual signed integer contrast does not fit the unchanged output type, execution fails with the input array and first failing tuple in the message. For example, int8 input `[-128, 127, -128]` with Height *255* would require contrast `[0, 255, 0]`; *255* cannot fit in int8, so the filter returns an error. Input `[-128, -1, -128]` at the same Height has representable contrast `[0, 127, 0]`. + +For an existing integer pipeline that used fractional Height, choose a whole Height or convert its input explicitly. Exact marker arithmetic can also change results that previously lost native 64-bit units. Review downstream peak selection, watershed markers and segmentation when migrating such a pipeline. ### Fully Connected @@ -31,7 +45,11 @@ Geodesic morphology, the h-maxima transform, and the h-convex transform are desc ## Algorithm -The filter lowers the input by **Height**, reconstructs that marker under the input by dilation, and subtracts the reconstruction from the input. Resident arrays use the Vincent hybrid reconstruction, whose raster, anti-raster, and fold-to-convergence sweeps run as dependency-exact, block-wavefront parallel plane sweeps when the reconstruction uses face connectivity (**Fully Connected** off); with full connectivity it falls back to the exact serial sweeps, since a same-row diagonal read can land in the horizontally adjacent block, which no rectangular block schedule can order. Disk-backed reconstruction iterates a forward raster sweep followed by a reverse anti-raster sweep over consecutive Z-plane slabs until stable, skipping any slab whose planes are already proven unchanged since that direction's last visit. Within a plane, the raster/anti-raster sweep is tiled into independent blocks that run in parallel; under face connectivity every voxel still sees exactly the values the un-blocked sweep would produce, and under full connectivity the iterated forward/reverse passes still converge to the identical final result. Each work and mask slab targets 16 MiB, plus one boundary plane. At least one plane is processed, so a single plane wider than the target can make the buffers exceed 16 MiB. Update order and output are unchanged, preserving exact storage-path parity. +The filter lowers the input by **Height**, reconstructs that marker under the input by dilation, and subtracts the reconstruction from the input. Resident arrays keep the Vincent reconstruction route and direct parallel subtraction. Signed subtraction checks each contrast before performing arithmetic that could overflow. + +Disk-backed input supplies its marker from owned reconstruction buffers, so it does not require a separate resident marker image. Reconstruction keeps its existing working-memory reservation and sweep routes. A granted working set can hold a complete image when it fits. Otherwise, 2-D data uses rows or tiles, and 3-D data uses slabs with a boundary plane. A 3-D streaming plan needs enough space for two working planes and one boundary plane; it returns an error if the grant cannot hold that minimum. This is a working-buffer budget, not a limit on total process memory. + +For disk-backed or other nonresident stores, the signed contrast phase transfers data serially through two owned buffers of at most 32 MiB each. It performs parallel arithmetic only on those buffers and propagates transfer errors and warnings. Resident signed contrast uses direct parallel spans without these transfer buffers. The buffer limits exclude the data stores, their cache and the reconstruction working set. If execution fails, some output values or completed chunks may already have been written; an error does not promise an unchanged output array. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/HMaximaImageFilter.md b/src/Plugins/NXImageProcessing/docs/HMaximaImageFilter.md index 85a75d2576..2ed47c82c2 100644 --- a/src/Plugins/NXImageProcessing/docs/HMaximaImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/HMaximaImageFilter.md @@ -16,6 +16,10 @@ Internally the filter performs a **reconstruction-by-dilation** of a marker imag The input array must be single-component (scalar); the output element type matches the input element type. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK H Maxima Image Filter. When all data is resident it uses a fast in-core hybrid reconstruction; when the arrays are out-of-core it streams the computation so memory use stays bounded regardless of image size. Both paths produce bit-identical output, and the result matches the legacy ITK filter exactly. +For wide integer images, marker construction uses Float64 arithmetic. It can lose single intensity units +above 2^53. The [H Convex](HConvexImageFilter.md) filter uses exact integer marker arithmetic and should be +used directly for integer peak contrast. + ### Height The *Height* parameter sets the contrast threshold in the same units as the image intensities: diff --git a/src/Plugins/NXImageProcessing/docs/HMinimaImageFilter.md b/src/Plugins/NXImageProcessing/docs/HMinimaImageFilter.md index af3a821585..3a9406a985 100644 --- a/src/Plugins/NXImageProcessing/docs/HMinimaImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/HMinimaImageFilter.md @@ -8,20 +8,24 @@ NXImageProcessing (Morphology) ## Description -Applies the **H-Minima transform** to a grayscale image. The transform removes every *regional minimum* whose **depth** -- its contrast below the surrounding level -- is less than the **Height** parameter, and raises each surviving minimum by exactly **Height**. Shallow dark features (whose contrast is below **Height**) are filled up to their surrounding background, while deeper dark features are preserved but raised in intensity by **Height**. +Applies the **H-Minima transform** to a grayscale image. A **regional minimum** is a connected region below its surrounding intensities. Its **depth** is the intensity difference to that surrounding level. The transform suppresses minima whose depth is less than **Height**. Deeper minima rise by Height, subject to the input type's maximum. The H-Minima transform is commonly used to remove insignificant intensity valleys caused by noise prior to a minima-detection or watershed step, so that only sufficiently prominent minima remain. It is the erosion counterpart of the H-Maxima transform. -Internally the filter performs a **reconstruction-by-erosion** of a marker image equal to the saturating sum `input + Height`, using the input image as the mask. Because the marker is formed with a *saturating* cast, a sum that overflows the element type's range is **clamped** to the type maximum (rather than wrapping), matching the legacy ITK behavior exactly. +The filter performs **reconstruction by erosion** of the raised marker `input + Height`, with the original input as its lower mask. Erosion lowers marker values through connected neighbors, but cannot lower them below the input mask. Output contains these reconstructed intensities. For example, an isolated minimum *30* in background *50* becomes *40* at Height *10*. It does not become a contrast value of *10*. A one-pixel image has no neighbor to lower its marker, so its output is the raised marker. -The input array must be single-component (scalar); the output element type matches the input element type. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK H Minima Image Filter. When all data is resident it uses a fast in-core hybrid reconstruction; when the arrays are out-of-core it streams the computation so memory use stays bounded regardless of image size. Both paths produce bit-identical output, and the result matches the legacy ITK filter exactly. +The input must have one component per tuple, called a **scalar image**. Output type, tuple dimensions and component dimensions match input. Output storage does not increase automatically. Resident and disk-backed arrays use the same numeric rules. ### Height -The *Height* parameter sets the contrast threshold in the same units as the image intensities: +**Height** is a contrast offset in the input's intensity units. It must be finite and nonnegative. -- Regional minima with a contrast **less than** *Height* are removed (filled up to the surrounding level). -- Regional minima with a contrast **greater than or equal to** *Height* survive but are raised by exactly *Height*. +- Integer images require a whole-number Height. Fractions such as *0.5* or *2.5* fail preflight. Choose an intentional whole Height, or explicitly convert the input to floating point before using a fraction. +- Floating images allow fractional Height. Their marker uses floating arithmetic and rounds to the input type's precision. +- Integer markers use exact native addition and saturate at the input type's maximum. Native 64-bit input values do not pass through floating point. Height *0* preserves every integer input value exactly, including native bounds. +- Height is stored as a float64 parameter. Above *2^53*, float64 cannot distinguish every consecutive integer Height. The filter uses the whole value represented by that parameter. A Height of *2^64* or more raises every integer marker value to the type maximum. + +For existing integer pipelines with fractional Height, choose a whole Height or convert the input explicitly. Exact arithmetic can change results that previously lost native 64-bit units. Review downstream minima selection, watershed seeds and segmentation when migrating such a pipeline. ### Fully Connected @@ -34,7 +38,11 @@ Geodesic morphology and grayscale reconstruction are described in Chapter 6 of P ## Algorithm -The filter raises the input by **Height** and reconstructs that marker under the input by erosion. Resident arrays use the Vincent hybrid reconstruction, whose raster, anti-raster, and fold-to-convergence sweeps run as dependency-exact, block-wavefront parallel plane sweeps when the reconstruction uses face connectivity (**Fully Connected** off); with full connectivity it falls back to the exact serial sweeps, since a same-row diagonal read can land in the horizontally adjacent block, which no rectangular block schedule can order. Disk-backed reconstruction iterates a forward raster sweep followed by a reverse anti-raster sweep over consecutive Z-plane slabs until stable, skipping any slab whose planes are already proven unchanged since that direction's last visit. Within a plane, the raster/anti-raster sweep is tiled into independent blocks that run in parallel; under face connectivity every voxel still sees exactly the values the un-blocked sweep would produce, and under full connectivity the iterated forward/reverse passes still converge to the identical final result. Each work and mask slab targets 16 MiB, plus one boundary plane. At least one plane is processed, so a single plane wider than the target can make the buffers exceed 16 MiB. Update order and output are unchanged, preserving exact storage-path parity. +The filter raises the input by Height and reconstructs that marker under the input by erosion. Resident input uses a materialized marker and keeps the Vincent hybrid reconstruction route. This route can allocate complete resident images for its marker and reconstruction work. + +Disk-backed input derives marker values in owned reconstruction buffers. It does not require a separate complete resident marker image. Reconstruction keeps its existing working-memory reservation and sweep routes. A granted working set can hold a complete image when it fits. Otherwise, 2-D data uses rows or tiles, and 3-D data uses slabs with a boundary plane. A 3-D streaming plan needs space for two working planes and one boundary plane. Execution fails if the grant cannot hold that minimum. The working-buffer budget excludes data stores, their cache and other process memory. + +Store transfers remain serial; parallel work uses stable owned buffers. Transfer errors, cancellation and existing allocation fallbacks retain their existing behavior. A later execution failure can leave completed output values or chunks written. An error does not promise an unchanged output array. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/Log10ImageFilter.md b/src/Plugins/NXImageProcessing/docs/Log10ImageFilter.md index 220b0307ab..dfce8b835a 100644 --- a/src/Plugins/NXImageProcessing/docs/Log10ImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/Log10ImageFilter.md @@ -1,19 +1,62 @@ # Log10 Image Filter -Computes the base-10 logarithm of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `log10(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Log10 Image Filter. +Computes the base-10 logarithm, `log10(x)`, of each image value. The filter applies the same operation to each component and preserves the array's tuple and component shapes. For example, `log10(1) = 0`, `log10(10) = 1`, and `log10(100) = 2`. + +Use positive input values to obtain finite results. The logarithm is dimensionless. If the source has physical units, first divide by a suitable reference with the same units. This transform does not supply a physical calibration. + +### Output Type and Precision + +Preflight and execution use the following output types: + +| Input type | Output type | +|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float64 | +| float32 | float32 | +| float64 | float64 | + +The calculation uses float64 precision. Integer input produces float64 output so that fractional logarithms are retained. For example, `log10(2)` is approximately 0.3010299956639812. Float32 input retains float32 output and its usual rounding. + +Float32 has enough range for these logarithms. Float64 output for integer input retains the existing double-precision calculation; this is a precision and storage choice. Converting int64 or uint64 input to float64 can round the input before the logarithm is calculated. Nearby large integers can therefore produce the same result. Float64 output does not make every 64-bit integer exactly representable. + +Each output value from integer input occupies 8 bytes. Compared with the former same-type output, this uses 8, 4, 2, or 1 times the storage for 8-, 16-, 32-, or 64-bit input, respectively. These factors describe array values and exclude storage metadata and compression. + +### Zero, Negative, and Nonfinite Values + +The filter retains ordinary floating-point behavior: + +| Input value | Output value | +|---|---| +| Positive finite value | Finite base-10 logarithm | +| Positive or negative zero | Negative infinity | +| Negative finite value | NaN (not a number) | +| Negative infinity | NaN | +| Positive infinity | Positive infinity | +| NaN | NaN | + +Zero and negative input are distinct cases. The filter does not clamp them to a positive value or replace the result with zero. Positive subnormal values, which are smaller than the smallest normal floating-point value, still have finite logarithms. + +### Existing Pipelines + +Integer input now produces float64 output. Earlier same-type integer output discarded fractional results; `log10(2)` became zero. Update downstream filters that require integer arrays. Recheck thresholds and zero/nonzero masks that depended on the old quantization. + +Handle NaN and infinity explicitly before range calculations or conversion to integer. An unchecked conversion back to integer can reintroduce unsafe behavior. + +## Algorithm + +This is an ITK-free implementation of the legacy ITK Log10 Image Filter. It uses the existing pointwise traversal for resident and disk-backed arrays. Resident storage retains the direct route when available. The buffered route uses serial bulk reads and writes with a default transfer scratch target of 64 MiB. Each working batch contains at least one complete storage slab across the trailing dimensions, such as an XY slice in a Z/Y/X image. A slab can exceed the target or cover the entire array. Parallel math uses owned buffers. Log10 adds no separate scratch array for the full volume. Cancellation and storage failures follow the shared pointwise execution path. % Auto generated parameter table will be inserted here ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Base-10 Log Transmission*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/LogImageFilter.md b/src/Plugins/NXImageProcessing/docs/LogImageFilter.md index 51b7be9d5e..35ae544752 100644 --- a/src/Plugins/NXImageProcessing/docs/LogImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/LogImageFilter.md @@ -1,14 +1,55 @@ # Log Image Filter -Computes the natural logarithm of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `log(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Log Image Filter. +Computes the natural logarithm, `ln(x)`, of each image value. The base is the mathematical constant *e*, approximately 2.71828. The filter applies the same operation to each component and preserves the array's tuple and component shapes. + +Use positive input values to obtain finite results. The logarithm is dimensionless. If the source has physical units, first divide by a suitable reference with the same units. This transform does not supply a physical calibration. + +### Output Type and Precision + +Preflight and execution use the following output types: + +| Input type | Output type | +|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float64 | +| float32 | float32 | +| float64 | float64 | + +The calculation uses float64 precision. Integer input produces float64 output so that fractional logarithms are retained. For example, `ln(1) = 0` and `ln(2)` is approximately 0.6931471805599453. Float32 input retains float32 output and its usual rounding. + +Converting an int64 or uint64 input to float64 can round the input before the logarithm is calculated. Nearby large integers can therefore produce the same result. Float64 output avoids an additional rounding step to float32; it does not make every 64-bit integer exactly representable. + +Each output value from integer input occupies 8 bytes. Compared with the former same-type output, this uses 8, 4, 2, or 1 times the storage for 8-, 16-, 32-, or 64-bit input, respectively. These factors describe array values and exclude storage metadata and compression. + +### Zero, Negative, and Nonfinite Values + +The filter retains ordinary floating-point behavior: + +| Input value | Output value | +|---|---| +| Positive finite value | Finite natural logarithm | +| Positive or negative zero | Negative infinity | +| Negative finite value | NaN (not a number) | +| Negative infinity | NaN | +| Positive infinity | Positive infinity | +| NaN | NaN | + +Zero and negative input are distinct cases. The filter does not clamp them to a positive value or replace the result with zero. Positive subnormal values, which are smaller than the smallest normal floating-point value, still have finite logarithms. + +### Existing Pipelines + +Integer input now produces float64 output. Earlier same-type integer output discarded fractional results; `ln(2)` became zero. Update downstream filters that require integer arrays. Recheck thresholds and zero/nonzero masks that depended on the old quantization. + +Handle NaN and infinity explicitly before range calculations or conversion to integer. An unchecked conversion back to integer can reintroduce unsafe behavior. + +## Algorithm + +This is an ITK-free implementation of the legacy ITK Log Image Filter. It uses the existing pointwise traversal for resident and disk-backed arrays. Resident storage retains the direct route when available. The buffered route has a default transfer scratch target of 64 MiB and processes at least one complete slab across the trailing tuple dimensions, such as an XY slice for a Z/Y/X array. A slab can exceed the target or cover the whole array. Bulk reads and writes run serially; parallel calculation uses owned buffers. Log adds no separate full-volume scratch allocation. Cancellation and storage failures follow the shared pointwise execution path. ![](Images/LogImageFilter.png) @@ -16,6 +57,8 @@ Computes `log(x)` for every pixel. ITK-free, out-of-core-capable reimplementatio ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Natural Log Transmission*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/MorphologicalWatershedFromMarkersImageFilter.md b/src/Plugins/NXImageProcessing/docs/MorphologicalWatershedFromMarkersImageFilter.md index 169e7d6e63..6875e1f227 100644 --- a/src/Plugins/NXImageProcessing/docs/MorphologicalWatershedFromMarkersImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/MorphologicalWatershedFromMarkersImageFilter.md @@ -8,38 +8,51 @@ NXImageProcessing (Watersheds / Segmentation) ## Description -Floods a grayscale image from a set of user-supplied **marker** (seed) labels, growing each marked region outward over ascending gray levels until neighboring regions meet. The result is a label image in which every voxel is assigned the label of the marker whose basin claimed it. This is the marker-controlled watershed: unlike the parameter-free morphological watershed, the number and identity of the output regions are determined entirely by the markers, so it does not over-segment. +Floods a grayscale image from integer seed labels called **markers**. Seed regions grow as the gray level rises. +The output labels identify the regions, or **basins**, formed when they meet. -Two flooding variants are provided via **Mark Watershed Line**: +- **Mark Watershed Line** is on by default. The filter assigns zero where different basins meet. + With this choice off, the filter assigns reached pixels to basins without a separating line. +- **Fully Connected** is off by default. The filter uses face neighbors (4 in 2D, 6 in 3D). + Enable it to include diagonal neighbors (8 total in 2D, 26 in 3D). -- **On (Meyer's algorithm, the default):** voxels equidistant between two different marker labels are left as a *watershed line* (label 0), producing a thin ridge of background separating the basins. -- **Off (Beucher's algorithm):** every voxel is assigned to a basin (no separating line); this is also slightly faster. +### Input Guidance -**Fully Connected** selects the neighborhood used for flooding: face connectivity (6-connected in 3D, 4-connected in 2D) when off, or face+edge+vertex connectivity (26-connected in 3D, 8-connected in 2D) when on. +Select a single-component grayscale image and a single-component integer marker image with the same tuple count. Marker +ID 0 means unmarked. Pixels that use the same nonzero ID are one seed region, even if they are in separate locations. +If no nonzero seed remains, the output stays unmarked. -### Required Inputs +The output has the marker array's element type and the grayscale image's shape and storage format. -- **Input Cell Data (grayscale):** a single-component scalar image of any numeric type. The flood ascends this image's gray levels. -- **Marker Cell Data:** a single-component **integer** scalar image with the same number of tuples as the grayscale input. Nonzero voxels are markers/seeds; a value of 0 means "unmarked". Voxels sharing the same nonzero label belong to the same seed region, so two disjoint blobs with the same label flood into one basin. +### Marker ID Conversion Handling -### Created Outputs +The filter converts marker IDs to `uint32` for flooding, then restores the marker type. All 8-, 16-, and 32-bit +integer values keep their original IDs, including signed negatives. For `int64` and `uint64`, the values that keep +their IDs range from 0 through 4,294,967,295, inclusive. -- A label image with the **same element type as the marker image**. Basin labels are copied from the markers; watershed-line voxels (when Mark Watershed Line is on) are 0. +- **Error** (default) stops before flooding if an ID changes during conversion. The error identifies the marker array, + flat index, original ID, and ID after conversion back to the marker type. +- **Warn and Continue (Legacy Behavior)** uses the old conversion and continues flooding. It reports how many marker + values changed and identifies the first change. -### Notes / Limitations +| Original marker in Warn mode | ID after conversion | Effect | +| --- | --- | --- | +| `uint64` 4,294,967,296 | 0 | The seed disappears. | +| `uint64` 4,294,967,297 | 1 | The seed can merge with seed 1. | +| `int64` −1 | 4,294,967,295 | The seed gets a different label. | -- The output reproduces the legacy ITK `MorphologicalWatershedFromMarkersImageFilter` exactly, including the label *values*. -- Internally the flood runs in `uint32`. A marker label of `0xFFFFFFFF` is valid and is handled as a normal in-bounds marker. Labels stored in a wider integer type are narrowed to 32 bits during the flood. - -This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK Morphological Watershed From Markers Image Filter. +Seed changes can alter basin boundaries, feature counts, and measurements. Saved pipelines without the choice use +**Error**. Select **Warn and Continue (Legacy Behavior)** only when you intend to keep the old conversion and can accept +those effects. ## Algorithm -Resident input uses an in-memory hierarchical queue. The filter processes the lowest gray level first. It uses FIFO order for voxels at the same level. - -An out-of-core endpoint keeps the same processing order with bounded, file-backed state. The engine gets an adaptive working-memory grant from the shared cache budget. It uses only the useful part of that grant and keeps a disk-backed fallback. If a complete state fits, the engine can keep it resident. Otherwise, it keeps fixed record pages in memory. Large partial 3-D state uses 32 x 32 x 8 voxel tiles so face neighbors usually share one page. +Flooding processes lower gray levels first and preserves arrival order at the same gray level. The filter checks +marker IDs as it copies them in groups of up to 65,536 values. -Eight- and sixteen-bit gray types use ordered gray-level buckets. Each bucket stores 64-bit voxel indexes in file-backed FIFO blocks. Wider integers and floating-point types use a file-backed minimum heap keyed by flood level and insertion order. Marker values are streamed during initialization and are not kept in each voxel record. Input and output transfers use bounded bulk I/O. +The in-memory path holds the flood state in memory. The out-of-core path can also use memory when the state fits. +For larger data it keeps the flood state on disk and reads and writes data in bounded groups. Both paths use the same +flood order. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/OtsuMultipleThresholdsImageFilter.md b/src/Plugins/NXImageProcessing/docs/OtsuMultipleThresholdsImageFilter.md index 2e3cdbaebc..6e78b0cce5 100644 --- a/src/Plugins/NXImageProcessing/docs/OtsuMultipleThresholdsImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/OtsuMultipleThresholdsImageFilter.md @@ -10,7 +10,37 @@ NXImageProcessing (Thresholding) This filter creates a labeled image that separates the input image into various classes. The filter computes the thresholds using a multi-Otsu calculator and applies those thresholds to the input image to produce class labels. The **Number Of Histogram Bins** and **Number Of Thresholds** control the calculator. The **Label Offset** is added to every output label so labels can start from a value other than zero. -Each output voxel is assigned the index of the class its intensity falls into: the number of thresholds the value exceeds, plus the **Label Offset**. The output is always a `uint8` label image, regardless of the (numeric, single-component) input element type. +Each finite, selected voxel receives the number of thresholds that its intensity strictly exceeds, plus **Label Offset**. A value equal to a threshold belongs to the lower class. The input can use any scalar signed or unsigned integer type, `float32`, or `float64`. The output is always a scalar `uint8` label image with the input tuple shape. Threshold values use the input intensity units; output labels have no intensity units. + +The configured class interval is **Label Offset** through **Label Offset + Number Of Thresholds**, including both endpoints. The sum must not exceed 255. The filter rejects an invalid interval instead of wrapping labels. It does not renumber classes or widen the output type. + +### Input with NaN or infinity + +Only selected finite samples contribute to the histogram. The filter can complete with NaN or infinity in the input. Labels at these pixels have no scientific interpretation. Clean invalid intensities upstream or supply a mask that excludes them before using the labels for measurements. + +### Explicit mask and excluded labels + +Enable **Use Mask Array** to select a **Mask Array**. The mask must be scalar `bool` or `uint8`. Its final tuple count must match the input when Otsu runs, after any upstream filters have resized their arrays. Tuples are paired in flat order, so the mask can have a different tuple shape or parent group. False or zero excludes a pixel. True or any nonzero `uint8` value selects it. The filter applies this selection before fitting the histogram. + +Pixels excluded by the mask receive **Excluded Label**, which defaults to 255. When a mask is enabled, this label must be outside the configured class interval, leaving up to 255 ordinary classes. An all-false mask gives every pixel the excluded label. With the mask disabled, all 256 labels are available for classes. + +A distinct label does not make downstream filters ignore excluded pixels. Supply the mask or an explicit background/exclusion rule to consumers that must ignore them. Changing histogram participation can change phase fractions, feature counts, and connectivity. + +For example, use the mask `[1,1,1,1,0,0,0]` with the input `[0,0,4,4,NaN,-Infinity,+Infinity]`. Two bins have counts `[2,2]`. With Label Offset 7 and Excluded Label 255, the output is `[7,7,8,8,255,255,255]`. + +For component labeling, first select the ordinary class of interest into a binary mask. For fractions measured over valid +pixels, exclude Excluded Label from both the selection and the denominator. Removing nonfinite samples from the histogram +can move the fitted thresholds and change the labels of finite pixels too. + +### Precision and pipeline migration + +The filter uses `float64` for histogram bounds, bin measurements, threshold fitting, and comparisons between voxel intensities and thresholds. Adjacent large 64-bit integers can round to the same `float64` value and receive the same label without a warning or error. For example, the first two values in the `uint64` input `[2^53, 2^53 + 1, 2^53 + 4]` round to the same value. With two bins, one threshold, **ReturnBinMidpoint** enabled, and **Label Offset** 0, the output is `[0, 0, 1]`. + +The filter reports a numeric error when it detects an unusable histogram range, unusable bins, nonfinite threshold arithmetic, or objective underflow. For example, distinct selected minimum and maximum values can round to the same value, or a very small nonzero class mean can square to zero. Rescale the finite data or use fewer bins where suitable. The checks do not establish exact arbitrary-precision Otsu accuracy. True finite constants retain the lower-class tie behavior. + +The finite tie tolerance, ordinary threshold search, and Valley Emphasis behavior are retained. **ReturnBinMidpoint** selects a bin midpoint instead of its maximum for the returned threshold. These checks add no automatic normalization or new scientific fitting rule. + +By default, **Use Mask Array** is off. Ordinary finite pipelines with valid label intervals and usable histogram and solver arithmetic retain their labels. A finite pipeline can fail if the fitting arithmetic overflows or loses a required distinction between values. Replacing bad intensities upstream adds those replacement values to the histogram. Masking them leaves them out of the fit. This filter also includes an option to use the valley emphasis algorithm from H.F. Ng, "Automatic thresholding for defect detection", Pattern Recognition Letters, (27): 1644-1649, 2006. The valley emphasis algorithm is particularly effective when the object to be thresholded is small. It is turned off by default; enable it with **Valley Emphasis**. @@ -18,9 +48,15 @@ ITK-free, out-of-core-capable reimplementation of the legacy ITK Otsu Multiple T ## Algorithm -For integral inputs whose observed intensity span is at most 65,535, the filter determines the input range and exact value frequencies in one global scan using a fixed 65,536-entry frequency ring, then populates the requested histogram without rereading the image. Wider integral ranges fall back to a second streaming scan after the range is known. Floating-point inputs retain the statistics scan followed by the histogram scan so their established NaN and range behavior remains unchanged. +For integral inputs whose selected native intensity span is at most 65,535, the filter can determine the input range and exact value frequencies in one scan using a fixed 65,536-entry frequency ring. It then fills the requested histogram without rereading the input. Wider integral ranges use a second bounded histogram scan. Buffered scans also use a second scan when the working-memory grant cannot hold the ring after reserving the input and any mask buffers. Floating-point inputs use a selected finite range/count scan followed by the histogram scan. A true constant has an analytic tied-threshold path. + +The histogram uses the existing marginal upper bound `max + (max - min) / (numberOfBins * 100)`. An upper-bound extension that rounds back to `max` is permitted when the bin geometry remains usable; endpoint clamping keeps minimum/maximum samples inside their bins before an integer index conversion. Native full-span 64-bit inputs remain valid for a two-bin split. No native maximum is incremented. + +Thresholds are calculated from the histogram and applied independently to each selected voxel. Resident scans use direct spans. Other scans use serial bulk input/mask transfers with bounded owned buffers and working-memory reservations. Floating-point range scans reduce fixed blocks in parallel when multicore support is enabled and a batch contains more than one block. Workers read only resident spans or owned buffers. The main thread merges finite bounds and selected counts in block order. The summary table belongs to the current bounded batch and does not grow with the full image. + +The default scratch target for the input, mask and floating-range summaries is 64 MiB. A developer working-memory override can change the target for buffered scans. The amount of useful data and the process-wide memory budget limit the actual grant. A low grant can reduce a buffered scan to one tuple. The masked output pass reserves combined input, mask, and label buffers. Boolean masks use contiguous owned storage. The optional ring and histogram/solver arrays depend on the fixed ring size and requested bin/class counts, not on image volume. The unmasked output pass retains the existing resident/buffered pointwise routes. No full-volume finite-only copy is made. -The thresholds are calculated from the fixed-size histogram and applied independently to every voxel. Disk-backed global scans use byte-capped buffers of at most 64 MiB, the frequency ring has a fixed size independent of the image volume, and the output pass uses separate bounded input and output buffers. Store transfers remain serial and memory use does not grow with the image volume. +Cancellation is checked during scans and threshold search and before label writes. Transfer failures remain errors. Completed earlier label batches are not rolled back if a later output transfer fails. ![Otsu multiple-threshold label map.](Images/OtsuThreshold.png) diff --git a/src/Plugins/NXImageProcessing/docs/SmoothingRecursiveGaussianImageFilter.md b/src/Plugins/NXImageProcessing/docs/SmoothingRecursiveGaussianImageFilter.md index 19a7455a6a..919af1f62b 100644 --- a/src/Plugins/NXImageProcessing/docs/SmoothingRecursiveGaussianImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/SmoothingRecursiveGaussianImageFilter.md @@ -8,27 +8,56 @@ NXImageProcessing (Smoothing) ## Description -Convolves the input image with a Gaussian kernel, computed with the Deriche 4th-order recursive IIR approximation (a fast, image-size-independent approximation to a true Gaussian convolution). One separable 0th-order pass is run along each filtered axis and the passes are cascaded, so the overall effect is a full N-dimensional Gaussian blur. This suppresses noise and fine detail while preserving the overall structure of the image. +Smooths an image with a recursive approximation of a Gaussian filter. Smoothing reduces fine detail and noise. -**Sigma** is specified per-axis (X, Y, Z), in the units of image spacing, so anisotropic smoothing and anisotropic spacing are both supported. Larger sigma produces stronger blurring along that axis. A `Z` size of 1 is treated as a 2D image and only the X and Y axes are filtered. - -The input array must be single-component (scalar) and must be a **signed** type: `int8`, `int16`, `int32`, `int64`, `float32`, or `float64`. Unsigned types are not allowed because the recursive filter has a small negative overshoot that would underflow an unsigned round-trip. The output has the **same type as the input** (type-preserving). This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK Smoothing Recursive Gaussian Image Filter, and matches it exactly for integer and float64 inputs. - -The filter requires at least 4 pixels along every filtered axis. +Select a single-component array of type int8, int16, int32, int64, float32, or float64. The output has the input type and +array shape. Each filtered axis needs at least four pixels. For a single Z slice, the filter uses only X and Y. ### Sigma -The standard deviation of the Gaussian along each axis (X, Y, Z), in the units of image spacing. Default is 1 along every axis. +*Sigma* is the Gaussian standard deviation in image-spacing units. It defaults to 1 along each axis. A larger value +produces more smoothing along that axis. + +Preflight checks that X and Y Sigma are finite and positive. If the final image has more than one Z slice, execution also +requires a finite, positive Z Sigma. Execution checks the spacing on each filtered axis. The spacing magnitude must be finite and greater than +`1e-8` in image-spacing units. The filter checks that Sigma divided by the spacing magnitude gives a finite positive +scale and that the calculation can form finite filter coefficients. Accuracy can decrease at extreme scales. ### Normalize Across Scale -Whether to normalize the Gaussian over scale-space (Lindeberg's scale normalization). This affects derivative magnitudes but does not change 0th-order smoothing. Default is Off. +This choice defaults to Off. It affects Gaussian derivatives. Smoothing uses order zero and has the same result with +either choice. ## Algorithm -The filter applies one separable zero-order recursive-Gaussian pass along each active image axis. Resident **Data Arrays** retain the direct parallel cascade. For a three-dimensional disk-backed image, the Z pass first batches consecutive Y rows across the volume; the following X and Y passes are fused within each Z plane and cast directly to the output. A two-dimensional image fuses its Y and X passes directly from input to output and needs no full-image working array. Store reads and writes remain serial and contiguous; only staged in-memory lines are filtered in parallel. +The filter smooths one axis at a time. It calculates in double precision and stores intermediate values as +**float32** between axes. An output of type float64 cannot recover detail lost in these intermediate values. +Large int64 values can also lose detail. + +The in-memory path filters lines in parallel and holds a float32 working image. The three-dimensional out-of-core path +uses a disk-backed working image and processes bounded groups of rows and planes. The two-dimensional out-of-core path +works in bounded blocks and may use disk-backed intermediate data. Both out-of-core paths read and write stores +serially. + +### Final values and diagnostics + +For integer output, the filter truncates each finite final value toward zero. It clips the result to the output type's +range if needed. For example, an int8 result of 127.75 becomes 127 without clipping, while 128 clips to 127. The filter +reports the total number of clipped values in one warning. + +If the calculation produces NaN or infinity, integer output fails. One error gives the number of nonfinite results, +the output type, and the flat index if exactly one value was found. If conversion stops early, the diagnostics identify +partial counts. A block containing a rejected result is skipped. Completed blocks can remain in the output. + +Floating-point output retains NaN and infinity. A double value just above the largest finite float32 magnitude can +round back to that magnitude. At or beyond the overflow midpoint, it rounds to infinity with the same sign. + +### Migration and downstream use + +Review clipping warnings after updating a saved pipeline. Earlier versions could produce an invalid integer result +when the smoothed value exceeded the output type's range. Clipping can change later thresholding and segmentation. +Use floating-point input if you need fractional or nonfinite output. Intermediate values still have float32 precision. -Each recurrence explicitly materializes its result as `float32` before the next axis, and the terminal plane is cast back to the input type. Three-dimensional working memory is bounded by a fixed number of image planes plus a Z slab whose combined buffers target at most 64 MiB; one XZ row is the indivisible minimum. The single full-volume intermediate adopts an out-of-core endpoint's format. Two-dimensional disk-backed execution uses only plane buffers and therefore creates no full-volume scratch array. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/SqrtImageFilter.md b/src/Plugins/NXImageProcessing/docs/SqrtImageFilter.md index be2b53055c..a1254d74b6 100644 --- a/src/Plugins/NXImageProcessing/docs/SqrtImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/SqrtImageFilter.md @@ -1,14 +1,56 @@ # Sqrt Image Filter -Computes the square root of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `sqrt(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Sqrt Image Filter. +Computes the square root, `sqrt(x)`, of each image value. The filter applies the same operation to each component and preserves the array's tuple and component shapes. + +Use finite nonnegative values to obtain finite results. The output has the square root of the input units. For example, input in squared length units produces output in length units. Dimensionless input produces dimensionless output. The transform alone does not supply a physical calibration. + +### Output Type and Precision + +Preflight and execution use the following output types: + +| Input type | Output type | +|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float64 | +| float32 | float32 | +| float64 | float64 | + +The calculation uses float64 precision. Integer input produces float64 output because a square root usually has a fractional part. For example, `sqrt(0) = 0`, `sqrt(4) = 2`, and `sqrt(2)` is approximately 1.4142135623730951. This is a mathematical square root, rather than an integer-root operation that discards the fractional part. Float32 input retains float32 output and its usual rounding. + +Converting int64 or uint64 input to float64 can round the input before the square root is calculated. Nearby large integers can therefore produce the same result. Float64 output avoids an additional rounding step to float32; it does not make every 64-bit integer transform exact. For example, the float64 result for `sqrt(INT64_MAX)` is approximately 3037000499.97605. Its representation error is about 0.000000208, compared with about 52 for float32. + +Each output value from integer input occupies 8 bytes. Compared with the former same-type output, this uses 8, 4, 2, or 1 times the storage for 8-, 16-, 32-, or 64-bit input, respectively. These factors describe array values and exclude storage metadata and compression. + +### Zero, Negative, and Nonfinite Values + +The filter retains ordinary floating-point behavior: + +| Input value | Output value | +|---|---| +| Positive finite value | Positive finite square root | +| Positive zero | Positive zero | +| Negative floating zero | Negative zero | +| Negative finite value | NaN (not a number) | +| Negative infinity | NaN | +| Positive infinity | Positive infinity | +| NaN | NaN | + +The filter does not clamp negative values to zero. Positive subnormal values, which are smaller than the smallest normal floating-point value, have positive square roots. Negative signed integer input produces a representable NaN in the float64 output. + +### Existing Pipelines + +Integer input now produces float64 output. Earlier same-type integer output discarded fractional results; `sqrt(2)` became 1. Update downstream filters that require integer arrays. Recheck thresholds that depended on integer quantization. For valid nonnegative input, the direct zero/nonzero status is preserved: zero stays zero, and positive input stays positive. + +Handle NaN and infinity explicitly before range calculations or conversion to integer. An unchecked conversion back to integer can reintroduce unsafe behavior. + +## Algorithm + +This is an ITK-free implementation of the legacy ITK Sqrt Image Filter. It uses the existing pointwise traversal for resident and disk-backed arrays. Resident storage retains the direct route when available. The buffered route uses a default 64 MiB transfer-scratch target, with a minimum of one complete storage slab across the trailing tuple dimensions. For Z/Y/X tuple order, this can be an XY slice. A slab can exceed the target or cover the whole array. Bulk store reads and writes are serial; parallel calculations use owned buffers. Sqrt adds no separate full-volume scratch array. Cancellation and storage failures follow the shared pointwise execution path. ![](Images/SqrtImageFilter.png) @@ -16,6 +58,8 @@ Computes `sqrt(x)` for every pixel. ITK-free, out-of-core-capable reimplementati ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Square Root Transmission*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/SquareImageFilter.md b/src/Plugins/NXImageProcessing/docs/SquareImageFilter.md index 394dd030a2..845d697a80 100644 --- a/src/Plugins/NXImageProcessing/docs/SquareImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/SquareImageFilter.md @@ -1,21 +1,65 @@ # Square Image Filter -Computes the square of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `x * x` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Square Image Filter. +Computes `x * x` for each value in the selected image cell array. The output keeps the input tuple and component shapes. Each component is squared separately. The output has the square of the input units; for example, an input in metres gives an output in square metres. Dimensionless input remains dimensionless. + +### Output types and exact integer results + +The filter widens 8-, 16- and 32-bit integers by one native width. It multiplies integers in the output integer type, without an intermediate floating-point conversion. + +| Input type | Output type | +|---|---| +| int8 | int16 | +| uint8 | uint16 | +| int16 | int32 | +| uint16 | uint32 | +| int32 | int64 | +| uint32 | uint64 | +| int64 | int64 | +| uint64 | uint64 | +| float32 | float32 | +| float64 | float64 | + +For example, *16* gives the exact integer result *256*, and *4097* gives *16785409*. The largest uint32 input, *4294967295*, gives the exact uint64 result *18446744065119617025*. + +The 64-bit integer output types have these input limits: + +- int64: *-3037000499* through *3037000499*, inclusive. +- uint64: *0* through *4294967295*, inclusive. + +An input outside these limits produces an error before integer multiplication. The error identifies the input array, the offending value and the allowed bound. The filter checks the signed limits directly, including the int64 minimum value. It does not saturate the output or change an overflowing integer result to a floating-point type. + +### Floating-point results -![](Images/SquareImageFilter.png) +Floating-point inputs keep their type. Squaring either signed zero gives positive zero. NaN gives NaN, and either infinity gives positive infinity. A result above the output finite range gives positive infinity. Small results can become subnormal values or positive zero through underflow. Floating-point results have the precision of their output type; they are not exact integer substitutes. + +### Input and downstream guidance + +Select an image geometry and a numeric cell array that belongs to that geometry. The array must have one tuple per image cell. An image reader or an earlier image-processing filter can supply this array. + +The widened 8-, 16- and 32-bit integer output uses twice the input array's storage. Check any later filter or export that requires a specific integer width. Exact integer comparisons can also differ from older results that lost low bits through floating-point arithmetic. + +For larger 64-bit integer inputs, explicitly convert the input array to float64 before this filter if approximate squares are acceptable. The conversion and floating-point multiplication can lose integer units. Choose that conversion deliberately rather than narrowing the exact integer output to fit a downstream width. + +## Algorithm + +The filter uses the existing pointwise traversal for both in-memory and disk-backed arrays. In-memory arrays use the resident route when available. Other stores use serial bulk reads and writes, with arithmetic on owned resident buffers. The generic traversal targets a 64 MiB scratch budget but requires at least one storage slab; a slab can exceed that target or cover a thin array. Square adds no separate temporary buffer beyond the existing traversal and scan buffers. + +Only int64 and uint64 inputs require an extra native-integer minimum/maximum scan before multiplication. This adds one complete input read for those types. The scan uses the existing resident or buffered reduction and checks cancellation and read errors. Other types use one pointwise pass. Cancellation and I/O failures follow the filter framework's existing result behavior. A later I/O failure does not guarantee that the output is unchanged. + +![Square image example](Images/SquareImageFilter.png) % Auto generated parameter table will be inserted here ## Example Pipelines +`15_Radiography_Intensity_Calibration.d3dpipeline` uses this filter to convert *Transmission* into *Squared Transmission*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/TanImageFilter.md b/src/Plugins/NXImageProcessing/docs/TanImageFilter.md index a9c981012a..fb8bbf3ea2 100644 --- a/src/Plugins/NXImageProcessing/docs/TanImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/TanImageFilter.md @@ -1,19 +1,51 @@ # Tan Image Filter -Computes the tangent of each pixel. - ## Group (Subgroup) NXImageProcessing (Pointwise) ## Description -Computes `tan(x)` for every pixel. ITK-free, out-of-core-capable reimplementation of the legacy ITK Tan Image Filter. +Computes the **tangent**, `tan(x)`, for each input value. The input is an angle in **radians**. The output is a signed, dimensionless response. Each component is processed separately. The output keeps the input tuple and component shapes. + +### Output Type and Precision + +| Input type | Output type | Output bytes per value | +|---|---|---| +| int8, uint8, int16, uint16, int32, uint32, int64, uint64 | float32 | 4 | +| float32 | float32 | 4 | +| float64 | float64 | 8 | + +Integer input needs floating output because an integer angle can produce a signed, fractional tangent. For example, `tan(1)` is about 1.55740772 and `tan(2)` is about -2.18503986. An unsigned input does not imply a positive tangent. Integer output would discard fractions and cannot safely store all negative responses. + +The input is converted to double precision before the tangent calculation. The result is then rounded to the output type. Float32 has about 7 significant decimal digits; float64 has about 16. The selected float32 output for integer input uses half the bytes of float64. A representation study across all int8 and uint8 arguments found a worst relative rounding error of about `5.63e-8`. This measures output rounding only. It is not a bound on the tangent calculation or wider integer inputs. + +Integer arguments above `2^53` in magnitude can lose whole integer units when converted to double. For example, `9007199254740993` becomes `9007199254740992` before evaluation. This can change the tangent's phase and result. Float64 output would not recover that lost input precision. + +### Numeric Limits + +- Positive and negative zero keep their signs. +- NaN (not a number), positive infinity, and negative infinity produce NaN. +- Finite angles near a **pole**, where the mathematical tangent is undefined, are evaluated without a cutoff or clamp. Poles occur at `pi/2 + k*pi` radians for integer `k`. +- The nearest float32 and float64 values to `pi/2` lie on opposite sides of that pole. Their results are about `-2.2877332e7` and `1.6331239353e16`, respectively. Both are finite. Small changes in a stored angle near a pole can change the result's sign and magnitude. +- If a finite double result exceeds the float32 finite range, it is stored as infinity with the result's sign. NaN, infinity, and signed zero keep their floating behavior during output conversion. + +### Storage and Downstream Use + +For integer input, the 4-byte output uses 4, 2, 1, or 0.5 times the bytes of an 8-, 16-, 32-, or 64-bit input value. Floating input keeps its existing output width. + +Existing pipelines with integer input now receive float32 responses. Earlier integer output discarded fractions: for example, `tan(3)` became zero in signed integer output instead of about -0.14254654. Review thresholds and zero/nonzero masks that depended on this truncation. Filters that accept only integer arrays can reject the new output type. Near-pole responses can dominate extrema and normalization. Before converting output back to integers, handle nonfinite values and check the destination range; an unchecked conversion can reintroduce unsafe behavior. + +## Algorithm + +The filter evaluates each value independently through the existing pointwise traversal. Resident arrays use direct memory views. Disk-backed arrays use serial bulk reads and writes through working batches. Transfer buffers target a combined 64 MiB, but each batch holds at least one complete trailing-dimensional slab, such as an XY slice for a Z/Y/X tuple shape. A slab can exceed this target or contain the whole array. Parallel calculation uses owned buffers. The filter adds no separate Tan-specific full-array calculation buffer. The output belongs to the input geometry. An explicit input storage format also applies to the output. When the input uses automatic storage, the storage resolver uses the output type and size. A uint8 image in memory can therefore produce a float32 array large enough to use disk storage. % Auto generated parameter table will be inserted here ## Example Pipelines +`16_Phase_and_Angle_Field_Transforms.d3dpipeline` uses this filter to convert *Phase Radians* into *Tangent*. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/docs/ThresholdMaximumConnectedComponentsImageFilter.md b/src/Plugins/NXImageProcessing/docs/ThresholdMaximumConnectedComponentsImageFilter.md index a42644f2e2..8a2111cbb0 100644 --- a/src/Plugins/NXImageProcessing/docs/ThresholdMaximumConnectedComponentsImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/ThresholdMaximumConnectedComponentsImageFilter.md @@ -1,40 +1,48 @@ # Threshold Maximum Connected Components Image Filter -Finds the threshold value of an image based on maximizing the number of objects in the image that are larger than a given minimal size. - ## Group (Subgroup) NXImageProcessing (Segmentation) ## Description -This filter is an iterative auto-thresholding method: it bisection-searches for the threshold value that **maximizes** the number of connected components (objects) in the image that are at least **Minimum Object Size In Pixels** in size, then outputs the binary threshold at that value. This method is based on Topological Stable State Thresholding and is particularly effective when there are a large number of objects in a microscopy image. +This filter selects a lower intensity threshold with a **component-count heuristic**: it compares the numbers of connected regions at two candidate thresholds and narrows the interval. It does not guarantee a global maximum. The input is a scalar cell array in the selected image geometry. Integer and floating inputs produce the same fixed **uint8** output type, with one byte per pixel or voxel. Output values are **Inside Value** and **Outside Value**; the threshold itself is not saved as an image. + +A pixel is inside when its native intensity is at or above the selected lower threshold and at or below **Upper Boundary**. Both bounds are inclusive. The search uses **face connectivity**, which joins pixels through shared edges in 2-D or shared faces in 3-D. Diagonal contact alone does not join regions. + +### Search score and stopping units -At each step of the search, the image is binary-thresholded at a candidate threshold value (paired with the fixed **Upper Boundary**), the resulting foreground is labeled into connected components (face connectivity only), and the number of components at least **Minimum Object Size In Pixels** in size is counted. The bisection converges on the threshold value that maximizes this count. +The score counts connected components of the would-be **nonzero output**, including components whose size is exactly **Minimum Object Size In Pixels**. This parameter counts pixels or voxels and defaults to *0*. Image spacing does not change the count or the two-intensity-unit stopping rule. Minimum Object Size In Pixels changes the search score. Small objects can remain in the final output. -The input array must be single-component (scalar) and may be **any scalar type** (integer or floating point). The output is a fixed **uint8** binary image (**Inside Value** / **Outside Value**) regardless of the input element type. This is an ITK-free, out-of-core-capable reimplementation of the legacy ITK Threshold Maximum Connected Components Image Filter, and matches it exactly (byte-identical binary output). +**Inside Value** defaults to *1* and **Outside Value** defaults to *0*. Both are dimensionless uint8 values. With these defaults, the score counts in-band regions. Inside 0/Outside 1 scores the complement. If both values are nonzero, all pixels participate as foreground. If both are zero, none participate. A nonzero Outside Value can connect regions that would otherwise be separate. -### Minimum Object Size In Pixels +The search stops when the interval is at most **2 input-intensity units** wide. This is an absolute rule for integers and floating inputs. It is not a relative tolerance or a measure of segmentation accuracy. For example, normalized values spanning 0 to 1 skip the search. For the values `[0,1,0,1]` at the default Inside and Outside settings, the integer midpoint rounds toward the lower endpoint to 0 and produces `[1,1,1,1]`. Floating-point input has midpoint 0.5 and produces `[0,1,0,1]`. In both cases the search stops before scoring alternate candidates. Scaling the intensities can change the selected mask. The right candidate wins only if its score is strictly greater; ties select the left candidate. -Set the minimum pixel area used to count objects on the image. Only objects that have a pixel area greater than or equal to the minimum pixel area are counted as an object in the optimization portion of this filter. Essentially, it eliminates noise from being counted as an object. The default value is zero. +For floating input, native rounding can repeat the complete search state while the interval is still wider than 2. The filter stops, retains the candidate selected by the normal comparison, and issues one precision warning. It does not choose a different endpoint or perform an exhaustive search. ### Upper Boundary -This class automatically calculates the lower threshold boundary. The upper threshold boundary, inside value, and outside value can be defined by the user, however the standard values are used as default if not set by the user. Default is 65536.0. +Upper Boundary is a Float64 parameter in input-intensity units. Its default is *65536*. Integer input truncates an in-range fractional request toward zero. Thus an unsigned request of *-0.5* becomes *0*; *-1* requests an empty native band. A signed request that truncates to the native minimum remains valid. In-range Float64-to-float32 conversion retains ordinary native rounding. -### Inside Value +A finite request above the native maximum, or positive infinity, selects the exact native maximum before conversion. For uint8, the default therefore becomes *255*. int64/uint64 limits are checked before casting; a rounded Float64 value at 2^63 or 2^64 is never cast into the corresponding integer. Float64 cannot express every exact 64-bit integer cutoff above 2^53, even though image bounds and integer search candidates remain exact native integers. -The value assigned to voxels at or above the calculated threshold (and at or below the Upper Boundary). Default is 1. +NaN is an invalid Upper Boundary. Pipeline JSON stores finite cutoffs as numbers and signed infinities as the strings `"+Infinity"` and `"-Infinity"`. An older file with a null cutoff has lost its original value. Enter the intended cutoff before loading that pipeline again. A finite request below the native range after integer truncation, a cap below the finite image minimum, or negative infinity produces an empty band. The filter skips search, fills Outside Value and issues an empty-band warning. It does not clamp a low cutoff upward or treat this output as an optimized threshold. Structurally valid zero-length input remains empty and is distinct from a nonempty all-nonfinite image. -### Outside Value +### Input with NaN or infinity -The value assigned to voxels outside the calculated threshold range. Default is 0. +Finite pixels set the native search bounds. A NaN or infinity lies outside the finite band and receives **Outside Value**. If there are no finite pixels, every output pixel receives **Outside Value**. A nonzero Outside Value can connect regions or make the entire image foreground. Clean invalid intensities upstream before relying on object counts, fractions or boundaries. + +### Numeric migration + +The starting midpoint now includes the image minimum, and interval arithmetic avoids native integer overflow. This corrects offset, negative and wide-range cases. For input `[100,102]`, a nonbinding cap and Inside 1/Outside 0, the old starting threshold 1 gave mask `[1,1]`; the corrected midpoint 101 gives `[0,1]`. The output type is unchanged, but segmentation and downstream measurements can change. Constant images use their actual constant as the threshold. ## Algorithm -The filter performs a bisection search over candidate lower thresholds. For each candidate it raster-scans the image, encodes foreground runs, joins connected runs with union-find, and counts components meeting the minimum-size requirement. The union-find and component-size tables contain one entry per provisional object run. After selecting the threshold, the filter writes the requested binary inside and outside values in bounded chunks. +One initial scan collects the native minimum and maximum of the finite pixels. Existing resident spans are reduced directly; other stores are read serially into bounded owned buffers, whose independent blocks can be reduced in parallel. The filter does not create a full-image finite mask or convert the integer image to Float64. Initial, left and right integer midpoint calculations retain native 64-bit distinctions and their left/right rounding rules. + +Each iteration performs two connected-component scans and compares their scores. 3-D counting reads budget-derived bands with a one-plane fallback and retains current/previous run planes. True 2-D counting uses bounded row blocks; very wide rows use bounded X tiles and provisional scratch, using disk storage for out-of-core input. These are shared traversal routes for resident and disk-backed arrays, with serial store I/O and stable owned compute buffers. Final classification and all-Outside fills use bounded writes. -For images with more than one Z plane, each connected-component scan reads one Z plane at a time and retains the current and previous plane's run descriptions. For a true two-dimensional image (`Z=1`), a checked scheduler uses at most 64 MiB of full-width row blocks while retaining only two run-encoded rows. Exceptionally wide rows use bounded X tiles and a provisional label image to reconnect neighboring tiles and rows. With an out-of-core input, that scratch uses the registered raw temporary-record store when available and otherwise falls back to the selected array storage format. This keeps cell-scale state disk-backed for out-of-core inputs while preserving the exact threshold search, connectivity, and component-count results. +Union-find and size tables still grow with the number of provisional foreground runs. Bounded staging is not a bound on total RAM. A provisional run ID beyond uint32 capacity, an allocation/addressability failure, or an I/O error stops execution. Search changes can change the number of full-image count passes and therefore CPU time and disk I/O. No fixed runtime improvement or legacy byte-parity guarantee is implied. % Auto generated parameter table will be inserted here diff --git a/src/Plugins/NXImageProcessing/docs/WriteImageFilter.md b/src/Plugins/NXImageProcessing/docs/WriteImageFilter.md index 34055a068a..3cf6b422e4 100644 --- a/src/Plugins/NXImageProcessing/docs/WriteImageFilter.md +++ b/src/Plugins/NXImageProcessing/docs/WriteImageFilter.md @@ -6,43 +6,39 @@ NXImageProcessing (IO) ## Description -Writes a 2D image or a series of 2D slices from a 3D **Image Geometry**. This **Filter** does not depend on ITK. It uses stb_image_write for PNG/JPEG/BMP files, libtiff for TIFF files, and zlib for compressed MHA files. - -The following output file formats are supported: - -- PNG (via stb) -- JPEG / JPG (via stb) -- BMP (via stb) -- TIFF / TIF (via libtiff) -- MHA / MetaImage (compressed, attached pixel data) +Writes a 2D image or a series of 2D slices from a 3D **Image Geometry**. +The filter supports PNG, JPEG, BMP, TIFF, and MHA. MHA stores compressed pixels in the same file. ### Pixel Data Type Support By Format -When *Create Color Table* is **disabled**, the filter writes the **Data Array**'s own pixel values directly, and the chosen output file format constrains which data types can be written. This is validated during preflight, so an unsupported combination is reported as an error before the filter runs rather than failing partway through writing: +With *Create Color Table* off, the file format must support the input array's type and number of components. The filter +checks both during preflight. -| Output Format | Backend | Supported Data Types | -|----------------------------|---------|----------------------------| -| PNG / JPG / JPEG / BMP | stb | uint8 | -| TIFF / TIF | libtiff | uint8, uint16, float32 | -| MHA | zlib | int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, float64 | +| Output format | Supported pixel types | +| --- | --- | +| PNG, JPG, JPEG, BMP | uint8 | +| TIF, TIFF | uint8, uint16, float32 | +| MHA | int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, float64 | -For example, writing a float32 array directly to a `.png` file fails preflight, since PNG supports only uint8 pixel data. The same array can be written to TIFF or MHA. If PNG is required, enable *Create Color Table* to write a uint8 RGB image. +For example, write raw float32 data to TIFF or MHA. To write single-component float32 data as PNG, enable *Create Color +Table* to produce a uint8 RGB image. -MHA output supports the component counts accepted by the ITK writer: 1, 2, 3, 4, 10, 11, and 36. MHA files also store the origin and spacing for the selected output plane. Other formats use only the component counts supported by their backend. +MHA supports 1, 2, 3, 4, 10, 11, or 36 components per pixel. It stores the origin and spacing for the selected plane. +Other formats have their own component limits. -If an existing pipeline contains the ITK Write Image filter UUID, the NXImageProcessing plugin maps that UUID to this **Filter** when ITKImageProcessing is not available. When ITKImageProcessing is available, the original ITK **Filter** remains registered. +A saved pipeline can refer to the original ITK Write Image filter. The pipeline uses that filter when ITKImageProcessing +is available. Otherwise, NXImageProcessing uses this filter in its place. -If the input array represents a 3D volume, the filter will output a series of slices along one of the orthogonal axes. The options are to produce XY slices along the Z axis, XZ slices along the Y axis, or YZ slices along the X axis. The output files will be numbered sequentially starting at the *Index Offset* and ending at *Index Offset + (dim - 1)* for the chosen axis. For example, if the Z axis has 117 dimensions and *Index Offset* is 0, 117 XY image files will be produced and numbered 000 through 116. If the volume produces only a single slice, no index is appended and the file is written with exactly the user-specified name. - -Writes are performed through an `AtomicFile`, so partially-written slices from an aborted run will not corrupt existing output files. +Each slice is written to a temporary file before it replaces the destination. An export that stops partway through can +leave earlier slices in the output folder. ### Plane -The *Plane* parameter controls which orthogonal plane is used when writing a 3D volume as a series of 2D image slices: +For a 3D volume, *Plane* selects the direction of the slice series. **XY** steps along Z, **XZ** along Y, and **YZ** +along X. -- **XY [0]**: Write image slices along the XY plane (normal to Z axis). -- **XZ [1]**: Write image slices along the XZ plane (normal to Y axis). -- **YZ [2]**: Write image slices along the YZ plane (normal to X axis). +The first slice uses *Index Offset*. For example, 117 XY slices with an offset of 0 are numbered 000 to 116. A single +slice uses the specified filename. ### Index Formatting @@ -62,18 +58,28 @@ This option only affects the written image files. The input Image Geometry and i ### Inline Color Table (Optional) -Enabling *Create Color Table* converts a single-component **Data Array** to an RGB image using a selected color preset immediately before writing, so there is no need to run the Create Color Map **Filter** as a separate step beforehand. The results are identical to running Create Color Map followed by Write Image. +*Create Color Table* is off by default. When enabled, the filter uses *Select Preset...* to map any single-component +numeric input to uint8 RGB. An input with more than one component causes a preflight error. + +All finite values set the color range, including finite values excluded by a mask. If every finite value is equal, +that value maps to the first color in the preset. Different values can have the same RGB color. -- *Select Preset...* chooses the color preset (for example grayscale, rainbow, or jet) that is applied to the array's values. -- When *Create Color Table* is enabled, the **Input Image Data Array** must be a single-component numeric array, but it may be **any** numeric type: int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32, or float64. This is wider than the type restrictions that apply when writing an array's raw pixel values directly (see *Pixel Data Type Support By Format* above), since color-table mode always produces a uint8 RGB image regardless of the input array's type. If the selected array has more than one component, the filter will fail during preflight. -- Colorization uses bounded source groups and writes one RGB slice at a time. The filter never holds a full RGB volume in memory. The filter first computes the minimum and maximum input values while ignoring the mask. It uses this range to normalize each voxel against the preset's control points. -- If every voxel in the input array has the same value (a constant array), every voxel normalizes to the same value and is colored using the preset's first control color. +For wide integer data, the writer keeps differences as exact integers before it computes the color fraction. [Create Color Map](../SimplnxCore/CreateColorMapFilter.md) can give different colors for the same preset. +For example, with the *Grayscale* preset, the three largest int64 values map to black, middle gray and white in +Write Image. Create Color Map converts those three input values to the same floating-point number and maps them all to black. -*Use Mask Array* is a separate, top-level toggle (it is not nested under *Create Color Table*) that assigns a fixed color to "bad" voxels instead of coloring them from the preset: +#### NaN and infinity in the input image -- *Mask Array* selects a boolean or uint8, single-component array that marks each **Voxel** as good (*true* / non-zero) or bad (*false* / zero). -- *Masked Color (RGB)* is the RGB triplet written for any voxel marked bad by the mask. -- The mask is only applied when *Create Color Table* is also enabled. If *Create Color Table* is disabled, *Use Mask Array* and *Masked Color (RGB)* have no effect, since the filter writes the raw pixel data unchanged. +**Check the input before you interpret a color image.** An unmasked NaN or infinity receives the first color in the +preset, the same color as the finite minimum. If every pixel is NaN or infinity, every unmasked pixel receives that color. These pixels do not produce a warning. To distinguish them from valid measurements, supply a +mask with a distinct *Masked Color (RGB)*. To preserve the original floating-point values, turn off *Create Color +Table* and select a format that supports the input type. + +#### Mask Array + +Enable *Use Mask Array* with *Create Color Table* to give excluded pixels the *Masked Color (RGB)*. Use a +single-component `bool` or `uint8` mask with the same `[Z, Y, X]` tuple shape as the image array. +Every false or zero mask value selects the mask color, including at pixels that contain NaN or infinity. ### Add Physical Scale Bar (Optional) @@ -99,17 +105,18 @@ the padded size. ### Required Input Sources -- **Image Data** -- a `uint8` (or `uint16`/`float32` for TIFF) **Cell Data** array on an **Image Geometry**, produced by an image reader such as [Read Image](ReadImageFilter.md) / [Read Images [3D Stack]](ReadImageStackFilter.md), or by any upstream image-processing filter. +Select a **Cell Data** array on an **Image Geometry**. You can use an image reader such as [Read Image](ReadImageFilter.md) +or [Read Images [3D Stack]](ReadImageStackFilter.md), or an array from an upstream image-processing filter. ## Algorithm -The filter selects an algorithm from the storage type of the input **Data Array** and the optional mask. Both algorithms produce the same files and preserve the same cancellation, flip, color-table, scale-bar, and atomic-write behavior. +The filter selects an algorithm from the storage type of the input **Data Array** and the optional mask. Both algorithms compute the same finite color range and apply the selected preset and mask before writing each slice. ### In-Core Path -`WriteImageDirect` runs when all applicable arrays use in-memory storage. The algorithm uses the original per-slice extraction path. This path preserves the lowest measured in-memory execution time. +`WriteImageDirect` runs when all applicable arrays use in-memory storage. -The algorithm reads one selected XY, XZ, or YZ slice. It converts the slice to the required byte layout and writes the slice before it reads the next slice. Color-table output first scans the scalar array in fixed pages to calculate the normalization range. It then colorizes one source slice and its optional mask at a time. +The algorithm reads one selected XY, XZ, or YZ slice. It converts the slice to the required byte layout and writes the slice before it reads the next slice. Color-table output scans the scalar array in pages of up to 1 MiB to get the range. It then reads one source slice and its optional mask at a time. ### Out-of-Core Path @@ -117,12 +124,16 @@ The algorithm reads one selected XY, XZ, or YZ slice. It converts the slice to t XY slices match the default out-of-core Z-slice chunk shape. The algorithm reads one XY slice per extent to prevent unnecessary chunk scatter. For XZ and YZ output, the algorithm groups adjacent output slices into a source slab. The slab size uses an active working-memory reservation with a preferred limit of 64 MiB. If one slice exceeds this limit, the algorithm processes one slice at a time. -The algorithm keeps the grouped source slab and one output slice in memory. A color-table mask shares the same slab plan. The algorithm performs store I/O on one thread and checks cancellation between output slices. +The algorithm keeps the grouped source slab and one output slice in memory. A color-table mask shares the same slab plan. The scalar range scan finishes before the algorithm allocates the slab. The algorithm performs store I/O on one thread and checks cancellation between output slices. + +The filter does not allocate a complete RGB volume. It still requires a complete selected 2D RGB slice. A scale bar can require a second padded slice and a separate band. The image codec can allocate more memory for that slice. The source-buffer reservation is not a limit on total process memory. % Auto generated parameter table will be inserted here ## Example Pipelines +`17_Scientific_Volume_Interoperability.d3dpipeline` exports MHA image data and writes a NIfTI volume as a series of TIFF slices. + ## License & Copyright Please see the description file distributed with this plugin. diff --git a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.d3dpipeline b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.d3dpipeline index f0c7939be3..e21a9ee96f 100644 --- a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.d3dpipeline +++ b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.d3dpipeline @@ -284,7 +284,11 @@ "value": "Pore Labels", "version": 1 }, - "parameters_version": 1 + "parameters_version": 2, + "provisional_label_limit_handling_index": { + "value": 0, + "version": 1 + } }, "comments": "Assign one label to each face-connected pore.", "filter": { diff --git a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.md b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.md index ea05d3e74a..b39e30eaaa 100644 --- a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.md +++ b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.md @@ -216,6 +216,7 @@ Key parameters: - `input_image_data_path`: `"AM XCT/Cell Data/Closed Pore Mask"` - `input_image_geometry_path`: `"AM XCT"` - `output_array_name`: `"Pore Labels"` +- `provisional_label_limit_handling_index`: `0` Resolved inputs: diff --git a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.yaml b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.yaml index de6b515054..c3edc0fa38 100644 --- a/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.yaml +++ b/src/Plugins/NXImageProcessing/pipelines/05_AM_XCT_Porosity_Segmentation/05_AM_XCT_Porosity_Segmentation.yaml @@ -285,7 +285,8 @@ "fully_connected": false, "input_image_data_path": "AM XCT/Cell Data/Closed Pore Mask", "input_image_geometry_path": "AM XCT", - "output_array_name": "Pore Labels" + "output_array_name": "Pore Labels", + "provisional_label_limit_handling_index": 0 } }, { diff --git a/src/Plugins/NXImageProcessing/pipelines/06_AM_Powder-Bed_Layer_Inspection/06_AM_Powder-Bed_Layer_Inspection.d3dpipeline b/src/Plugins/NXImageProcessing/pipelines/06_AM_Powder-Bed_Layer_Inspection/06_AM_Powder-Bed_Layer_Inspection.d3dpipeline index 348af15e43..825d3e9625 100644 --- a/src/Plugins/NXImageProcessing/pipelines/06_AM_Powder-Bed_Layer_Inspection/06_AM_Powder-Bed_Layer_Inspection.d3dpipeline +++ b/src/Plugins/NXImageProcessing/pipelines/06_AM_Powder-Bed_Layer_Inspection/06_AM_Powder-Bed_Layer_Inspection.d3dpipeline @@ -275,10 +275,10 @@ "value": 0, "version": 1 }, - "parameters_version": 1, + "parameters_version": 2, "upper_boundary": { "value": 255.0, - "version": 1 + "version": 2 } }, "comments": "Select an automatic threshold that retains many meaningful layer anomalies.", diff --git a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.d3dpipeline b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.d3dpipeline index 30568d57a6..a9eef4253d 100644 --- a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.d3dpipeline +++ b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.d3dpipeline @@ -183,6 +183,14 @@ "value": 0, "version": 1 }, + "mask_array_path": { + "value": "", + "version": 1 + }, + "masked_label": { + "value": 255, + "version": 1 + }, "number_of_histogram_bins": { "value": 128, "version": 1 @@ -195,11 +203,15 @@ "value": "Otsu Regions", "version": 1 }, - "parameters_version": 1, + "parameters_version": 2, "return_bin_midpoint": { "value": false, "version": 1 }, + "use_mask_array": { + "value": false, + "version": 1 + }, "valley_emphasis": { "value": true, "version": 1 @@ -281,7 +293,11 @@ "value": "Track Labels", "version": 1 }, - "parameters_version": 1 + "parameters_version": 2, + "provisional_label_limit_handling_index": { + "value": 0, + "version": 1 + } }, "comments": "Label the melt pool and separated spatter regions.", "filter": { diff --git a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.md b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.md index ac78e5a8e5..597bb81fe2 100644 --- a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.md +++ b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.md @@ -143,10 +143,13 @@ Key parameters: - `input_image_data_path`: `"Melt Pool Image/Cell Data/Sigmoid Contrast"` - `input_image_geometry_path`: `"Melt Pool Image"` - `label_offset`: `0` +- `mask_array_path`: `""` +- `masked_label`: `255` - `number_of_histogram_bins`: `128` - `number_of_thresholds`: `2` - `output_array_name`: `"Otsu Regions"` - `return_bin_midpoint`: `false` +- `use_mask_array`: `false` - `valley_emphasis`: `true` Resolved inputs: @@ -198,6 +201,7 @@ Key parameters: - `input_image_data_path`: `"Melt Pool Image/Cell Data/Track Mask"` - `input_image_geometry_path`: `"Melt Pool Image"` - `output_array_name`: `"Track Labels"` +- `provisional_label_limit_handling_index`: `0` Resolved inputs: diff --git a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.yaml b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.yaml index ebee4e1ad1..9cf6e5a8ab 100644 --- a/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.yaml +++ b/src/Plugins/NXImageProcessing/pipelines/07_AM_Melt-Pool_and_Track_Inspection/07_AM_Melt-Pool_and_Track_Inspection.yaml @@ -196,10 +196,13 @@ "input_image_data_path": "Melt Pool Image/Cell Data/Sigmoid Contrast", "input_image_geometry_path": "Melt Pool Image", "label_offset": 0, + "mask_array_path": "", + "masked_label": 255, "number_of_histogram_bins": 128, "number_of_thresholds": 2, "output_array_name": "Otsu Regions", "return_bin_midpoint": false, + "use_mask_array": false, "valley_emphasis": true } }, @@ -262,7 +265,8 @@ "fully_connected": true, "input_image_data_path": "Melt Pool Image/Cell Data/Track Mask", "input_image_geometry_path": "Melt Pool Image", - "output_array_name": "Track Labels" + "output_array_name": "Track Labels", + "provisional_label_limit_handling_index": 0 } }, { diff --git a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.d3dpipeline b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.d3dpipeline index 6d51681ed0..9e7e6295e9 100644 --- a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.d3dpipeline +++ b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.d3dpipeline @@ -273,7 +273,11 @@ "value": "Marker Labels", "version": 1 }, - "parameters_version": 1 + "parameters_version": 2, + "provisional_label_limit_handling_index": { + "value": 0, + "version": 1 + } }, "comments": "Assign a unique label to each watershed marker.", "filter": { @@ -300,6 +304,10 @@ "value": true, "version": 1 }, + "marker_id_conversion_handling_index": { + "value": 0, + "version": 1 + }, "marker_image_data_path": { "value": "Powder Particles/Cell Data/Marker Labels", "version": 1 @@ -308,7 +316,7 @@ "value": "Particle Labels", "version": 1 }, - "parameters_version": 1 + "parameters_version": 2 }, "comments": "Grow the particle markers across the gradient surface without merging touching particles.", "filter": { diff --git a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.md b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.md index 7b2fac2d1d..ddc72fc608 100644 --- a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.md +++ b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.md @@ -194,6 +194,7 @@ Key parameters: - `input_image_data_path`: `"Powder Particles/Cell Data/Marker Mask"` - `input_image_geometry_path`: `"Powder Particles"` - `output_array_name`: `"Marker Labels"` +- `provisional_label_limit_handling_index`: `0` Resolved inputs: @@ -216,6 +217,7 @@ Key parameters: - `input_image_data_path`: `"Powder Particles/Cell Data/Particle Gradient"` - `input_image_geometry_path`: `"Powder Particles"` - `mark_watershed_line`: `true` +- `marker_id_conversion_handling_index`: `0` - `marker_image_data_path`: `"Powder Particles/Cell Data/Marker Labels"` - `output_array_name`: `"Particle Labels"` diff --git a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.yaml b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.yaml index 65eaa6fe09..ca2159ff07 100644 --- a/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.yaml +++ b/src/Plugins/NXImageProcessing/pipelines/08_Powder_Particle_Watershed_Segmentation/08_Powder_Particle_Watershed_Segmentation.yaml @@ -262,7 +262,8 @@ "fully_connected": true, "input_image_data_path": "Powder Particles/Cell Data/Marker Mask", "input_image_geometry_path": "Powder Particles", - "output_array_name": "Marker Labels" + "output_array_name": "Marker Labels", + "provisional_label_limit_handling_index": 0 } }, { @@ -291,6 +292,7 @@ "input_image_data_path": "Powder Particles/Cell Data/Particle Gradient", "input_image_geometry_path": "Powder Particles", "mark_watershed_line": true, + "marker_id_conversion_handling_index": 0, "marker_image_data_path": "Powder Particles/Cell Data/Marker Labels", "output_array_name": "Particle Labels" } diff --git a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.d3dpipeline b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.d3dpipeline index febd6733c1..7d0895ef35 100644 --- a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.d3dpipeline +++ b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.d3dpipeline @@ -398,7 +398,11 @@ "value": "Object Labels", "version": 1 }, - "parameters_version": 1 + "parameters_version": 2, + "provisional_label_limit_handling_index": { + "value": 0, + "version": 1 + } }, "comments": "Assign one label to each mask object.", "filter": { diff --git a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.md b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.md index f7e66e94c8..a365b94a4b 100644 --- a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.md +++ b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.md @@ -268,6 +268,7 @@ Key parameters: - `input_image_data_path`: `"Binary Mask/Cell Data/Mask"` - `input_image_geometry_path`: `"Binary Mask"` - `output_array_name`: `"Object Labels"` +- `provisional_label_limit_handling_index`: `0` Resolved inputs: diff --git a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.yaml b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.yaml index 7df583e2ed..a0c5557161 100644 --- a/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.yaml +++ b/src/Plugins/NXImageProcessing/pipelines/10_Binary_Mask_Repair_and_Skeletonization/10_Binary_Mask_Repair_and_Skeletonization.yaml @@ -366,7 +366,8 @@ "fully_connected": true, "input_image_data_path": "Binary Mask/Cell Data/Mask", "input_image_geometry_path": "Binary Mask", - "output_array_name": "Object Labels" + "output_array_name": "Object Labels", + "provisional_label_limit_handling_index": 0 } }, { diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AcosImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AcosImageFilter.cpp index 689cdf1475..6b27793a01 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AcosImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AcosImageFilter.cpp @@ -2,6 +2,8 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -78,7 +80,8 @@ IFilter::PreflightResult AcosImageFilter::preflightImpl(const DataStructure& dat auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> AcosImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +92,8 @@ Result<> AcosImageFilter::executeImpl(DataStructure& dataStructure, const Argume const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const AcosOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImage.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImage.hpp index 622334d918..fda5f3cac3 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImage.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImage.hpp @@ -62,7 +62,7 @@ class NXIMAGEPROCESSING_EXPORT WriteImage /** * @brief Writes all slices for the selected plane. - * @return An error if slice extraction, compression, or file output fails. + * @return Warnings and errors from reading image data, encoding slices, or writing files. */ Result<> operator()(); diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageColorUtilities.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageColorUtilities.hpp new file mode 100644 index 0000000000..de6ee22662 --- /dev/null +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageColorUtilities.hpp @@ -0,0 +1,268 @@ +#pragma once + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/DataStructure/AbstractDataStore.hpp" +#include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageTransferResult.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +/** @namespace nx::core::write_image_color + * @brief Contains color safety operations used only by the image writer. + */ +namespace nx::core::write_image_color +{ +struct SliceExtents +{ + usize Width = 0; + usize Height = 0; + usize Count = 0; +}; + +struct ProgressCallbacks +{ + std::function Range; + std::function Rows; +}; + +/** + * @brief Checks the products used by color slice, group and RGB indexes. + * @tparam T Scalar input type. + * @param extents Output width, height, and slice count. + * @param hasMask Whether the source group also holds a mask. + * @return An error for empty dimensions or unrepresentable buffer sizes. + */ +template +Result<> ValidateSize(const SliceExtents& extents, bool hasMask) +{ + const auto& [width, height, slices] = extents; + constexpr usize maximum = std::numeric_limits::max(); + const usize bytesPerValue = sizeof(T) + (hasMask ? std::max(sizeof(bool), sizeof(uint8)) : 0); + if(width == 0 || height == 0 || slices == 0 || width > maximum / height) + { + return MakeErrorResult( + -27030, + fmt::format( + "Write Image color slice dimensions are empty or too large (width {}, height {}, slice count {}, index limit {}). Use positive dimensions whose width times height fits this limit.", width, + height, slices, maximum)); + } + const usize pixels = width * height; + if(pixels > maximum / 3 || pixels > maximum / bytesPerValue || slices > maximum / (pixels * bytesPerValue)) + { + return MakeErrorResult(-27032, fmt::format("Write Image color buffer sizes exceed the supported index range (width {}, height {}, slice count {}, index limit {}). Reduce the image dimensions.", + width, height, slices, maximum)); + } + return {}; +} + +/** + * @struct Range + * @brief Native endpoints and cancellation state from the writer's initial scan. + * @tparam T Scalar input type. + */ +template +struct Range +{ + T Minimum{}; + T Maximum{}; + bool Cancelled = false; +}; + +/** + * @brief Finds finite scalar endpoints across all input pages, including masked pixels. + * If every value is nonfinite, both endpoints remain zero. + * @tparam T Scalar input type. + * @param array Single-component source array. + * @param shouldCancel Stops the scan between pages. + * @param reportRange Synchronous callback after each complete page. + * @return Native range and warnings, cancellation state, or the first scan error. + */ +template +Result> ScanRange(const IDataArray& array, const std::atomic_bool& shouldCancel, const std::function& reportRange) +{ + const auto& store = array.getIDataStoreRefAs>(); + const usize count = store.getNumberOfTuples(); + if(count == 0) + { + return MakeErrorResult>(-27020, "Input array is empty."); + } + constexpr usize targetPageBytes = usize{1024} * usize{1024}; + const usize pageCount = std::min(count, targetPageBytes / sizeof(T)); + // Scalar input can use bool. The store needs a contiguous bool buffer, which std::vector cannot provide. + // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays,modernize-avoid-c-arrays) + auto values = std::make_unique(pageCount); + Range range; + Result<> status; + bool initialized = false; + for(usize offset = 0; offset < count;) + { + if(shouldCancel) + { + range.Cancelled = true; + return ConvertResultTo>(std::move(status), std::move(range)); + } + const usize size = std::min(pageCount, count - offset); + ImageProcessing::AccumulateTransferResult(status, store.copyIntoBuffer(offset, nonstd::span(values.get(), size))); + if(status.invalid()) + { + return ConvertInvalidResult>(std::move(status)); + } + for(usize index = 0; index < size; ++index) + { + const T value = values[index]; + if constexpr(std::is_floating_point_v) + { + if(!std::isfinite(value)) + { + continue; + } + } + if(!initialized) + { + range.Minimum = value; + range.Maximum = value; + initialized = true; + } + else + { + range.Minimum = std::min(range.Minimum, value); + range.Maximum = std::max(range.Maximum, value); + } + } + offset += size; + if(reportRange) + { + reportRange(offset, count); + } + } + range.Cancelled = shouldCancel; + return ConvertResultTo>(std::move(status), std::move(range)); +} + +/** + * @brief Normalizes native distances without signed overflow or endpoint collapse. + * @tparam T Scalar input type. + * @param value Input value; nonfinite values use the first control color. + * @param minimum Finite native minimum. + * @param maximum Finite native maximum. + * @return Finite float32 coordinate in [0, 1]. + */ +template +float32 Normalize(T value, T minimum, T maximum) +{ + if constexpr(std::is_floating_point_v) + { + if(!std::isfinite(value)) + { + return 0.0F; + } + } + if(minimum == maximum || value <= minimum) + { + return 0.0F; + } + if(value >= maximum) + { + return 1.0F; + } + float64 fraction = 0; + if constexpr(std::is_same_v) + { + fraction = value ? 1.0 : 0.0; + } + else if constexpr(std::is_integral_v) + { + // Unsigned subtraction is defined modulo 2^N. Since minimum <= value <= + // maximum, both distances fit the corresponding unsigned native type. + using UnsignedType = std::make_unsigned_t; + const auto numerator = static_cast(static_cast(value) - static_cast(minimum)); + const auto denominator = static_cast(static_cast(maximum) - static_cast(minimum)); + fraction = static_cast(numerator) / static_cast(denominator); + } + else + { + const float64 low = static_cast(minimum); + const float64 high = static_cast(maximum); + const float64 current = static_cast(value); + // The bound can round up, so scale at equality to avoid an overflowing width. + if(low < 0 && high > 0 && high >= std::numeric_limits::max() + low) + { + fraction = (current * 0.5 - low * 0.5) / (high * 0.5 - low * 0.5); + } + else + { + fraction = (current - low) / (high - low); + } + } + return static_cast(std::clamp(fraction, 0.0, 1.0)); +} + +/** + * @brief Validates the palette data the writer will index and interpolate. + * @param points Packed position/RGB controls. + * @param bins Normalized control positions. + * @return An error for invalid sizes, nonfinite values or unordered positions. + */ +inline Result<> ValidatePalette(const std::vector& points, const std::vector& bins) +{ + if(points.size() < 8 || points.size() % 4 != 0 || bins.size() != points.size() / 4 || !std::ranges::all_of(points, [](float32 value) { return std::isfinite(value); }) || + !std::ranges::all_of(bins, [](float32 value) { return std::isfinite(value); }) || !std::ranges::is_sorted(bins)) + { + return MakeErrorResult(-27029, "Write Image requires at least two finite color controls in position order. Select a valid color preset."); + } + return {}; +} + +/** + * @brief Uses the existing linear palette interpolation and truncating RGB bytes. + * Checked endpoints and usize indexes avoid invalid segment/channel casts. + * The caller validates the palette once before entering the pixel loop. + * @param bins Validated normalized control positions. + * @param value Finite normalized coordinate in [0, 1]. + * @param points Validated packed position/RGB controls. + * @return Three uint8 channels, with the existing truncation rule. + */ +inline std::array ComputeRgb(const std::vector& bins, float32 value, const std::vector& points) +{ + const usize last = bins.size() - 1; + usize left = 0; + usize right = 0; + float32 fraction = 0; + if(value >= 1) + { + left = last; + right = last; + } + else if(value > 0) + { + right = static_cast(std::ranges::lower_bound(bins, value) - bins.begin()); + right = std::min(last, std::max(1, right)); + left = right - 1; + const float32 width = bins[right] - bins[left]; + if(width > 0) + { + fraction = std::clamp((value - bins[left]) / width, 0.0F, 1.0F); + } + } + std::array rgb{}; + for(usize channel = 0; channel < rgb.size(); ++channel) + { + const float64 scaled = (points[(left * 4) + channel + 1] * (1.0 - fraction) + points[(right * 4) + channel + 1] * fraction) * 255; + rgb.at(channel) = static_cast(std::clamp(scaled, 0.0, 255.0)); + } + return rgb; +} +} // namespace nx::core::write_image_color diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageDirect.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageDirect.cpp index 37ed0f935b..9df3b2388e 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageDirect.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageDirect.cpp @@ -1,7 +1,11 @@ #include "WriteImageDirect.hpp" +#include "WriteImageColorUtilities.hpp" + #include "simplnx/Common/AtomicFile.hpp" #include "simplnx/Common/Extent.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" #include "simplnx/Common/TypesUtility.hpp" #include "simplnx/DataStructure/DataArray.hpp" #include "simplnx/DataStructure/Geometry/ImageGeom.hpp" @@ -12,6 +16,7 @@ #include "simplnx/Utilities/ImageIO/ImageIOFactory.hpp" #include "simplnx/Utilities/ImageIO/ImageIOUtilities.hpp" #include "simplnx/Utilities/ImageIO/ImageMetadata.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageTransferResult.hpp" #include "simplnx/Utilities/ScaleBarRenderer.hpp" #include "simplnx/Utilities/ThrottledMessageHandler.hpp" @@ -20,11 +25,14 @@ #include #include +#include #include #include #include +#include #include #include +#include #include namespace fs = std::filesystem; @@ -124,9 +132,11 @@ struct ExtractSliceFunctor } const std::vector& sliceValues = sliceResult.value(); const usize expectedElements = static_cast(sliceExtent.totalElements()) * nComp; - if(sliceValues.size() != expectedElements) + const usize actualElements = sliceValues.size(); + if(actualElements != expectedElements) { - return MakeErrorResult(-27023, fmt::format("Could not bulk-read image slice {}. Expected {} values but received {}.", sliceIndex, expectedElements, sliceValues.size())); + return MergeResults(ConvertResult(std::move(sliceResult)), + MakeErrorResult(-27023, fmt::format("Could not bulk-read image slice {}. Expected {} values but received {}.", sliceIndex, expectedElements, actualElements))); } const usize rowElements = (planeIndex == 2 ? dimY : dimX) * nComp; @@ -151,7 +161,7 @@ struct ExtractSliceFunctor } } - return {}; + return ConvertResult(std::move(sliceResult)); } }; @@ -173,7 +183,7 @@ Result> ReadMaskSlice(const IDataArray* maskArray, const Exte const std::vector& boolMask = maskResult.value(); std::vector mask(boolMask.size()); std::transform(boolMask.cbegin(), boolMask.cend(), mask.begin(), [](bool value) { return value ? uint8{1} : uint8{0}; }); - return {std::move(mask)}; + return ConvertResultTo>(ConvertResult(std::move(maskResult)), std::move(mask)); } const auto& maskStore = maskArray->getIDataStoreRefAs>(); return maskStore.readExtent(extent); @@ -191,93 +201,67 @@ struct ColorizeVolumeFunctor { // The operation calculates the range in pages and then colorizes bounded slices. template - Result<> operator()(const IDataArray& dataArrayRef, usize planeIndex, usize dimX, usize dimY, usize dimZ, usize sliceCount, usize sliceW, usize sliceH, const std::vector& binPoints, - const std::vector& controlPoints, usize numControlColors, const IDataArray* maskArray, const std::vector& invalidColor, const std::atomic_bool& shouldCancel, - const std::function(std::vector&, usize)>& writeSlice, const std::function& reportRange = {}, - const std::function& reportRows = {}) + Result<> operator()(const IDataArray& dataArrayRef, usize planeIndex, usize dimX, usize dimY, usize dimZ, const write_image_color::SliceExtents& sliceExtents, const std::vector& binPoints, + const std::vector& controlPoints, const IDataArray* maskArray, const std::vector& invalidColor, const std::atomic_bool& shouldCancel, + const std::function(std::vector&, usize)>& writeSlice, const write_image_color::ProgressCallbacks& progress) { - const auto& dataStore = dataArrayRef.template getIDataStoreRefAs>(); - const usize numTuples = dataStore.getNumberOfTuples(); - if(numTuples == 0) + const auto& [sliceW, sliceH, sliceCount] = sliceExtents; + if(Result<> sizeResult = write_image_color::ValidateSize(sliceExtents, maskArray != nullptr); sizeResult.invalid()) { - return MakeErrorResult(-27020, "Input array is empty."); + return sizeResult; } - - // Include masked values to match Create Color Map range semantics. - constexpr usize k_TargetPageBytes = 1024 * 1024; - const usize pageElements = std::max(1, std::min(numTuples, k_TargetPageBytes / sizeof(T))); - auto valuePage = std::make_unique(pageElements); - T arrayMin{}; - T arrayMax{}; - bool initialized = false; - for(usize offset = 0; offset < numTuples; offset += pageElements) + auto rangeResult = write_image_color::ScanRange(dataArrayRef, shouldCancel, progress.Range); + if(rangeResult.invalid()) { - if(shouldCancel) - { - return {}; - } - const usize count = std::min(pageElements, numTuples - offset); - if(Result<> result = dataStore.copyIntoBuffer(offset, nonstd::span(valuePage.get(), count)); result.invalid()) - { - return result; - } - for(usize i = 0; i < count; ++i) - { - if(!initialized) - { - arrayMin = valuePage[i]; - arrayMax = valuePage[i]; - initialized = true; - } - else - { - arrayMin = std::min(arrayMin, valuePage[i]); - arrayMax = std::max(arrayMax, valuePage[i]); - } - } - if(reportRange) - { - reportRange(offset + count, numTuples); - } + return ConvertResult(std::move(rangeResult)); } - + const auto range = rangeResult.value(); + Result<> status = ConvertResult(std::move(rangeResult)); + if(range.Cancelled) + { + return status; + } + const auto& dataStore = dataArrayRef.template getIDataStoreRefAs>(); std::vector sliceBuffer(sliceW * sliceH * 3); for(usize slice = 0; slice < sliceCount; ++slice) { if(shouldCancel) { - return {}; + return status; } const Extent sliceExtent = CreateSliceExtent(planeIndex, slice, dimX, dimY, dimZ); Result> sliceResult = dataStore.readExtent(sliceExtent); if(sliceResult.invalid()) { - return ConvertResult(std::move(sliceResult)); + return MergeResults(std::move(status), ConvertResult(std::move(sliceResult))); } + status.warnings().insert(status.warnings().end(), sliceResult.warnings().begin(), sliceResult.warnings().end()); const std::vector& sliceValues = sliceResult.value(); const usize pixelCount = sliceW * sliceH; if(sliceValues.size() != pixelCount) { - return MakeErrorResult(-27024, fmt::format("Could not bulk-read colorized image slice {}. Expected {} values but received {}.", slice, pixelCount, sliceValues.size())); + return MergeResults(std::move(status), + MakeErrorResult(-27024, fmt::format("Could not bulk-read colorized image slice {}. Expected {} values but received {}.", slice, pixelCount, sliceValues.size()))); } Result> maskResult = ReadMaskSlice(maskArray, sliceExtent); if(maskResult.invalid()) { - return ConvertResult(std::move(maskResult)); + return MergeResults(std::move(status), ConvertResult(std::move(maskResult))); } + status.warnings().insert(status.warnings().end(), maskResult.warnings().begin(), maskResult.warnings().end()); const std::vector& maskValues = maskResult.value(); if(maskArray != nullptr && maskValues.size() != pixelCount) { - return MakeErrorResult(-27025, fmt::format("Could not bulk-read mask slice {}. Expected {} values but received {}.", slice, pixelCount, maskValues.size())); + return MergeResults(std::move(status), MakeErrorResult(-27025, fmt::format("Could not bulk-read mask slice {}. Expected {} values but received {}.", slice, pixelCount, maskValues.size()))); } for(usize row = 0; row < sliceH; ++row) { if(shouldCancel) { - return {}; + return status; } for(usize col = 0; col < sliceW; ++col) { @@ -292,25 +276,25 @@ struct ColorizeVolumeFunctor } const T sourceValue = sliceValues[dstPixel]; - const float32 nValue = ColorTableUtilities::NormalizeValue(sourceValue, arrayMin, arrayMax); - const std::array rgb = ColorTableUtilities::ComputeRgbFromControlPoints(nValue, binPoints, controlPoints, numControlColors); + const float32 nValue = write_image_color::Normalize(sourceValue, range.Minimum, range.Maximum); + const std::array rgb = write_image_color::ComputeRgb(binPoints, nValue, controlPoints); sliceBuffer[dst + 0] = rgb[0]; sliceBuffer[dst + 1] = rgb[1]; sliceBuffer[dst + 2] = rgb[2]; } - if(reportRows) + if(progress.Rows) { - reportRows(row + 1, sliceH); + progress.Rows(row + 1, sliceH); } } - auto result = writeSlice(sliceBuffer, slice); - if(result.invalid()) + ImageProcessing::AccumulateTransferResult(status, writeSlice(sliceBuffer, slice)); + if(status.invalid()) { - return result; + return status; } } - return {}; + return status; } }; } // namespace @@ -433,13 +417,15 @@ Result<> WriteImageDirect::operator()() ThrottledMessageHandler progressThrottle(m_MessageHandler); progressThrottle.reset(sliceCount, "Writing image slices"); m_MessageHandler.sendInfoMessage("Preparing and writing image slices"); - const std::function reportRange = [&](usize current, usize total) { progressThrottle.updatePercent("Computing color range", current, total); }; - const std::function reportRows = [&](usize current, usize total) { - if(sliceCount == 1) - { - progressThrottle.updatePercent("Preparing image rows", current, total); - } - }; + const write_image_color::ProgressCallbacks progress{.Range = [&](usize current, usize total) { progressThrottle.updatePercent("Computing color range", current, total); }, + .Rows = + [&](usize current, usize total) { + if(sliceCount == 1) + { + progressThrottle.updatePercent("Preparing image rows", current, total); + } + }}; + const write_image_color::SliceExtents sliceExtents{.Width = sliceW, .Height = sliceH, .Count = sliceCount}; // Encode and atomically commit one independently named slice file. auto writeSlice = [&](std::vector& sliceBuffer, usize slice) -> Result<> { @@ -476,15 +462,16 @@ Result<> WriteImageDirect::operator()() m_MessageHandler.sendInfoMessage("Encoding image file"); } auto writeResult = imageIO->writePixelData(atomicFile.tempFilePath(), *writeBufferPtr, metadata); + writeResult = MergeResults(ConvertResult(std::move(atomicFileResult)), std::move(writeResult)); if(writeResult.invalid()) { return writeResult; } if(m_ShouldCancel) { - return MakeErrorResult(-1, "Filter cancelled"); + return MergeResults(std::move(writeResult), MakeErrorResult(-1, "Filter cancelled")); } - auto commitResult = atomicFile.commit(); + auto commitResult = MergeResults(std::move(writeResult), atomicFile.commit()); if(commitResult.valid()) { progressThrottle.updateCount(slice + 1); @@ -515,7 +502,10 @@ Result<> WriteImageDirect::operator()() return MakeErrorResult(-27022, fmt::format("Preset '{}' must define at least 2 control colors", m_InputValues.presetName)); } std::vector binPoints = ColorTableUtilities::NormalizeBinPoints(controlPoints); - const usize numControlColors = controlPoints.size() / 4; + if(Result<> paletteResult = write_image_color::ValidatePalette(controlPoints, binPoints); paletteResult.invalid()) + { + return MergeResults(ConvertResult(std::move(controlPointsResult)), std::move(paletteResult)); + } const IDataArray* maskArrayPtr = nullptr; if(m_InputValues.useMask) @@ -523,29 +513,34 @@ Result<> WriteImageDirect::operator()() maskArrayPtr = m_DataStructure.getDataAs(m_InputValues.maskArrayPath); } - return ExecuteDataFunction(ColorizeVolumeFunctor{}, dataType, imageArray, m_InputValues.planeIndex, dimX, dimY, dimZ, sliceCount, sliceW, sliceH, binPoints, controlPoints, numControlColors, - maskArrayPtr, m_InputValues.invalidColor, m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), reportRange, reportRows); + auto colorResult = ExecuteDataFunction(ColorizeVolumeFunctor{}, dataType, imageArray, m_InputValues.planeIndex, dimX, dimY, dimZ, sliceExtents, binPoints, controlPoints, maskArrayPtr, + m_InputValues.invalidColor, m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), progress); + return MergeResults(ConvertResult(std::move(controlPointsResult)), std::move(colorResult)); } // The non-color path preserves typed bytes for one slice at a time. usize sliceBufferSize = sliceW * sliceH * nComp * bytesPerComponent; std::vector sliceBuffer(sliceBufferSize); + Result<> status; for(usize slice = 0; slice < sliceCount; ++slice) { if(m_ShouldCancel) { - return {}; + return status; } - auto extractResult = ExecuteDataFunction(ExtractSliceFunctor{}, dataType, imageArray, sliceBuffer, slice, m_InputValues.planeIndex, dimX, dimY, dimZ, nComp, reportRows); + auto extractResult = ExecuteDataFunction(ExtractSliceFunctor{}, dataType, imageArray, sliceBuffer, slice, m_InputValues.planeIndex, dimX, dimY, dimZ, nComp, progress.Rows); if(extractResult.invalid()) { - return extractResult; + return MergeResults(std::move(status), std::move(extractResult)); } + std::ranges::move(extractResult.warnings(), std::back_inserter(status.warnings())); + auto sliceResult = writeSlice(sliceBuffer, slice); if(sliceResult.invalid()) { - return sliceResult; + return MergeResults(std::move(status), std::move(sliceResult)); } + std::ranges::move(sliceResult.warnings(), std::back_inserter(status.warnings())); } - return {}; + return status; } diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageScanline.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageScanline.cpp index ccc2d70569..3e86bdfcda 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageScanline.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Algorithms/WriteImageScanline.cpp @@ -1,8 +1,13 @@ #include "WriteImageScanline.hpp" +#include "WriteImageColorUtilities.hpp" + #include "simplnx/Common/AtomicFile.hpp" #include "simplnx/Common/Extent.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" #include "simplnx/Common/TypesUtility.hpp" +#include "simplnx/DataStructure/AbstractDataStore.hpp" #include "simplnx/DataStructure/DataArray.hpp" #include "simplnx/DataStructure/Geometry/ImageGeom.hpp" #include "simplnx/DataStructure/IDataArray.hpp" @@ -12,6 +17,7 @@ #include "simplnx/Utilities/ImageIO/ImageIOFactory.hpp" #include "simplnx/Utilities/ImageIO/ImageIOUtilities.hpp" #include "simplnx/Utilities/ImageIO/ImageMetadata.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageTransferResult.hpp" #include "simplnx/Utilities/ImageProcessing/WorkingMemory.hpp" #include "simplnx/Utilities/ScaleBarRenderer.hpp" #include "simplnx/Utilities/ThrottledMessageHandler.hpp" @@ -24,8 +30,10 @@ #include #include #include +#include #include #include +#include #include namespace fs = std::filesystem; @@ -264,7 +272,7 @@ struct WriteDirectVolumeFunctor * @param shouldCancel Stops processing between output slices. * @param writeSlice Writes one packed output slice. * @param reportRows Optional synchronous callback for completed output rows. - * @return Error from the image writer. + * @return The accumulated warnings and the first transfer or writer error. */ template Result<> operator()(const IDataArray& dataArray, usize planeIndex, usize dimX, usize dimY, usize dimZ, usize sliceCount, usize sliceW, usize sliceH, usize numComponents, @@ -288,11 +296,12 @@ struct WriteDirectVolumeFunctor std::unique_ptr groupValues = std::make_unique(slicesPerGroup * sliceValueCount); std::vector sliceBuffer(sliceValueCount * (std::is_same_v ? 1 : sizeof(T))); + Result<> status; for(usize firstSlice = 0; firstSlice < sliceCount; firstSlice += slicesPerGroup) { if(shouldCancel) { - return {}; + return status; } const usize groupSliceCount = std::min(slicesPerGroup, sliceCount - firstSlice); @@ -300,25 +309,29 @@ struct WriteDirectVolumeFunctor const Extent groupExtent = CreateSliceGroupExtent(planeIndex, firstSlice, groupSliceCount, dimX, dimY, dimZ); // A failed read leaves the group buffer holding stale or uninitialized values. // Stop here so the writer never commits those values as image pixels. - if(Result<> result = dataStore.readExtentIntoBuffer(groupExtent, nonstd::span(groupValues.get(), groupValueCount)); result.invalid()) + auto readResult = dataStore.readExtentIntoBuffer(groupExtent, nonstd::span(groupValues.get(), groupValueCount)); + if(readResult.invalid()) { - return result; + return MergeResults(std::move(status), std::move(readResult)); } + std::ranges::move(readResult.warnings(), std::back_inserter(status.warnings())); for(usize localSliceIndex = 0; localSliceIndex < groupSliceCount; ++localSliceIndex) { if(shouldCancel) { - return {}; + return status; } CopySliceFromGroup(nonstd::span(groupValues.get(), groupValueCount), sliceBuffer, localSliceIndex, groupSliceCount, planeIndex, dimX, dimY, dimZ, numComponents, reportRows); - if(Result<> result = writeSlice(sliceBuffer, firstSlice + localSliceIndex); result.invalid()) + auto sliceResult = writeSlice(sliceBuffer, firstSlice + localSliceIndex); + if(sliceResult.invalid()) { - return result; + return MergeResults(std::move(status), std::move(sliceResult)); } + std::ranges::move(sliceResult.warnings(), std::back_inserter(status.warnings())); } } - return {}; + return status; } }; @@ -361,74 +374,39 @@ struct ColorizeVolumeFunctor * @param dimX Number of source tuples on the X axis. * @param dimY Number of source tuples on the Y axis. * @param dimZ Number of source tuples on the Z axis. - * @param sliceCount Number of output slices. - * @param sliceW Output width in pixels. - * @param sliceH Output height in pixels. + * @param sliceExtents Output width, height, and slice count. * @param dataArrayPath Identifies the scalar source array. * @param binPoints Normalized color-control positions. * @param controlPoints Color-control values. - * @param numControlColors Number of control colors. * @param maskArray Optional Boolean or uint8 mask array. * @param invalidColor RGB value for masked pixels. * @param shouldCancel Stops processing between output slices. * @param writeSlice Writes one packed RGB output slice. - * @param reportRange Optional synchronous callback for completed range-scan values. - * @param reportRows Optional synchronous callback for completed output rows. + * @param progress Synchronous callbacks for range-scan values and output rows. * @return Error from source I/O or the image writer. */ template - Result<> operator()(const IDataArray& dataArrayRef, usize planeIndex, usize dimX, usize dimY, usize dimZ, usize sliceCount, usize sliceW, usize sliceH, const DataPath& dataArrayPath, - const std::vector& binPoints, const std::vector& controlPoints, usize numControlColors, const IDataArray* maskArray, const std::vector& invalidColor, - const std::atomic_bool& shouldCancel, const std::function(std::vector&, usize)>& writeSlice, const std::function& reportRange = {}, - const std::function& reportRows = {}) + Result<> operator()(const IDataArray& dataArrayRef, usize planeIndex, usize dimX, usize dimY, usize dimZ, const write_image_color::SliceExtents& sliceExtents, const DataPath& dataArrayPath, + const std::vector& binPoints, const std::vector& controlPoints, const IDataArray* maskArray, const std::vector& invalidColor, + const std::atomic_bool& shouldCancel, const std::function(std::vector&, usize)>& writeSlice, const write_image_color::ProgressCallbacks& progress) { - const auto& dataStore = dataArrayRef.template getIDataStoreRefAs>(); - const usize numTuples = dataStore.getNumberOfTuples(); - if(numTuples == 0) + const auto& [sliceW, sliceH, sliceCount] = sliceExtents; + if(Result<> sizeResult = write_image_color::ValidateSize(sliceExtents, maskArray != nullptr); sizeResult.invalid()) { - return MakeErrorResult(-27020, "Input array is empty."); + return sizeResult; } - - // Global min/max over the whole array (mask ignored) — matches Create Color Map semantics. - constexpr usize k_TargetPageBytes = 1024 * 1024; - const usize pageElements = std::max(1, std::min(numTuples, k_TargetPageBytes / sizeof(T))); - auto valuePage = std::make_unique(pageElements); - T arrayMin{}; - T arrayMax{}; - bool initialized = false; - for(usize offset = 0; offset < numTuples; offset += pageElements) + auto rangeResult = write_image_color::ScanRange(dataArrayRef, shouldCancel, progress.Range); + if(rangeResult.invalid()) { - if(shouldCancel) - { - return {}; - } - const usize count = std::min(pageElements, numTuples - offset); - if(Result<> result = dataStore.copyIntoBuffer(offset, nonstd::span(valuePage.get(), count)); result.invalid()) - { - return result; - } - for(usize i = 0; i < count; ++i) - { - if(!initialized) - { - arrayMin = valuePage[i]; - arrayMax = valuePage[i]; - initialized = true; - } - else - { - arrayMin = std::min(arrayMin, valuePage[i]); - arrayMax = std::max(arrayMax, valuePage[i]); - } - } - if(reportRange) - { - reportRange(offset + count, numTuples); - } + return ConvertResult(std::move(rangeResult)); } - - valuePage.reset(); - + const auto range = rangeResult.value(); + Result<> status = ConvertResult(std::move(rangeResult)); + if(range.Cancelled) + { + return status; + } + const auto& dataStore = dataArrayRef.template getIDataStoreRefAs>(); const usize pixelCount = sliceW * sliceH; const uint64 sourceSliceBytes = static_cast(pixelCount) * sizeof(T); const uint64 maskSliceBytes = maskArray == nullptr ? 0 : static_cast(pixelCount); @@ -438,10 +416,12 @@ struct ColorizeVolumeFunctor const usize slicesPerGroup = CalculateSlicesPerGroup(planeIndex, sliceCount, groupSliceBytes, workingMemory.sizeBytes()); if(slicesPerGroup == 0) { - return MakeErrorResult(-27026, - fmt::format("Write Image cannot reserve one source slice for array '{}'. The scalar and mask buffers require {} bytes, but the working-memory manager granted {} bytes. " - "Increase the cache memory budget or reduce the image slice dimensions.", - dataArrayPath.toString(), groupSliceBytes, workingMemory.sizeBytes())); + return MergeResults( + std::move(status), + MakeErrorResult(-27026, + fmt::format("Write Image cannot reserve one source slice for array '{}'. The scalar and mask buffers require {} bytes, but the working-memory manager granted {} bytes. " + "Increase the cache memory budget or reduce the image slice dimensions.", + dataArrayPath.toString(), groupSliceBytes, workingMemory.sizeBytes()))); } std::unique_ptr groupValues = std::make_unique(slicesPerGroup * pixelCount); @@ -461,11 +441,11 @@ struct ColorizeVolumeFunctor std::vector sliceBuffer(sliceW * sliceH * 3); - for(usize firstSlice = 0; firstSlice < sliceCount; firstSlice += slicesPerGroup) + for(usize firstSlice = 0; firstSlice < sliceCount;) { if(shouldCancel) { - return {}; + return status; } const usize groupSliceCount = std::min(slicesPerGroup, sliceCount - firstSlice); @@ -473,22 +453,27 @@ struct ColorizeVolumeFunctor const Extent groupExtent = CreateSliceGroupExtent(planeIndex, firstSlice, groupSliceCount, dimX, dimY, dimZ); // A failed read leaves the group buffers holding stale or uninitialized values. // Stop here so the writer never commits those values as image pixels. - if(Result<> result = dataStore.readExtentIntoBuffer(groupExtent, nonstd::span(groupValues.get(), groupValueCount)); result.invalid()) + ImageProcessing::AccumulateTransferResult(status, dataStore.readExtentIntoBuffer(groupExtent, nonstd::span(groupValues.get(), groupValueCount))); + if(status.invalid()) { - return result; + return status; } if(booleanMaskValues != nullptr) { - if(Result<> result = maskArray->getIDataStoreRefAs>().readExtentIntoBuffer(groupExtent, nonstd::span(booleanMaskValues.get(), groupValueCount)); result.invalid()) + ImageProcessing::AccumulateTransferResult( + status, maskArray->getIDataStoreRefAs>().readExtentIntoBuffer(groupExtent, nonstd::span(booleanMaskValues.get(), groupValueCount))); + if(status.invalid()) { - return result; + return status; } } else if(uint8MaskValues != nullptr) { - if(Result<> result = maskArray->getIDataStoreRefAs>().readExtentIntoBuffer(groupExtent, nonstd::span(uint8MaskValues.get(), groupValueCount)); result.invalid()) + ImageProcessing::AccumulateTransferResult( + status, maskArray->getIDataStoreRefAs>().readExtentIntoBuffer(groupExtent, nonstd::span(uint8MaskValues.get(), groupValueCount))); + if(status.invalid()) { - return result; + return status; } } @@ -496,14 +481,14 @@ struct ColorizeVolumeFunctor { if(shouldCancel) { - return {}; + return status; } for(usize row = 0; row < sliceH; ++row) { if(shouldCancel) { - return {}; + return status; } for(usize col = 0; col < sliceW; ++col) { @@ -520,25 +505,27 @@ struct ColorizeVolumeFunctor } const T sourceValue = groupValues[groupValueIndex]; - const float32 nValue = ColorTableUtilities::NormalizeValue(sourceValue, arrayMin, arrayMax); - const std::array rgb = ColorTableUtilities::ComputeRgbFromControlPoints(nValue, binPoints, controlPoints, numControlColors); + const float32 nValue = write_image_color::Normalize(sourceValue, range.Minimum, range.Maximum); + const std::array rgb = write_image_color::ComputeRgb(binPoints, nValue, controlPoints); sliceBuffer[dst + 0] = rgb[0]; sliceBuffer[dst + 1] = rgb[1]; sliceBuffer[dst + 2] = rgb[2]; } - if(reportRows) + if(progress.Rows) { - reportRows(row + 1, sliceH); + progress.Rows(row + 1, sliceH); } } - if(Result<> result = writeSlice(sliceBuffer, firstSlice + localSliceIndex); result.invalid()) + ImageProcessing::AccumulateTransferResult(status, writeSlice(sliceBuffer, firstSlice + localSliceIndex)); + if(status.invalid()) { - return result; + return status; } } + firstSlice += groupSliceCount; } - return {}; + return status; } }; } // namespace @@ -661,13 +648,15 @@ Result<> WriteImageScanline::operator()() ThrottledMessageHandler progressThrottle(m_MessageHandler); progressThrottle.reset(sliceCount, "Writing image slices"); m_MessageHandler.sendInfoMessage("Preparing and writing image slices"); - const std::function reportRange = [&](usize current, usize total) { progressThrottle.updatePercent("Computing color range", current, total); }; - const std::function reportRows = [&](usize current, usize total) { - if(sliceCount == 1) - { - progressThrottle.updatePercent("Preparing image rows", current, total); - } - }; + const write_image_color::ProgressCallbacks progress{.Range = [&](usize current, usize total) { progressThrottle.updatePercent("Computing color range", current, total); }, + .Rows = + [&](usize current, usize total) { + if(sliceCount == 1) + { + progressThrottle.updatePercent("Preparing image rows", current, total); + } + }}; + const write_image_color::SliceExtents sliceExtents{.Width = sliceW, .Height = sliceH, .Count = sliceCount}; // Shared per-slice writer: names the file, writes via the ImageIO layer, commits atomically. auto writeSlice = [&](std::vector& sliceBuffer, usize slice) -> Result<> { @@ -706,11 +695,12 @@ Result<> WriteImageScanline::operator()() m_MessageHandler.sendInfoMessage("Encoding image file"); } auto writeResult = imageIO->writePixelData(atomicFile.tempFilePath(), *writeBufferPtr, metadata); + writeResult = MergeResults(ConvertResult(std::move(atomicFileResult)), std::move(writeResult)); if(writeResult.invalid()) { return writeResult; } - auto commitResult = atomicFile.commit(); + auto commitResult = MergeResults(std::move(writeResult), atomicFile.commit()); if(commitResult.valid()) { progressThrottle.updateCount(slice + 1); @@ -741,7 +731,10 @@ Result<> WriteImageScanline::operator()() return MakeErrorResult(-27022, fmt::format("Preset '{}' must define at least 2 control colors", m_InputValues.presetName)); } std::vector binPoints = ColorTableUtilities::NormalizeBinPoints(controlPoints); - const usize numControlColors = controlPoints.size() / 4; + if(Result<> paletteResult = write_image_color::ValidatePalette(controlPoints, binPoints); paletteResult.invalid()) + { + return MergeResults(ConvertResult(std::move(controlPointsResult)), std::move(paletteResult)); + } const IDataArray* maskArrayPtr = nullptr; if(m_InputValues.useMask) @@ -749,11 +742,11 @@ Result<> WriteImageScanline::operator()() maskArrayPtr = m_DataStructure.getDataAs(m_InputValues.maskArrayPath); } - return ExecuteDataFunction(ColorizeVolumeFunctor{}, dataType, imageArray, m_InputValues.planeIndex, dimX, dimY, dimZ, sliceCount, sliceW, sliceH, m_InputValues.imageDataArrayPath, binPoints, - controlPoints, numControlColors, maskArrayPtr, m_InputValues.invalidColor, m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), reportRange, - reportRows); + auto colorResult = ExecuteDataFunction(ColorizeVolumeFunctor{}, dataType, imageArray, m_InputValues.planeIndex, dimX, dimY, dimZ, sliceExtents, m_InputValues.imageDataArrayPath, binPoints, + controlPoints, maskArrayPtr, m_InputValues.invalidColor, m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), progress); + return MergeResults(ConvertResult(std::move(controlPointsResult)), std::move(colorResult)); } return ExecuteDataFunction(WriteDirectVolumeFunctor{}, dataType, imageArray, m_InputValues.planeIndex, dimX, dimY, dimZ, sliceCount, sliceW, sliceH, nComp, m_InputValues.imageDataArrayPath, - m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), reportRows); + m_ShouldCancel, std::function(std::vector&, usize)>(writeSlice), progress.Rows); } diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AsinImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AsinImageFilter.cpp index 612b3a741d..42bcb1372e 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AsinImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/AsinImageFilter.cpp @@ -2,6 +2,8 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -78,7 +80,8 @@ IFilter::PreflightResult AsinImageFilter::preflightImpl(const DataStructure& dat auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> AsinImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +92,8 @@ Result<> AsinImageFilter::executeImpl(DataStructure& dataStructure, const Argume const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const AsinOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.cpp index dca53aad78..e3670ce96f 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.cpp @@ -2,13 +2,20 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/TypeTraits.hpp" #include "simplnx/DataStructure/IDataArray.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/BoolParameter.hpp" +#include "simplnx/Parameters/ChoicesParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" #include "simplnx/Parameters/GeometrySelectionParameter.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageProcessingOperationTypes.hpp" + +#include +#include using namespace nx::core; @@ -43,6 +50,14 @@ Parameters ConnectedComponentImageFilter::parameters() const "Set/Get whether the connected components are defined strictly by face connectivity or by face+edge+vertex connectivity. Default is FullyConnectedOff. " "For objects that are 1 pixel wide, use FullyConnectedOn.", false)); + params.insert( + std::make_unique(k_ProvisionalLabelLimitHandling_Key, "Provisional Label Limit Handling", + "Controls what happens if more than 4,294,967,295 provisional run IDs are needed. Error (default) stops before IDs wrap. " + "Warn and Continue (Legacy Behavior) keeps uint32 wrap to background zero and reused IDs. Foreground can disappear, components can merge, " + "and counts and downstream statistics can be incorrect. A wrapped zero from a previous row can erase a neighboring component in scanline processing. " + "Tiled processing skips that zero and can give different labels. Choose Warn only if you accept these consequences. " + "It does not increase label capacity or prevent memory or I/O errors.", + to_underlying(ImageProcessing::ConnectedComponentLabelLimitHandling::Error), ChoicesParameter::Choices{"Error", "Warn and Continue (Legacy Behavior)"})); params.insertSeparator(Parameters::Separator{"Input Cell Data"}); params.insert(std::make_unique(k_InputImageGeomPath_Key, "Image Geometry", "Select the Image Geometry Group from the DataStructure.", DataPath({"Image Geometry"}), @@ -58,7 +73,7 @@ Parameters ConnectedComponentImageFilter::parameters() const IFilter::VersionType ConnectedComponentImageFilter::parametersVersion() const { - return 1; + return 2; } IFilter::UniquePointer ConnectedComponentImageFilter::clone() const { @@ -91,7 +106,8 @@ Result<> ConnectedComponentImageFilter::executeImpl(DataStructure& dataStructure const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); auto fullyConnected = filterArgs.value(k_FullyConnected_Key); + const auto labelLimitHandling = static_cast(filterArgs.value(k_ProvisionalLabelLimitHandling_Key)); - return ImageProcessing::ExecuteConnectedComponentImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, fullyConnected, shouldCancel, messageHandler); + return ImageProcessing::ExecuteConnectedComponentImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, fullyConnected, shouldCancel, messageHandler, labelLimitHandling); } } // namespace nx::core diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.hpp index 392b960a91..873a6080a7 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ConnectedComponentImageFilter.hpp @@ -12,10 +12,11 @@ namespace nx::core * @brief ITK-free, out-of-core-capable connected-component labeling via a streaming scanline union-find. * * Labels the objects in a binary image: non-zero input voxels are foreground, zero-valued voxels are background. - * Each distinct foreground object is assigned a unique consecutive label (1, 2, 3, ...) in raster-scan order of + * Below the provisional ID limit, each foreground object gets a unique consecutive label (1, 2, 3, ...) in raster-scan order of * first appearance; background voxels are labeled 0. The input may be ANY integer scalar type; the output is a * FIXED uint32 label image regardless of the input element type. Matches the legacy ITK Connected Component Image - * Filter exactly (byte-identical label values). Out-of-core capable. + * Filter below the provisional uint32 ID limit. Error is the default at that limit. Explicit legacy continuation + * retains wrap to zero and reused IDs, so segmentation and downstream counts/statistics can be incorrect. */ class NXIMAGEPROCESSING_EXPORT ConnectedComponentImageFilter : public IFilter { @@ -33,6 +34,8 @@ class NXIMAGEPROCESSING_EXPORT ConnectedComponentImageFilter : public IFilter static constexpr StringLiteral k_InputImageDataPath_Key = "input_image_data_path"; static constexpr StringLiteral k_OutputImageArrayName_Key = "output_array_name"; static constexpr StringLiteral k_FullyConnected_Key = "fully_connected"; + // NOLINTNEXTLINE(readability-identifier-naming) -- Use the same k_Name_Key spelling as the other filter argument keys. + static constexpr StringLiteral k_ProvisionalLabelLimitHandling_Key = "provisional_label_limit_handling_index"; std::string name() const override; std::string className() const override; diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/CurvatureFlowImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/CurvatureFlowImageFilter.cpp index 056997b53c..e9aee042a9 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/CurvatureFlowImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/CurvatureFlowImageFilter.cpp @@ -1,15 +1,24 @@ #include "CurvatureFlowImageFilter.hpp" #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/TerminalConversionDiagnostics.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Common/TypesUtility.hpp" +#include "simplnx/DataStructure/Geometry/ImageGeom.hpp" #include "simplnx/DataStructure/IDataArray.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" #include "simplnx/Parameters/GeometrySelectionParameter.hpp" #include "simplnx/Parameters/NumberParameter.hpp" +#include "simplnx/Utilities/ImageProcessing/FiniteDifferenceEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include +#include + using namespace nx::core; namespace nx::core @@ -76,6 +85,15 @@ IFilter::PreflightResult CurvatureFlowImageFilter::preflightImpl(const DataStruc // the legacy ScalarPixelIdTypeList), matching the legacy ITK filter, which has no minimum-dimension requirement. Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter( dataStructure, selectedInputArray, imageGeomPath, outputArrayPath, /*requireScalar=*/true); + if(resultOutputActions.invalid()) + { + return {.outputActions = std::move(resultOutputActions)}; + } + const float64 timeStep = filterArgs.value(k_TimeStep_Key); + if(Result<> result = ImageProcessing::detail::ValidateCurvatureFlowTimeStep(timeStep); result.invalid()) + { + return {.outputActions = MergeResults(std::move(resultOutputActions), ConvertResultTo(std::move(result), OutputActions{}))}; + } return {std::move(resultOutputActions)}; } @@ -90,7 +108,34 @@ Result<> CurvatureFlowImageFilter::executeImpl(DataStructure& dataStructure, con auto timeStep = filterArgs.value(k_TimeStep_Key); auto numberOfIterations = filterArgs.value(k_NumberOfIterations_Key); - return ImageProcessing::ExecuteFiniteDifferenceImageFilter( - dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::detail::CurvatureFlowFn{}, timeStep, numberOfIterations, shouldCancel, messageHandler); + Result<> result = + ImageProcessing::ExecuteFiniteDifferenceImageFilter( + dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::detail::CurvatureFlowFn{}, timeStep, numberOfIterations, shouldCancel, messageHandler); + const auto appendOutput = [&](auto& diagnostic) { + const auto type = dataStructure.getDataRefAs(outputArrayPath).getDataType(); + diagnostic.message += fmt::format(" Output array '{}' has type '{}'.", outputArrayPath.toString(), DataTypeToString(type)); + }; + if(result.invalid()) + { + for(auto& error : result.errors()) + { + if(error.code == ImageProcessing::k_CurvatureFlowInvalidSpacing) + { + error.message += fmt::format(" Image Geometry '{}'.", imageGeomPath.toString()); + } + else if(error.code == ImageProcessing::k_CurvatureFlowNonFiniteIntegerOutput) + { + appendOutput(error); + } + } + } + for(auto& warning : result.warnings()) + { + if(warning.code == ImageProcessing::k_CurvatureFlowClippedIntegerOutput) + { + appendOutput(warning); + } + } + return ImageProcessing::detail::FinishCheckedImageExecution(std::move(result), shouldCancel); } } // namespace nx::core diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpImageFilter.cpp index d114f44c08..81809ccd8c 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct ExpOperation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::exp(static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::exp(static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult ExpImageFilter::preflightImpl(const DataStructure& data auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> ExpImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> ExpImageFilter::executeImpl(DataStructure& dataStructure, const Argumen const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const ExpOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpNegativeImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpNegativeImageFilter.cpp index 91cc9dd728..c66cbb075e 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpNegativeImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ExpNegativeImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct ExpNegativeOperation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::exp(-static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::exp(-static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult ExpNegativeImageFilter::preflightImpl(const DataStructu auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> ExpNegativeImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> ExpNegativeImageFilter::executeImpl(DataStructure& dataStructure, const const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const ExpNegativeOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.cpp index baceee0217..fb95436cab 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.cpp @@ -2,7 +2,12 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/DataStructure/DataPath.hpp" +#include "simplnx/DataStructure/DataStructure.hpp" #include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Filter/Arguments.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/BoolParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" @@ -12,10 +17,12 @@ #include "simplnx/Parameters/StringParameter.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageProcessingOperationTypes.hpp" #include "simplnx/Utilities/ImageProcessing/MorphologicalReconstructionEngine.hpp" #include "simplnx/Utilities/SIMPLConversion.hpp" #include +#include #include @@ -27,6 +34,7 @@ namespace // its Height guards: -8553 (non-finite) and -8556 (negative). constexpr int32 k_NonFiniteHeight = -8553; constexpr int32 k_NegativeHeight = -8556; +constexpr int32 k_FractionalIntegerHeight = -29101; } // namespace namespace nx::core @@ -57,7 +65,7 @@ Parameters HConvexImageFilter::parameters() const params.insertSeparator(Parameters::Separator{"Input Parameter(s)"}); params.insert(std::make_unique(k_Height_Key, "Height", "The height (contrast) cap. Each regional maximum is transformed to its own height capped at this value (its dome height); the rest of the image " - "becomes 0. Must be finite.", + "becomes 0. Must be finite and nonnegative. Integer input requires a whole-number Height; floating input allows fractions.", 2.0)); params.insert(std::make_unique(k_FullyConnected_Key, "Fully Connected", "Whether the connected components are defined strictly by face connectivity (Off) or by face+edge+vertex connectivity (On). Default is Off. For " @@ -92,8 +100,7 @@ IFilter::PreflightResult HConvexImageFilter::preflightImpl(const DataStructure& auto height = filterArgs.value(k_Height_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - // The marker offsets every voxel by -Height through a saturating cast, which is undefined for a non-finite - // value; reject it here so the offset is always well-defined. + // The marker offset must be finite for reconstruction. if(!std::isfinite(height)) { return {MakeErrorResult(k_NonFiniteHeight, fmt::format("H Convex requires a finite Height, but the supplied value was {}.", height))}; @@ -105,6 +112,14 @@ IFilter::PreflightResult HConvexImageFilter::preflightImpl(const DataStructure& { return {MakeErrorResult(k_NegativeHeight, fmt::format("H Convex requires a non-negative Height, but the supplied value was {}.", height))}; } + const auto* inputArrayPtr = dataStructure.getDataAs(selectedInputArray); + if(inputArrayPtr != nullptr && ImageProcessing::GetIntegerScalarTypes().contains(inputArrayPtr->getDataType()) && std::trunc(height) != height) + { + return {.outputActions = MakeErrorResult( + k_FractionalIntegerHeight, fmt::format("H Convex requires a whole-number Height for integer input array '{}', but received {}. Choose an intentional whole Height or explicitly " + "convert the input to floating point before using a fractional Height.", + selectedInputArray.toString(), height))}; + } // requireScalar=true: the grayscale reconstruction engine is defined on scalar images (matching the legacy ITK // operator); the shared preflight also validates type membership and the geometry/tuple match. @@ -125,8 +140,9 @@ Result<> HConvexImageFilter::executeImpl(DataStructure& dataStructure, const Arg // HConvex == input - HMaxima(input, Height): reconstruct-by-dilation of the saturating (input - Height) marker, // then subtract that h-maxima result from the input (the h-dome). FullyConnected selects the reconstruction // connectivity. - return ImageProcessing::ExecuteMorphologicalReconstructionImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::ReconstructOp::Dilation, fullyConnected, - ImageProcessing::detail::ReconMarker::MinusHeight, height, shouldCancel, messageHandler, /*differenceFromInput=*/true); + return ImageProcessing::detail::ExecuteMorphologicalReconstructionWithValidatedHeight(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::ReconstructOp::Dilation, + fullyConnected, ImageProcessing::detail::ReconMarker::MinusHeight, height, shouldCancel, messageHandler, + /*differenceFromInput=*/true); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.hpp index 3854356407..4d91211815 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HConvexImageFilter.hpp @@ -12,12 +12,14 @@ namespace nx::core * @brief ITK-free, out-of-core-capable h-convex transform: each regional maximum is replaced by its own height, * capped at the Height parameter (its "dome"), and everything else becomes zero. * - * HConvex(f, h) = f - HMaxima(f, h). A regional maximum of contrast c maps to min(c, h); the background maps to 0. + * HMaxima in the mathematical identity HConvex(f, h) = f - HMaxima(f, h) uses exact integer markers here. + * The separate H Maxima filter can round 64-bit integer markers above 2^53. A regional maximum of contrast c maps to min(c, h); the background maps to 0. * It is implemented by reconstruction-by-dilation of the (input - Height) marker under the input mask (the HMaxima * result) followed by an elementwise subtraction of that result from the input. Output type == input type; the - * input must be single-component (scalar). This matches the legacy ITK H Convex Image Filter exactly for integer - * and float types, and is out-of-core capable: the reconstruction result never exceeds the input, so the - * difference never underflows. + * input must be single-component (scalar). Height is finite and nonnegative; integer images require a whole Height. + * Integer marker arithmetic preserves native units and saturates at the type minimum. Floating images allow fractional + * Height. A nonnegative contrast that exceeds a signed output type's maximum returns an execution error. + * Resident and disk-backed arrays use the same numeric contract. */ class NXIMAGEPROCESSING_EXPORT HConvexImageFilter : public IFilter { diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.cpp index d481d892f0..59281e79f4 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.cpp @@ -2,7 +2,12 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/DataStructure/DataPath.hpp" +#include "simplnx/DataStructure/DataStructure.hpp" #include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Filter/Arguments.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/BoolParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" @@ -12,10 +17,11 @@ #include "simplnx/Parameters/StringParameter.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageProcessingOperationTypes.hpp" #include "simplnx/Utilities/ImageProcessing/MorphologicalReconstructionEngine.hpp" #include "simplnx/Utilities/SIMPLConversion.hpp" -#include +#include #include @@ -28,6 +34,7 @@ namespace // the -8552 (non-finite) and -8555 (negative) slots for its Height guards (HMaxima owns -8551/-8554). constexpr int32 k_NonFiniteHeight = -8552; constexpr int32 k_NegativeHeight = -8555; +constexpr int32 k_FractionalIntegerHeight = -29201; } // namespace namespace nx::core @@ -58,7 +65,8 @@ Parameters HMinimaImageFilter::parameters() const params.insertSeparator(Parameters::Separator{"Input Parameter(s)"}); params.insert(std::make_unique(k_Height_Key, "Height", "The height (contrast) below which a regional minimum is suppressed. Every regional minimum whose depth is less than Height is removed; each " - "surviving minimum is raised by exactly Height. Must be finite.", + "surviving minimum is raised by exactly Height. Must be finite and nonnegative. Integer input requires a whole-number Height; floating input " + "allows fractions.", 2.0)); params.insert(std::make_unique(k_FullyConnected_Key, "Fully Connected", "Whether the connected components are defined strictly by face connectivity (Off) or by face+edge+vertex connectivity (On). Default is Off. For " @@ -93,8 +101,7 @@ IFilter::PreflightResult HMinimaImageFilter::preflightImpl(const DataStructure& auto height = filterArgs.value(k_Height_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - // The marker offsets every voxel by +Height through a saturating cast, which is undefined for a non-finite - // value; reject it here so the offset is always well-defined. + // The marker offset must be finite for reconstruction. if(!std::isfinite(height)) { return {MakeErrorResult(k_NonFiniteHeight, fmt::format("H Minima requires a finite Height, but the supplied value was {}.", height))}; @@ -106,6 +113,14 @@ IFilter::PreflightResult HMinimaImageFilter::preflightImpl(const DataStructure& { return {MakeErrorResult(k_NegativeHeight, fmt::format("H Minima requires a non-negative Height, but the supplied value was {}.", height))}; } + const auto* inputArrayPtr = dataStructure.getDataAs(selectedInputArray); + if(inputArrayPtr != nullptr && ImageProcessing::GetIntegerScalarTypes().contains(inputArrayPtr->getDataType()) && std::trunc(height) != height) + { + return {.outputActions = MakeErrorResult( + k_FractionalIntegerHeight, fmt::format("H Minima requires a whole-number Height for integer input array '{}', but received {}. Choose an intentional whole Height or explicitly " + "convert the input to floating point before using a fractional Height.", + selectedInputArray.toString(), height))}; + } // requireScalar=true: the grayscale reconstruction engine is defined on scalar images (matching the legacy ITK // operator); the shared preflight also validates type membership and the geometry/tuple match. @@ -125,8 +140,9 @@ Result<> HMinimaImageFilter::executeImpl(DataStructure& dataStructure, const Arg // HMinima == reconstruct-by-erosion of the saturating (input + Height) marker under the input mask; unlike // HMaxima the legacy ITK filter exposes a FullyConnected option, so honor it here. - return ImageProcessing::ExecuteMorphologicalReconstructionImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::ReconstructOp::Erosion, fullyConnected, - ImageProcessing::detail::ReconMarker::PlusHeight, height, shouldCancel, messageHandler); + return ImageProcessing::detail::ExecuteMorphologicalReconstructionWithValidatedHeight(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, ImageProcessing::ReconstructOp::Erosion, + fullyConnected, ImageProcessing::detail::ReconMarker::PlusHeight, height, shouldCancel, messageHandler, + /*differenceFromInput=*/false); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.hpp index f88b679ed0..40a2e17a2e 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/HMinimaImageFilter.hpp @@ -9,19 +9,15 @@ namespace nx::core { /** * @class HMinimaImageFilter - * @brief ITK-free, out-of-core-capable H-Minima transform (suppresses regional minima whose depth/contrast is - * below a user-supplied Height). + * @brief Suppresses shallow regional minima by reconstructing the raised input marker by erosion. * - * The H-Minima transform removes every regional minimum whose depth (contrast below the surrounding level) is - * less than @c Height, and raises each surviving minimum by exactly @c Height, leaving the background otherwise - * unchanged. It is implemented as reconstruction-by-erosion of a marker image equal to the saturating sum - * (input + Height) under the input itself as the mask (the shared D3-split morphological reconstruction engine). - * The saturating marker matches the legacy ITK H Minima Image Filter exactly, including the clamp (rather than - * wrap) when (input + Height) overflows the element type's range. + * The marker is input plus Height, and the original input is the lower mask for reconstruction. + * Integer images require finite, nonnegative whole Height values. Integer marker addition uses native values and saturates at the type maximum. + * Height 0 preserves integer input exactly, including native 64-bit units. Floating images retain fractional Height and existing floating arithmetic. + * Height uses float64 precision, which cannot distinguish every consecutive integer above 2^53. * - * Output type == input type; the input must be single-component (scalar). This is out-of-core capable (the legacy - * filter rejected chunked arrays): reconstruction only copies or clamps existing values, so the result is - * bit-for-bit identical for integer AND float types and matches the legacy ITK output exactly. + * Input must have one component per tuple. Output contains reconstructed intensities with the same type and shape as input. + * Resident and disk-backed reconstruction both preserve integer marker precision for downstream minima and watershed seeds. */ class NXIMAGEPROCESSING_EXPORT HMinimaImageFilter : public IFilter { diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Log10ImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Log10ImageFilter.cpp index dc0e166927..59ae63a981 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Log10ImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/Log10ImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct Log10Operation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::log10(static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::log10(static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult Log10ImageFilter::preflightImpl(const DataStructure& da auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> Log10ImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> Log10ImageFilter::executeImpl(DataStructure& dataStructure, const Argum const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const Log10Operation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/LogImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/LogImageFilter.cpp index 217cacf6d0..0b6c0f0422 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/LogImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/LogImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct LogOperation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::log(static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::log(static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult LogImageFilter::preflightImpl(const DataStructure& data auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> LogImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> LogImageFilter::executeImpl(DataStructure& dataStructure, const Argumen const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const LogOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.cpp index d2f3ea1d37..44506bfbff 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.cpp @@ -2,10 +2,12 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "simplnx/Common/TypeTraits.hpp" #include "simplnx/DataStructure/IDataArray.hpp" #include "simplnx/Filter/Actions/CreateArrayAction.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/BoolParameter.hpp" +#include "simplnx/Parameters/ChoicesParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" #include "simplnx/Parameters/GeometrySelectionParameter.hpp" #include "simplnx/Utilities/DataStoreUtilities.hpp" @@ -14,6 +16,7 @@ #include +#include #include using namespace nx::core; @@ -52,6 +55,14 @@ Parameters MorphologicalWatershedFromMarkersImageFilter::parameters() const "Set/Get whether the connected components are defined strictly by face connectivity or by face+edge+vertex connectivity. Default is FullyConnectedOff. " "For objects that are 1 pixel wide, use FullyConnectedOn.", false)); + params.insert(std::make_unique( + k_MarkerIdConversionHandling_Key, "Marker ID Conversion Handling", + "Controls marker IDs that change when converted to internal uint32 and back. Error (default) stops before flooding. " + "Warn and Continue (Legacy Behavior) keeps the old conversion, which can remove or rename seeds, merge basins, change boundaries and region sizes, " + "and make downstream feature measurements incorrect. Choose Warn only if you intentionally accept these consequences; it does not preserve unsupported IDs. " + "Output keeps the marker type. All 8/16/32-bit integer values, including signed negatives, are lossless. The int64/uint64 lossless range is 0 through 4294967295, inclusive. " + "Zero is unmarked; UINT32_MAX is a valid seed. For example, uint64 4294967296 becomes 0, 4294967297 becomes 1, and int64 -1 becomes 4294967295.", + to_underlying(ImageProcessing::MarkerIdConversionHandling::Error), ChoicesParameter::Choices{"Error", "Warn and Continue (Legacy Behavior)"})); params.insertSeparator(Parameters::Separator{"Input Cell Data"}); params.insert(std::make_unique(k_InputImageGeomPath_Key, "Image Geometry", "Select the Image Geometry Group from the DataStructure.", DataPath({"Image Geometry"}), @@ -70,7 +81,7 @@ Parameters MorphologicalWatershedFromMarkersImageFilter::parameters() const } IFilter::VersionType MorphologicalWatershedFromMarkersImageFilter::parametersVersion() const { - return 1; + return 2; } IFilter::UniquePointer MorphologicalWatershedFromMarkersImageFilter::clone() const { @@ -165,8 +176,9 @@ Result<> MorphologicalWatershedFromMarkersImageFilter::executeImpl(DataStructure auto markWatershedLine = filterArgs.value(k_MarkWatershedLine_Key); auto fullyConnected = filterArgs.value(k_FullyConnected_Key); + const auto conversionHandling = static_cast(filterArgs.value(k_MarkerIdConversionHandling_Key)); return ImageProcessing::ExecuteMorphologicalWatershedFromMarkersImageFilter(dataStructure, imageGeomPath, selectedInputArray, markerArrayPath, outputArrayPath, markWatershedLine, fullyConnected, - shouldCancel, messageHandler); + shouldCancel, messageHandler, conversionHandling); } } // namespace nx::core diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.hpp index 872b2f8735..b134f508c6 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/MorphologicalWatershedFromMarkersImageFilter.hpp @@ -23,6 +23,8 @@ class NXIMAGEPROCESSING_EXPORT MorphologicalWatershedFromMarkersImageFilter : pu static constexpr StringLiteral k_MarkerImageDataPath_Key = "marker_image_data_path"; static constexpr StringLiteral k_MarkWatershedLine_Key = "mark_watershed_line"; static constexpr StringLiteral k_FullyConnected_Key = "fully_connected"; + // NOLINTNEXTLINE(readability-identifier-naming) -- Use the same k_Name_Key spelling as the other filter argument keys. + static constexpr StringLiteral k_MarkerIdConversionHandling_Key = "marker_id_conversion_handling_index"; static constexpr StringLiteral k_OutputImageArrayName_Key = "output_array_name"; std::string name() const override; diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.cpp index f384c837bf..665d82bf20 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.cpp @@ -1,8 +1,16 @@ #include "OtsuMultipleThresholdsImageFilter.hpp" -#include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" - +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" #include "simplnx/Common/TypesUtility.hpp" +#include "simplnx/DataStructure/AbstractDataStore.hpp" +#include "simplnx/DataStructure/DataArray.hpp" +#include "simplnx/DataStructure/DataPath.hpp" +#include "simplnx/DataStructure/DataStructure.hpp" +#include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Filter/Arguments.hpp" +#include "simplnx/Filter/IFilter.hpp" +#include "simplnx/Filter/Parameters.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/BoolParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" @@ -10,45 +18,28 @@ #include "simplnx/Parameters/GeometrySelectionParameter.hpp" #include "simplnx/Parameters/NumberParameter.hpp" #include "simplnx/Parameters/StringParameter.hpp" -#include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/OtsuImageEngine.hpp" #include "simplnx/Utilities/SIMPLConversion.hpp" -#include +#include -#include +#include +#include +#include #include using namespace nx::core; -namespace +namespace nx::core { -struct OtsuOperation +namespace { - uint32 numBins = 128u; - uint8 numThresholds = 1u; - uint8 labelOffset = 0u; - bool valleyEmphasis = false; - bool returnBinMidpoint = false; - - template - auto makeClassifyOp(const std::vector& thresholds) const - { - const uint8 offset = labelOffset; - return [thresholds, offset](T value) -> U { - // class index = count of thresholds this value STRICTLY EXCEEDS, + labelOffset. std::lower_bound gives the - // count of thresholds < value, i.e. a value exactly equal to a threshold lands in the LOWER class -- which - // is ITK's ThresholdLabeler convention ("values equal to a threshold are in the lower class"). Using - // std::upper_bound here put a value == threshold one class too high (e.g. every voxel of a constant image). - const auto idx = static_cast(std::lower_bound(thresholds.begin(), thresholds.end(), static_cast(value)) - thresholds.begin()); - return static_cast(offset + idx); - }; - } -}; +constexpr int32 k_OtsuClassIntervalOverflow = -28903; +constexpr int32 k_OtsuExcludedLabelCollision = -28907; +constexpr int32 k_OtsuMaskTupleMismatch = -28908; } // namespace -namespace nx::core -{ std::string OtsuMultipleThresholdsImageFilter::name() const { return FilterTraits::name; @@ -79,6 +70,12 @@ Parameters OtsuMultipleThresholdsImageFilter::parameters() const params.insert(std::make_unique(k_ValleyEmphasis_Key, "Valley Emphasis", "Set/Get the use of valley emphasis. Default is false.", false)); params.insert( std::make_unique(k_ReturnBinMidpoint_Key, "ReturnBinMidpoint", "Should the threshold value be mid-point of the bin or the maximum? Default is to return bin maximum.", false)); + params.insertLinkableParameter(std::make_unique(k_UseMaskArray_Key, "Use Mask Array", "Explicitly exclude pixels with a zero/false mask value before fitting the histogram.", false)); + params.insert(std::make_unique(k_MaskArrayPath_Key, "Mask Array", "Select a scalar bool or uint8 mask with one value per input tuple. Nonzero values select pixels.", + DataPath{}, ArraySelectionParameter::AllowedTypes{DataType::boolean, DataType::uint8}, ArraySelectionParameter::AllowedComponentShapes{{1}})); + params.insert(std::make_unique(k_MaskedLabel_Key, "Excluded Label", "Label for pixels excluded by the input mask. Choose a value outside the ordinary class interval.", uint8{255})); + params.linkParameters(k_UseMaskArray_Key, k_MaskArrayPath_Key, true); + params.linkParameters(k_UseMaskArray_Key, k_MaskedLabel_Key, true); params.insertSeparator(Parameters::Separator{"Input Cell Data"}); params.insert(std::make_unique(k_InputImageGeomPath_Key, "Image Geometry", "Select the Image Geometry Group from the DataStructure.", DataPath({"Image Geometry"}), @@ -94,7 +91,7 @@ Parameters OtsuMultipleThresholdsImageFilter::parameters() const } IFilter::VersionType OtsuMultipleThresholdsImageFilter::parametersVersion() const { - return 1; + return 2; } IFilter::UniquePointer OtsuMultipleThresholdsImageFilter::clone() const { @@ -117,8 +114,37 @@ IFilter::PreflightResult OtsuMultipleThresholdsImageFilter::preflightImpl(const return { MakeErrorResult(-8311, fmt::format("NumberOfThresholds ({}) must be >= 1 and < NumberOfHistogramBins ({}).", static_cast(numberOfThresholds), numberOfHistogramBins))}; } - + const uint32 labelOffset = filterArgs.value(k_LabelOffset_Key); + const uint32 lastLabel = labelOffset + static_cast(numberOfThresholds); + if(lastLabel > 255) + { + return {.outputActions = MakeErrorResult(k_OtsuClassIntervalOverflow, + fmt::format("Label Offset ({}) plus Number Of Thresholds ({}) exceeds 255. Reduce either value to keep every class label within uint8.", + labelOffset, static_cast(numberOfThresholds)))}; + } + const bool useMask = filterArgs.value(k_UseMaskArray_Key); const auto& inputArray = dataStructure.getDataRefAs(selectedInputArray); + if(useMask) + { + const uint32 maskedLabel = filterArgs.value(k_MaskedLabel_Key); + if(maskedLabel >= labelOffset && maskedLabel <= lastLabel) + { + return {.outputActions = MakeErrorResult( + k_OtsuExcludedLabelCollision, + fmt::format("Excluded Label ({}) collides with the configured class interval [{}, {}]. Select an Excluded Label outside this interval or reduce the class interval.", maskedLabel, + labelOffset, lastLabel))}; + } + const auto maskPath = filterArgs.value(k_MaskArrayPath_Key); + // ArraySelectionParameter also accepts nonnumeric array kinds. + const auto* maskPtr = dataStructure.getDataAs(maskPath); + if(maskPtr == nullptr) + { + constexpr int32 invalidMaskArrayKind = -28909; + return {.outputActions = + MakeErrorResult(invalidMaskArrayKind, fmt::format("Mask Array '{}' is not a numeric data array. Select a scalar bool or uint8 mask array.", maskPath.toString()))}; + } + } + if(inputArray.getNumberOfComponents() != 1) { return {MakeErrorResult(-8310, fmt::format("Otsu Multiple Thresholds requires a single-component (scalar) input array, but '{}' has {} components.", selectedInputArray.toString(), @@ -137,14 +163,38 @@ Result<> OtsuMultipleThresholdsImageFilter::executeImpl(DataStructure& dataStruc auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - auto numberOfThresholds = filterArgs.value(k_NumberOfThresholds_Key); - auto labelOffset = filterArgs.value(k_LabelOffset_Key); - auto numberOfHistogramBins = filterArgs.value(k_NumberOfHistogramBins_Key); - auto valleyEmphasis = filterArgs.value(k_ValleyEmphasis_Key); - auto returnBinMidpoint = filterArgs.value(k_ReturnBinMidpoint_Key); - - const OtsuOperation operation{numberOfHistogramBins, numberOfThresholds, labelOffset, valleyEmphasis, returnBinMidpoint}; - return ImageProcessing::ExecuteHistogramImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + const ImageProcessing::OtsuImageOptions options{.NumberOfBins = filterArgs.value(k_NumberOfHistogramBins_Key), + .NumberOfThresholds = filterArgs.value(k_NumberOfThresholds_Key), + .LabelOffset = filterArgs.value(k_LabelOffset_Key), + .ExcludedLabel = filterArgs.value(k_MaskedLabel_Key), + .ValleyEmphasis = filterArgs.value(k_ValleyEmphasis_Key), + .ReturnBinMidpoint = filterArgs.value(k_ReturnBinMidpoint_Key)}; + const auto& inputArray = dataStructure.getDataRefAs(selectedInputArray); + const IDataArray* maskPtr = nullptr; + if(filterArgs.value(k_UseMaskArray_Key)) + { + const auto maskPath = filterArgs.value(k_MaskArrayPath_Key); + maskPtr = &dataStructure.getDataRefAs(maskPath); + // Upstream filters can resize arrays during execution. Compare their final counts before reading either store. + const auto maskTuples = maskPtr->getNumberOfTuples(); + const auto inputTuples = inputArray.getNumberOfTuples(); + if(maskTuples != inputTuples) + { + return MakeErrorResult(k_OtsuMaskTupleMismatch, fmt::format("Mask Array '{}' has {} tuples, but input '{}' has {}. Select a scalar mask with one value per input tuple.", maskPath.toString(), + maskTuples, selectedInputArray.toString(), inputTuples)); + } + } + // Dispatch is synchronous, so the filter arguments and local paths remain live. + return ImageProcessing::AllNumeric::dispatch(inputArray.getDataType(), [&]() -> Result<> { + const auto& input = dataStructure.getDataRefAs>(selectedInputArray).getDataStoreRef(); + auto& output = dataStructure.getDataRefAs>(outputArrayPath).getDataStoreRef(); + if(maskPtr != nullptr && maskPtr->getDataType() == DataType::boolean) + { + return ImageProcessing::ApplyOtsuImage(input, output, &maskPtr->getIDataStoreRefAs>(), options, shouldCancel, messageHandler); + } + const auto* maskStorePtr = maskPtr == nullptr ? nullptr : &maskPtr->getIDataStoreRefAs>(); + return ImageProcessing::ApplyOtsuImage(input, output, maskStorePtr, options, shouldCancel, messageHandler); + }); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.hpp index fc18c9b2a4..35b0cd6091 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/OtsuMultipleThresholdsImageFilter.hpp @@ -26,6 +26,11 @@ class NXIMAGEPROCESSING_EXPORT OtsuMultipleThresholdsImageFilter : public IFilte static constexpr StringLiteral k_NumberOfHistogramBins_Key = "number_of_histogram_bins"; static constexpr StringLiteral k_ValleyEmphasis_Key = "valley_emphasis"; static constexpr StringLiteral k_ReturnBinMidpoint_Key = "return_bin_midpoint"; + // NOLINTBEGIN(readability-identifier-naming) -- Use the same k_Name_Key spelling as the other filter argument keys. + static constexpr StringLiteral k_UseMaskArray_Key = "use_mask_array"; + static constexpr StringLiteral k_MaskArrayPath_Key = "mask_array_path"; + static constexpr StringLiteral k_MaskedLabel_Key = "masked_label"; + // NOLINTEND(readability-identifier-naming) static Result FromSIMPLJson(const nlohmann::json& json); diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.cpp index 0236398ab6..aaded6633e 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.cpp @@ -1,6 +1,7 @@ #include "SmoothingRecursiveGaussianImageFilter.hpp" #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "NXImageProcessing/utils/TerminalConversionDiagnostics.hpp" #include "simplnx/DataStructure/IDataArray.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" @@ -12,8 +13,11 @@ #include "simplnx/Parameters/VectorParameter.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/RecursiveGaussianEngine.hpp" #include "simplnx/Utilities/SIMPLConversion.hpp" +#include + using namespace nx::core; namespace nx::core @@ -78,7 +82,7 @@ IFilter::PreflightResult SmoothingRecursiveGaussianImageFilter::preflightImpl(co const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); // requireScalar=true: the recursive Gaussian is defined on scalar images. The output is SameAsInput (type-preserving), - // so an input type T produces a float32-free, T-typed output array. The SignedScalar policy admits only signed integer + // so an input type T produces a T-typed output array with float32 inter-pass precision. The SignedScalar policy admits only signed integer // + floating point types (the legacy SignedScalarPixelIdTypeList); unsigned types are rejected. Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter( dataStructure, selectedInputArray, imageGeomPath, outputArrayPath, /*requireScalar=*/true); @@ -94,15 +98,11 @@ IFilter::PreflightResult SmoothingRecursiveGaussianImageFilter::preflightImpl(co } auto sigma = filterArgs.value(k_Sigma_Key); - if(Result<> sigmaCheck = ImageProcessing::ValidatePositiveSigma(sigma, imageGeom.getDimensions(), ImageProcessing::k_RecursiveGaussianNonPositiveSigma); sigmaCheck.invalid()) - { - return {ConvertResultTo(std::move(sigmaCheck), OutputActions{})}; - } - - if(Result<> spacingCheck = ImageProcessing::ValidatePositiveSpacing(imageGeom.getSpacing(), imageGeom.getDimensions(), ImageProcessing::k_RecursiveGaussianNonPositiveSpacing, 1e-8); - spacingCheck.invalid()) + // X and Y are always filtered. An upstream filter can still reduce the provisional grid to a single Z slice. + if(Result<> controls = ImageProcessing::detail::ValidateSmoothingGaussianSigma(sigma, 2); controls.invalid()) { - return {ConvertResultTo(std::move(spacingCheck), OutputActions{})}; + controls.errors().front().message += fmt::format(" Image Geometry '{}'.", imageGeomPath.toString()); + return {.outputActions = ConvertResultTo(std::move(controls), OutputActions{})}; } return {std::move(resultOutputActions)}; } @@ -118,7 +118,9 @@ Result<> SmoothingRecursiveGaussianImageFilter::executeImpl(DataStructure& dataS auto sigma = filterArgs.value(k_Sigma_Key); auto normalizeAcrossScale = filterArgs.value(k_NormalizeAcrossScale_Key); - return ImageProcessing::ExecuteSmoothingRecursiveGaussianImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, sigma, normalizeAcrossScale, shouldCancel, messageHandler); + return ImageProcessing::detail::FinishCheckedImageExecution( + ImageProcessing::ExecuteSmoothingRecursiveGaussianImageFilter(dataStructure, imageGeomPath, selectedInputArray, outputArrayPath, sigma, normalizeAcrossScale, shouldCancel, messageHandler), + shouldCancel); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.hpp index 7e12df2c7d..86a7f8fcb8 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SmoothingRecursiveGaussianImageFilter.hpp @@ -13,7 +13,9 @@ namespace nx::core * * Convolves the input with a Gaussian (per-axis sigma) using the Deriche 4th-order recursive IIR approximation. * The input may be any SIGNED scalar type (int8/16/32/64 or float32/64); the output has the SAME type as the input. - * Matches the legacy ITK Smoothing Recursive Gaussian Image Filter exactly for integer/float64 inputs. + * Each axis materializes float32 values, including for float64 output. Finite final integer values truncate and clip + * to the output range with one warning. Nonfinite final integer values fail. Active Sigma, spacing, effective scale, + * and formed coefficients are validated; inactive Z controls remain unused for a two-dimensional image. */ class NXIMAGEPROCESSING_EXPORT SmoothingRecursiveGaussianImageFilter : public IFilter { diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SqrtImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SqrtImageFilter.cpp index 0a67c57b85..b7e0e04360 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SqrtImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SqrtImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct SqrtOperation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::sqrt(static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::sqrt(static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult SqrtImageFilter::preflightImpl(const DataStructure& dat auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> SqrtImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> SqrtImageFilter::executeImpl(DataStructure& dataStructure, const Argume const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const SqrtOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SquareImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SquareImageFilter.cpp index 1235c7a4e7..63f82e6e27 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SquareImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/SquareImageFilter.cpp @@ -2,6 +2,16 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/DataStructure/AbstractDataStore.hpp" +#include "simplnx/DataStructure/DataArray.hpp" +#include "simplnx/DataStructure/DataPath.hpp" +#include "simplnx/DataStructure/DataStructure.hpp" +#include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -9,22 +19,94 @@ #include "simplnx/Parameters/StringParameter.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/StreamingStatistics.hpp" #include "simplnx/Utilities/SIMPLConversion.hpp" -#include +#include + +#include +#include +#include using namespace nx::core; namespace { +constexpr int32 k_SquareBelowSignedLimit = -29001; +constexpr int32 k_SquareAboveSignedLimit = -29002; +constexpr int32 k_SquareAboveUnsignedLimit = -29003; +template +using SquareOutputType = std::conditional_t< + std::is_same_v, int16, + std::conditional_t< + std::is_same_v, uint16, + std::conditional_t, int32, + std::conditional_t, uint32, std::conditional_t, int64, std::conditional_t, uint64, T>>>>>>; + +template +Result<> validateSquareRange(const AbstractDataStore& inputStore, const DataPath& inputPath, const std::atomic_bool& shouldCancel) +{ + static_assert(std::is_same_v || std::is_same_v); + if(shouldCancel) + { + return {}; + } + auto extremaResult = ImageProcessing::ComputeArrayMinMax(inputStore, shouldCancel); + if(extremaResult.invalid()) + { + return ConvertResult(std::move(extremaResult)); + } + if(shouldCancel || extremaResult.value().count == 0) + { + return ConvertResult(std::move(extremaResult)); + } + const auto& extrema = extremaResult.value(); + if constexpr(std::is_same_v) + { + // Compare native signed values directly; taking abs(INT64_MIN) would overflow. + constexpr int64 limit = 3037000499LL; + if(extrema.min < -limit) + { + auto errorResult = + MakeErrorResult(k_SquareBelowSignedLimit, fmt::format("Square Image Filter cannot square value {} in input array '{}': int64 inputs must be at least -3037000499. Convert the input to " + "float64 first if approximate larger squares are acceptable.", + extrema.min, inputPath.toString())); + return MergeResults(ConvertResult(std::move(extremaResult)), std::move(errorResult)); + } + if(extrema.max > limit) + { + auto errorResult = MakeErrorResult(k_SquareAboveSignedLimit, fmt::format("Square Image Filter cannot square value {} in input array '{}': int64 inputs must be at most " + "3037000499. Convert the input to float64 first if approximate larger squares are acceptable.", + extrema.max, inputPath.toString())); + return MergeResults(ConvertResult(std::move(extremaResult)), std::move(errorResult)); + } + } + else if(extrema.max > 4294967295ULL) + { + auto errorResult = MakeErrorResult(k_SquareAboveUnsignedLimit, fmt::format("Square Image Filter cannot square value {} in input array '{}': uint64 inputs must be at most " + "4294967295. Convert the input to float64 first if approximate larger squares are acceptable.", + extrema.max, inputPath.toString())); + return MergeResults(ConvertResult(std::move(extremaResult)), std::move(errorResult)); + } + return ConvertResult(std::move(extremaResult)); +} + struct SquareOperation { template auto makeMapOp() const { return [](T value) -> U { - const double d = static_cast(value); - return static_cast(d * d); + if constexpr(std::is_integral_v) + { + const U widenedValue = static_cast(+value); + return static_cast(widenedValue * widenedValue); + } + else + { + const float64 floatingValue = static_cast(value); + return ImageProcessing::ConvertMathResult(floatingValue * floatingValue); + } }; } }; @@ -81,7 +163,8 @@ IFilter::PreflightResult SquareImageFilter::preflightImpl(const DataStructure& d auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> SquareImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -91,8 +174,23 @@ Result<> SquareImageFilter::executeImpl(DataStructure& dataStructure, const Argu auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); + Result<> validationResult; + const DataType inputType = dataStructure.getDataRefAs(selectedInputArray).getDataType(); + if(inputType == DataType::int64) + { + validationResult = validateSquareRange(dataStructure.getDataRefAs(selectedInputArray).getDataStoreRef(), selectedInputArray, shouldCancel); + } + else if(inputType == DataType::uint64) + { + validationResult = validateSquareRange(dataStructure.getDataRefAs(selectedInputArray).getDataStoreRef(), selectedInputArray, shouldCancel); + } + if(validationResult.invalid() || shouldCancel) + { + return validationResult; + } const SquareOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + auto executeResult = ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return MergeResults(std::move(validationResult), std::move(executeResult)); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/TanImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/TanImageFilter.cpp index cc62cda25b..72779788f1 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/TanImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/TanImageFilter.cpp @@ -2,6 +2,11 @@ #include "NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp" +#include "NXImageProcessing/utils/MathOutputUtilities.hpp" + +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/Filter/Output.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataGroupSelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" @@ -22,7 +27,7 @@ struct TanOperation template auto makeMapOp() const { - return [](T value) -> U { return static_cast(std::tan(static_cast(value))); }; + return [](T value) -> U { return ImageProcessing::ConvertMathResult(std::tan(static_cast(value))); }; } }; } // namespace @@ -78,7 +83,8 @@ IFilter::PreflightResult TanImageFilter::preflightImpl(const DataStructure& data auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); - Result resultOutputActions = ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); + Result resultOutputActions = + ImageProcessing::PreflightFullOverwriteImageFilter(dataStructure, selectedInputArray, imageGeomPath, outputArrayPath); return {std::move(resultOutputActions)}; } Result<> TanImageFilter::executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, @@ -89,7 +95,8 @@ Result<> TanImageFilter::executeImpl(DataStructure& dataStructure, const Argumen const DataPath outputArrayPath = selectedInputArray.replaceName(outputArrayName); const TanOperation operation{}; - return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, messageHandler); + return ImageProcessing::ExecuteImageFilter(dataStructure, selectedInputArray, outputArrayPath, operation, shouldCancel, + messageHandler); } namespace diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.cpp index 5fa3be25f9..07701ebb7b 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.cpp @@ -2,18 +2,85 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "simplnx/Common/Result.hpp" +#include "simplnx/Common/Types.hpp" +#include "simplnx/DataStructure/DataPath.hpp" +#include "simplnx/DataStructure/DataStructure.hpp" #include "simplnx/DataStructure/IDataArray.hpp" +#include "simplnx/Filter/Arguments.hpp" +#include "simplnx/Filter/Output.hpp" +#include "simplnx/Filter/Parameters.hpp" #include "simplnx/Parameters/ArraySelectionParameter.hpp" #include "simplnx/Parameters/DataObjectNameParameter.hpp" #include "simplnx/Parameters/GeometrySelectionParameter.hpp" #include "simplnx/Parameters/NumberParameter.hpp" -#include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include // NOLINT(misc-include-cleaner) The serialization overrides require the complete JSON type. +#include + +#include +#include +#include +#include +#include + using namespace nx::core; namespace nx::core { +namespace +{ +constexpr int32 k_ThresholdMaxCCNaNUpperBoundary = -28610; +constexpr int32 k_ThresholdMaxCCNullUpperBoundary = -28619; + +// This cutoff accepts signed infinities, which JSON numbers cannot represent. +class UpperBoundaryParameter final : public Float64Parameter +{ +public: + using Float64Parameter::Float64Parameter; + + UniquePointer clone() const override + { + return std::make_unique(name(), humanName(), helpText(), defaultNumber()); + } + + VersionType getVersion() const override + { + return 2; + } + +protected: + nlohmann::json toJsonImpl(const std::any& value) const override + { + const auto cap = std::any_cast(value); + if(std::isinf(cap)) + { + return cap > 0 ? "+Infinity" : "-Infinity"; + } + return Float64Parameter::toJsonImpl(value); + } + + Result fromJsonImpl(const nlohmann::json& json, VersionType version) const override + { + if(json == "+Infinity") + { + return Float64Parameter::fromJsonImpl(std::numeric_limits::infinity(), version); + } + if(json == "-Infinity") + { + return Float64Parameter::fromJsonImpl(-std::numeric_limits::infinity(), version); + } + if(json.is_null()) + { + return MakeErrorResult(k_ThresholdMaxCCNullUpperBoundary, + R"(Upper Boundary is null. The saved value has lost its sign. Enter a finite cutoff, "+Infinity" for the native maximum, or "-Infinity" for an empty band.)"); + } + return Float64Parameter::fromJsonImpl(json, version); + } +}; +} // namespace + std::string ThresholdMaximumConnectedComponentsImageFilter::name() const { return FilterTraits::name; @@ -41,27 +108,18 @@ Parameters ThresholdMaximumConnectedComponentsImageFilter::parameters() const params.insertSeparator(Parameters::Separator{"Input Parameter(s)"}); params.insert(std::make_unique( k_MinimumObjectSizeInPixels_Key, "Minimum Object Size In Pixels", - "The pixel type must support comparison operators. Set the minimum pixel area used to count objects on the image. Thus, only objects that have a pixel area greater than the minimum pixel area " - "will be counted as an object in the optimization portion of this filter. Essentially, it eliminates noise from being counted as an object. The default value is zero.", + "Count face-connected nonzero output components with at least this many pixels or voxels. This changes the search score; it does not remove small objects from the output. Default: 0 pixels.", 0u)); - params.insert(std::make_unique( + params.insert(std::make_unique( k_UpperBoundary_Key, "Upper Boundary", - "The following Set/Get methods are for the binary threshold function. This class automatically calculates the lower threshold boundary. The upper threshold boundary, inside value, and outside " - "value can be defined by the user, however the standard values are used as default if not set by the user. The default value of the: Inside value is the maximum pixel type intensity. Outside " - "value is the minimum pixel type intensity. Upper threshold boundary is the maximum pixel type intensity.", + "Inclusive upper cutoff in input intensity units. Default: 65536. Integer inputs truncate toward zero. High values or positive infinity select the native " + "maximum; low/empty bands or negative infinity produce Outside Value with a warning. NaN is an error. Float64 cannot express every 64-bit integer cutoff.", 65536.0)); - params.insert(std::make_unique( - k_InsideValue_Key, "Inside Value", - "The following Set/Get methods are for the binary threshold function. This class automatically calculates the lower threshold boundary. The upper threshold boundary, inside value, and outside " - "value can be defined by the user, however the standard values are used as default if not set by the user. The default value of the: Inside value is the maximum pixel type intensity. Outside " - "value is the minimum pixel type intensity. Upper threshold boundary is the maximum pixel type intensity.", - 1u)); - params.insert(std::make_unique( - k_OutsideValue_Key, "Outside Value", - "The following Set/Get methods are for the binary threshold function. This class automatically calculates the lower threshold boundary. The upper threshold boundary, inside value, and outside " - "value can be defined by the user, however the standard values are used as default if not set by the user. The default value of the: Inside value is the maximum pixel type intensity. Outside " - "value is the minimum pixel type intensity. Upper threshold boundary is the maximum pixel type intensity.", - 0u)); + params.insert( + std::make_unique(k_InsideValue_Key, "Inside Value", + "Dimensionless uint8 value assigned inside the inclusive threshold band. Default: 1. Only nonzero output pixels participate in the component-count score.", 1u)); + params.insert(std::make_unique(k_OutsideValue_Key, "Outside Value", + "Dimensionless uint8 value assigned outside the band. Default: 0. A nonzero value participates in scoring and can connect regions.", 0u)); params.insertSeparator(Parameters::Separator{"Input Cell Data"}); params.insert(std::make_unique(k_InputImageGeomPath_Key, "Image Geometry", "Select the Image Geometry Group from the DataStructure.", DataPath({"Image Geometry"}), @@ -77,7 +135,7 @@ Parameters ThresholdMaximumConnectedComponentsImageFilter::parameters() const IFilter::VersionType ThresholdMaximumConnectedComponentsImageFilter::parametersVersion() const { - return 1; + return 2; } IFilter::UniquePointer ThresholdMaximumConnectedComponentsImageFilter::clone() const { @@ -87,6 +145,11 @@ IFilter::UniquePointer ThresholdMaximumConnectedComponentsImageFilter::clone() c IFilter::PreflightResult ThresholdMaximumConnectedComponentsImageFilter::preflightImpl(const DataStructure& dataStructure, const Arguments& filterArgs, const MessageHandler& messageHandler, const std::atomic_bool& shouldCancel, const ExecutionContext& executionContext) const { + if(std::isnan(filterArgs.value(k_UpperBoundary_Key))) + { + return {.outputActions = MakeErrorResult( + k_ThresholdMaxCCNaNUpperBoundary, "Upper Boundary is NaN. Enter a valid numeric cutoff; positive infinity selects the native maximum and negative infinity requests an empty band.")}; + } auto imageGeomPath = filterArgs.value(k_InputImageGeomPath_Key); auto selectedInputArray = filterArgs.value(k_InputImageDataPath_Key); auto outputArrayName = filterArgs.value(k_OutputImageArrayName_Key); diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.hpp index 5d4bd2e3bf..2e683a5b6c 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/ThresholdMaximumConnectedComponentsImageFilter.hpp @@ -9,13 +9,10 @@ namespace nx::core { /** * @class ThresholdMaximumConnectedComponentsImageFilter - * @brief ITK-free, out-of-core-capable iterative auto-threshold that bisection-searches for the threshold value - * that MAXIMIZES the number of connected components in the image (subject to a minimum object size), then outputs - * the binary threshold at that value. + * @brief Searches native finite bounds with a component-count heuristic and an absolute two-intensity-unit stop. * - * The input may be ANY scalar type; the output is a FIXED uint8 binary image (Inside Value / Outside Value) - * regardless of the input element type. Matches the legacy ITK Threshold Maximum Connected Components Image - * Filter exactly (byte-identical binary output). Out-of-core capable. + * Finite scalar input values define the search interval. The uint8 output uses Inside Value and Outside Value. + * The search counts nonzero output components. Component run tables grow with image topology. */ class NXIMAGEPROCESSING_EXPORT ThresholdMaximumConnectedComponentsImageFilter : public IFilter { diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.cpp index 466585ec6c..a30432beda 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.cpp @@ -33,6 +33,7 @@ #include #include #include +#include #include namespace fs = std::filesystem; diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.hpp index c8206bcc84..aed5fc0e69 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/Filters/WriteImageFilter.hpp @@ -115,7 +115,7 @@ class NXIMAGEPROCESSING_EXPORT WriteImageFilter : public IFilter * @param messageHandler Receives slice progress messages. * @param shouldCancel Stops output between slices when set. * @param executionContext Resolves relative file paths. - * @return An error if slice extraction, compression, or file output fails. + * @return Warnings and errors from reading image data, encoding slices, or writing files. */ Result<> executeImpl(DataStructure& dataStructure, const Arguments& filterArgs, const PipelineFilter* pipelineNode, const MessageHandler& messageHandler, const std::atomic_bool& shouldCancel, const ExecutionContext& executionContext) const override; diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ComponentImageFilterExecutors.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ComponentImageFilterExecutors.cpp index edb9d8794b..c9d863afee 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ComponentImageFilterExecutors.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ComponentImageFilterExecutors.cpp @@ -8,7 +8,9 @@ #include "simplnx/Utilities/ImageProcessing/BinaryThinningEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ConnectedComponentEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageProcessingOperationTypes.hpp" #include "simplnx/Utilities/ImageProcessing/MorphologicalReconstructionEngine.hpp" +#include "simplnx/Utilities/ImageProcessing/ThresholdMaximumConnectedComponentsEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ZeroCrossingEngine.hpp" #include @@ -39,7 +41,8 @@ namespace * @brief Dispatched execute body for the (ITK-free) ConnectedComponent filter: labels foreground (non-zero) voxels * into consecutive uint32 components via the streaming scanline union-find @ref LabelConnectedComponents * engine. Output is a FIXED uint32 label image, background 0. Input must be an integer scalar type (the - * caller's preflight enforces this via the IntegerOnly policy). + * caller's preflight enforces this via the IntegerOnly policy). Explicit legacy overflow can lose foreground + * or merge components through zero and reused IDs. */ struct ConnectedComponentExecuteFn { @@ -51,13 +54,16 @@ struct ConnectedComponentExecuteFn const std::atomic_bool& shouldCancel; const IFilter::MessageHandler& messageHandler; + ConnectedComponentLabelLimitHandling labelLimitHandling; + template Result<> operator()() const { const auto& inArray = dataStructure.getDataRefAs>(inputArrayPath); auto& outArray = dataStructure.getDataRefAs>(outputArrayPath); const auto pred = [](T v) { return v != T{}; }; // compile-time predicate (Pred deduced by LabelConnectedComponents) - return LabelConnectedComponents(inArray.getDataStoreRef(), outArray.getDataStoreRef(), dims, pred, fullyConnected, shouldCancel, messageHandler); + return LabelConnectedComponents(inArray.getDataStoreRef(), outArray.getDataStoreRef(), dims, pred, fullyConnected, shouldCancel, messageHandler, k_ConnectedComponent2DTargetBytes, + labelLimitHandling); } }; @@ -673,207 +679,37 @@ struct RelabelComponentExecuteFn } }; -/** - * @brief Clamps the user's Float64 Upper Boundary parameter to the input pixel type T's representable range, - * mirroring the legacy ITK bridge functor's SetUpperBoundary call - * (ITKThresholdMaximumConnectedComponentsImageFilter.cpp::createFilter): `static_cast( - * std::min(upperBoundary, itk::NumericTraits::max()))`, where MinType is PixelType - * itself for int64/uint64 (whose max cannot be represented exactly as a float64, so the comparison is done - * in T to avoid that precision loss) and float64 for every other scalar type (all other integers plus - * float32/float64). This is the ONE-TIME clamp applied before the bisection (ITK's `m_UpperBoundary`), - * distinct from the per-run LOCAL bisection bound computed in @ref ThresholdMaxCCExecuteFn. - */ -template -T ClampThresholdMaxCCUpperBoundary(float64 upperBoundary) -{ - if constexpr(std::is_same_v || std::is_same_v) - { - return std::min(static_cast(upperBoundary), std::numeric_limits::max()); - } - else - { - return static_cast(std::min(upperBoundary, static_cast(std::numeric_limits::max()))); - } -} - -/** - * @brief Dispatched execute body for the (ITK-free) ThresholdMaximumConnectedComponents filter: bisection-searches - * the threshold value that MAXIMIZES the number of connected components with size >= - * @c minimumObjectSizeInPixels, then writes the final binary threshold at the converged value. Transcribed - * VERBATIM from itk::ThresholdMaximumConnectedComponentsImageFilter::GenerateData + ComputeConnectedComponents - * (itkThresholdMaximumConnectedComponentsImageFilter.hxx): - * - lowerBound/upperBound = input min/max (one streaming @ref ComputeArrayMinMax pass); upperBound is - * then clamped to the (type-clamped) Upper Boundary parameter -- @ref ClampThresholdMaxCCUpperBoundary. - * - midpoint = (upperBound-lowerBound)/2; midpointL = lowerBound+(midpoint-lowerBound)/2; midpointR = - * upperBound-(upperBound-midpoint)/2 -- PixelType (T) arithmetic (integer division for integer T, so - * this is NOT the true midpoint of [lowerBound,upperBound] when lowerBound != 0); this is ITK's own - * formula, transcribed exactly as written, not "fixed". - * - while((upperBound-lowerBound) > 2): count components at midpointR and midpointL (each count binary- - * thresholds [candidateThreshold, UpperBoundary] and counts connected components with size >= - * minimumObjectSizeInPixels, via @ref CountConnectedComponents); if the RIGHT count is STRICTLY greater - * than the LEFT count, move lowerBound=midpoint, midpoint=midpointR; otherwise (right <= left, i.e. a - * TIE TAKES THE LOWER/LEFT branch, matching ITK's `if (connectedComponentsRight > connectedComponentsLeft)` - * exactly) move upperBound=midpoint, midpoint=midpointL. Recompute midpointL/midpointR each iteration. - * - final: thresholdValue = midpoint; out = (v >= thresholdValue && v <= UpperBoundary) ? insideValue : - * outsideValue. - * The internal ConnectedComponentImageFilter connectivity is ITK's own default, FullyConnected=false (the - * bridge never calls SetFullyConnected; itkScanlineFilterCommon.h's m_FullyConnected member defaults to - * false). Output is a FIXED uint8 binary image. Input may be ANY scalar type (the caller's preflight - * enforces this via the AllNumeric policy). - */ +/** @brief Native threshold search adapter; the scoped engine owns validation, warnings and bounded I/O. */ struct ThresholdMaxCCExecuteFn { DataStructure& dataStructure; const DataPath& inputArrayPath; const DataPath& outputArrayPath; SizeVec3 dims; - uint32 minimumObjectSizeInPixels; - float64 upperBoundary; - uint8 insideValue; - uint8 outsideValue; + ThresholdMaxCCOptions Options; const std::atomic_bool& shouldCancel; const IFilter::MessageHandler& messageHandler; template Result<> operator()() const { - const auto& inStore = dataStructure.getDataRefAs>(inputArrayPath).getDataStoreRef(); - auto& outStore = dataStructure.getDataRefAs>(outputArrayPath).getDataStoreRef(); - - // Input min/max (itk::MinimumMaximumImageCalculator equivalent): one streaming bulk-I/O pass. Only min/max - // are consumed, so the parallel min/max reduction replaces the full statistics pass. - Result> statsResult = ComputeArrayMinMax(inStore, shouldCancel); - if(statsResult.invalid()) - { - return ConvertResult(std::move(statsResult)); - } - if(shouldCancel) - { - return {}; - } - const ArrayMinMax& stats = statsResult.value(); - - // m_UpperBoundary (ITK): the Upper Boundary parameter clamped to T's representable range -- FIXED for the - // whole run (unlike the local bisection `upperBound` below, which the loop mutates). - const T upperBoundaryFixed = ClampThresholdMaxCCUpperBoundary(upperBoundary); - - T lowerBound = stats.min; - T upperBound = std::min(stats.max, upperBoundaryFixed); - - T midpoint = (upperBound - lowerBound) / 2; - T midpointL = lowerBound + (midpoint - lowerBound) / 2; - T midpointR = upperBound - (upperBound - midpoint) / 2; - - const uint64 minSize = static_cast(minimumObjectSizeInPixels); - // ITK's ComputeConnectedComponents (itkThresholdMaximumConnectedComponentsImageFilter.hxx:76-81,108-110) counts - // components on the BINARY-THRESHOLD OUTPUT, whose foreground is `value != 0`: the internal BinaryThresholdImageFilter - // writes m_InsideValue to in-band pixels [thr, m_UpperBoundary] and m_OutsideValue elsewhere, then the - // ConnectedComponentImageFilter (background=0) labels every NONZERO pixel. So a pixel is counted-foreground iff its - // threshold output would be nonzero -- (in-band ? InsideValue!=0 : OutsideValue!=0) -- NOT simply "in-band". For the - // DEFAULT (InsideValue=1, OutsideValue=0) this reduces to exactly (in-band ? true : false) = in-band, unchanged; for - // non-default Inside/Outside (e.g. Inside=0/Outside=1) ITK instead maximizes components in the OUT-of-band region. - // The internal ConnectedComponentImageFilter connectivity is ITK's default (FullyConnected=false). - const bool insideNonZero = (insideValue != 0); - const bool outsideNonZero = (outsideValue != 0); - auto countAt = [&](T thr) -> Result { - const auto pred = [thr, upperBoundaryFixed, insideNonZero, outsideNonZero](T v) { return (v >= thr && v <= upperBoundaryFixed) ? insideNonZero : outsideNonZero; }; - return CountConnectedComponents(inStore, dims, pred, /*fullyConnected=*/false, minSize, shouldCancel); - }; - - while((upperBound - lowerBound) > T{2}) - { - if(shouldCancel) - { - return {}; - } - Result rightResult = countAt(midpointR); - if(rightResult.invalid()) - { - return ConvertResult(std::move(rightResult)); - } - Result leftResult = countAt(midpointL); - if(leftResult.invalid()) - { - return ConvertResult(std::move(leftResult)); - } - - // itkThresholdMaximumConnectedComponentsImageFilter.hxx::GenerateData: ties (right <= left) take the ELSE - // branch -- i.e. the LOWER threshold wins on a tie. - if(rightResult.value() > leftResult.value()) - { - lowerBound = midpoint; - midpoint = midpointR; - } - else - { - upperBound = midpoint; - midpoint = midpointL; - } - - midpointL = lowerBound + (midpoint - lowerBound) / 2; - midpointR = upperBound - (upperBound - midpoint) / 2; - } - - const T thresholdValue = midpoint; - - // Final binary threshold [thresholdValue, upperBoundaryFixed] -> insideValue/outsideValue, streamed in a - // bounded, working-memory-derived band instead of a fixed 64 KiB chunk (identical in-core and out-of-core). - // A 64 KiB call is smaller than one store chunk at the certified geometry (a Z-plane is exactly one 1 MiB - // chunk), so every call touched only part of a single chunk and the codec never left its serial branch. - // Reserving from the shared working-memory budget widens each call to many whole chunks when the grant - // allows it, and degrades to exactly the previous 64 KiB floor -- never smaller -- under a tight grant. - const usize total = inStore.getSize(); - constexpr usize k_FinalPassMinimumValues = 65536; - constexpr usize k_FinalPassPreferredBytes = 32ULL * 1024ULL * 1024ULL; - constexpr usize k_FinalPassValueBytes = sizeof(T) + sizeof(uint8); - const bool finalPassByteCountFits = total <= std::numeric_limits::max() / k_FinalPassValueBytes; - const uint64 usefulFinalPassBytes = finalPassByteCountFits ? static_cast(total) * k_FinalPassValueBytes : std::numeric_limits::max(); - auto finalPassReservation = ReserveWorkingMemory(k_FinalPassPreferredBytes, usefulFinalPassBytes); - const usize chunkValues = - std::max(k_FinalPassMinimumValues, std::min(total, static_cast(std::min(finalPassReservation.sizeBytes() / k_FinalPassValueBytes, std::numeric_limits::max())))); - // shrinkTo is a no-op when the actual footprint is not smaller than the grant (e.g. the k_FinalPassMinimumValues - // floor under a tight grant), and otherwise releases the unused portion back to the shared budget immediately, - // rather than holding it for this call's remaining lifetime. - finalPassReservation.shrinkTo(static_cast(std::min(chunkValues, total)) * k_FinalPassValueBytes); - auto inBuffer = std::make_unique(std::min(chunkValues, total)); - auto outBuffer = std::make_unique(std::min(chunkValues, total)); - for(usize start = 0; start < total; start += chunkValues) - { - if(shouldCancel) - { - return {}; - } - const usize count = std::min(chunkValues, total - start); - if(Result<> r = inStore.copyIntoBuffer(start, nonstd::span(inBuffer.get(), count)); r.invalid()) - { - return r; - } - for(usize i = 0; i < count; ++i) - { - const T v = inBuffer[i]; - outBuffer[i] = (v >= thresholdValue && v <= upperBoundaryFixed) ? insideValue : outsideValue; - } - if(Result<> r = outStore.copyFromBuffer(start, nonstd::span(outBuffer.get(), count)); r.invalid()) - { - return r; - } - } - return {}; + const auto& input = dataStructure.getDataRefAs>(inputArrayPath).getDataStoreRef(); + auto& output = dataStructure.getDataRefAs>(outputArrayPath).getDataStoreRef(); + return ApplyThresholdMaximumConnectedComponents(input, output, dims, Options, shouldCancel, messageHandler); } }; - } // namespace } // namespace detail // ----------------------------------------------------------------------------- Result<> ExecuteConnectedComponentImageFilter(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& outputArrayPath, bool fullyConnected, - const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler) + const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler, ConnectedComponentLabelLimitHandling labelLimitHandling) { using TypeSetPolicy = IntegerOnly; const auto& inputArray = dataStructure.getDataRefAs(inputArrayPath); const DataType inputType = inputArray.getDataType(); const auto& imageGeom = dataStructure.getDataRefAs(imageGeomPath); - detail::ConnectedComponentExecuteFn executeFn{dataStructure, inputArrayPath, outputArrayPath, imageGeom.getDimensions(), fullyConnected, shouldCancel, messageHandler}; + detail::ConnectedComponentExecuteFn executeFn{dataStructure, inputArrayPath, outputArrayPath, imageGeom.getDimensions(), fullyConnected, shouldCancel, messageHandler, labelLimitHandling}; return TypeSetPolicy::dispatch(inputType, executeFn); } @@ -935,8 +771,14 @@ Result<> ExecuteThresholdMaximumConnectedComponentsImageFilter(DataStructure& da const auto& inputArray = dataStructure.getDataRefAs(inputArrayPath); const DataType inputType = inputArray.getDataType(); const auto& imageGeom = dataStructure.getDataRefAs(imageGeomPath); - detail::ThresholdMaxCCExecuteFn executeFn{dataStructure, inputArrayPath, outputArrayPath, imageGeom.getDimensions(), minimumObjectSizeInPixels, upperBoundary, insideValue, - outsideValue, shouldCancel, messageHandler}; + const ThresholdMaxCCOptions options{.MinimumObjectSize = minimumObjectSizeInPixels, .UpperBoundary = upperBoundary, .InsideValue = insideValue, .OutsideValue = outsideValue}; + const detail::ThresholdMaxCCExecuteFn executeFn{.dataStructure = dataStructure, + .inputArrayPath = inputArrayPath, + .outputArrayPath = outputArrayPath, + .dims = imageGeom.getDimensions(), + .Options = options, + .shouldCancel = shouldCancel, + .messageHandler = messageHandler}; return TypeSetPolicy::dispatch(inputType, executeFn); } diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/GaussianImageFilterExecutors.cpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/GaussianImageFilterExecutors.cpp index a5309638eb..d181920395 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/GaussianImageFilterExecutors.cpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/GaussianImageFilterExecutors.cpp @@ -1,12 +1,18 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" +#include "NXImageProcessing/utils/SmoothingRecursiveGaussian2D.hpp" +#include "NXImageProcessing/utils/TerminalConversionDiagnostics.hpp" + +#include "simplnx/Common/Result.hpp" #include "simplnx/DataStructure/DataArray.hpp" #include "simplnx/Utilities/AlgorithmDispatch.hpp" #include "simplnx/Utilities/DataStoreUtilities.hpp" #include "simplnx/Utilities/ImageProcessing/DiscreteGaussianEngine.hpp" #include "simplnx/Utilities/ImageProcessing/GradientMagnitudeEngine.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageProcessingConstants.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" #include "simplnx/Utilities/ImageProcessing/RecursiveGaussianEngine.hpp" +#include "simplnx/Utilities/ImageProcessing/TerminalImageConversion.hpp" #include #include @@ -221,21 +227,27 @@ template Result<> ApplySmoothingRecursiveGaussian3D(const AbstractDataStore& input, AbstractDataStore& output, WorkStoreT& work, const SizeVec3& dims, const FloatVec3& spacing, const std::vector& sigma, bool normalizeAcrossScale, const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler) { - if(Result<> result = RecursiveGaussianAxisPass(input, work, dims, 2, sigma[2], static_cast(spacing[2]), 0, normalizeAcrossScale, shouldCancel, messageHandler); result.invalid()) + detail::TerminalConversionState conversionState(output.getSize()); + RecursiveGaussianPassOptions options; + options.CheckedSmoothing = true; + Result<> accumulated = RecursiveGaussianAxisPass(input, work, dims, 2, sigma[2], static_cast(spacing[2]), 0, normalizeAcrossScale, shouldCancel, messageHandler, options); + if(accumulated.invalid()) { - return result; + return accumulated; } std::vector outputPlane(dims[0] * dims[1]); auto outputSink = [&](usize planeOffset, nonstd::span filteredPlane) -> Result<> { - for(usize index = 0; index < filteredPlane.size(); ++index) + if(!detail::ConvertTerminalImageBuffer(nonstd::span(filteredPlane.data(), filteredPlane.size()), nonstd::span(outputPlane.data(), filteredPlane.size()), planeOffset, + conversionState, shouldCancel)) { - outputPlane[index] = static_cast(filteredPlane[index]); + return {}; } return output.copyFromBuffer(planeOffset, nonstd::span(outputPlane.data(), filteredPlane.size())); }; - const RecursiveGaussianPlaneAxis first{0, sigma[0], static_cast(spacing[0]), 0, normalizeAcrossScale}; - const RecursiveGaussianPlaneAxis second{1, sigma[1], static_cast(spacing[1]), 0, normalizeAcrossScale}; - return RecursiveGaussianXYPlaneCascadeToSink(work, dims, first, second, shouldCancel, messageHandler, outputSink); + const RecursiveGaussianPlaneAxis first{.axis = 0, .sigma = sigma[0], .spacing = static_cast(spacing[0]), .order = 0, .normalizeAcrossScale = normalizeAcrossScale, .CheckedSmoothing = true}; + const RecursiveGaussianPlaneAxis second{.axis = 1, .sigma = sigma[1], .spacing = static_cast(spacing[1]), .order = 0, .normalizeAcrossScale = normalizeAcrossScale, .CheckedSmoothing = true}; + accumulated = MergeResults(std::move(accumulated), RecursiveGaussianXYPlaneCascadeToSink(work, dims, first, second, shouldCancel, messageHandler, outputSink)); + return detail::ReportSmoothingGaussianConversion(conversionState, std::move(accumulated)); } template @@ -333,29 +345,6 @@ Result<> ApplyLaplacianRecursiveGaussian2D(const AbstractDataStore& input, Ab return {}; } -template -Result<> ApplySmoothingRecursiveGaussian2D(const AbstractDataStore& input, AbstractDataStore& output, WorkStoreT& work, CheckpointStoreT& checkpoints, const SizeVec3& dims, - const FloatVec3& spacing, const std::vector& sigma, bool normalizeAcrossScale, const detail::RecursiveGaussian2DBufferPlan& plan, - const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler) -{ - std::vector outputBuffer; - auto terminalSink = [&](usize yBegin, usize xBegin, usize rowCount, usize columnCount, nonstd::span filtered, nonstd::span) -> Result<> { - if constexpr(std::is_same_v) - { - return ImageProcessing::WriteRecursiveGaussian2DBlock(output, dims[0], yBegin, xBegin, rowCount, columnCount, nonstd::span(filtered.data(), filtered.size())); - } - outputBuffer.resize(filtered.size()); - for(usize index = 0; index < filtered.size(); ++index) - { - outputBuffer[index] = static_cast(filtered[index]); - } - return ImageProcessing::WriteRecursiveGaussian2DBlock(output, dims[0], yBegin, xBegin, rowCount, columnCount, nonstd::span(outputBuffer.data(), outputBuffer.size())); - }; - const RecursiveGaussianPlaneAxis smoothY{1, sigma[1], static_cast(spacing[1]), 0, normalizeAcrossScale}; - const RecursiveGaussianPlaneAxis smoothX{0, sigma[0], static_cast(spacing[0]), 0, normalizeAcrossScale}; - return RecursiveGaussian2DYXCascadeToSink(input, work, checkpoints, dims, smoothY, smoothX, plan, shouldCancel, messageHandler, terminalSink); -} - /// @brief Dispatched execute body for the GradientMagnitudeRecursiveGaussian filter. /// Input is a T-typed scalar image and output is a fixed float32 gradient-magnitude image. For each filtered axis, it /// differentiates along that axis, smooths along every other axis, and accumulates the squared, spacing-scaled result. @@ -891,17 +880,22 @@ struct SmoothingRecursiveGaussianExecuteFn if(usePlaneCascade) { std::vector outputPlane(dims[0] * dims[1]); + detail::TerminalConversionState conversionState(outStore.getSize()); auto outputSink = [&](usize planeOffset, nonstd::span filteredPlane) -> Result<> { - for(usize i = 0; i < filteredPlane.size(); ++i) + if(!detail::ConvertTerminalImageBuffer(nonstd::span(filteredPlane.data(), filteredPlane.size()), nonstd::span(outputPlane.data(), filteredPlane.size()), planeOffset, + conversionState, shouldCancel)) { - outputPlane[i] = static_cast(filteredPlane[i]); + return {}; } return outStore.copyFromBuffer(planeOffset, nonstd::span(outputPlane.data(), filteredPlane.size())); }; - const RecursiveGaussianPlaneAxis first{1, sigma[1], static_cast(spacing[1]), 0, normalizeAcrossScale}; - const RecursiveGaussianPlaneAxis second{0, sigma[0], static_cast(spacing[0]), 0, normalizeAcrossScale}; - return RecursiveGaussianXYPlaneCascadeToSink(inStore, dims, first, second, shouldCancel, messageHandler, outputSink); + const RecursiveGaussianPlaneAxis first{ + .axis = 1, .sigma = sigma[1], .spacing = static_cast(spacing[1]), .order = 0, .normalizeAcrossScale = normalizeAcrossScale, .CheckedSmoothing = true}; + const RecursiveGaussianPlaneAxis second{ + .axis = 0, .sigma = sigma[0], .spacing = static_cast(spacing[0]), .order = 0, .normalizeAcrossScale = normalizeAcrossScale, .CheckedSmoothing = true}; + Result<> result = RecursiveGaussianXYPlaneCascadeToSink(inStore, dims, first, second, shouldCancel, messageHandler, outputSink); + return detail::ReportSmoothingGaussianConversion(conversionState, std::move(result)); } const std::string format = detail::SelectRecursiveGaussianWorkingDataFormat(inStore.getStoreType(), inStore.getDataFormat(), outStore.getStoreType(), outStore.getDataFormat()); @@ -918,27 +912,32 @@ struct SmoothingRecursiveGaussianExecuteFn } bool first = true; + Result<> accumulated; + RecursiveGaussianPassOptions options; + options.CheckedSmoothing = true; for(uint32 axis : axisOrder) { const double s = sigma[axis]; const double sp = static_cast(spacing[axis]); if(first) { - if(Result<> r = RecursiveGaussianAxisPass(inStore, work, dims, axis, s, sp, /*order=*/0, normalizeAcrossScale, shouldCancel, messageHandler); r.invalid()) + accumulated = MergeResults(std::move(accumulated), RecursiveGaussianAxisPass(inStore, work, dims, axis, s, sp, /*order=*/0, normalizeAcrossScale, shouldCancel, messageHandler, options)); + if(accumulated.invalid()) { - return r; + return accumulated; } first = false; } else { - if(Result<> r = RecursiveGaussianAxisPass(work, work, dims, axis, s, sp, /*order=*/0, normalizeAcrossScale, shouldCancel, messageHandler); r.invalid()) + accumulated = MergeResults(std::move(accumulated), RecursiveGaussianAxisPass(work, work, dims, axis, s, sp, /*order=*/0, normalizeAcrossScale, shouldCancel, messageHandler, options)); + if(accumulated.invalid()) { - return r; + return accumulated; } } } - return CastFloat32StoreTo(work, outStore, shouldCancel); + return MergeResults(std::move(accumulated), CastFloat32StoreTo(work, outStore, shouldCancel, detail::ReportSmoothingGaussianConversion)); } }; @@ -1027,8 +1026,28 @@ Result<> ExecuteSmoothingRecursiveGaussianImageFilter(DataStructure& dataStructu const auto& imageGeom = dataStructure.getDataRefAs(imageGeomPath); const SizeVec3 dims = imageGeom.getDimensions(); const FloatVec3 spacing = imageGeom.getSpacing(); + if(Result<> controls = detail::ValidateSmoothingGaussianControls(sigma, spacing, dims); controls.invalid()) + { + controls.errors().front().message += fmt::format(" Image Geometry '{}'.", imageGeomPath.toString()); + return controls; + } detail::SmoothingRecursiveGaussianExecuteFn executeFn{dataStructure, inputArrayPath, outputArrayPath, dims, spacing, sigma, normalizeAcrossScale, shouldCancel, messageHandler}; - return TypeSetPolicy::dispatch(inputType, executeFn); + Result<> result = TypeSetPolicy::dispatch(inputType, executeFn); + if(result.invalid()) + { + for(auto& error : result.errors()) + { + error.message += fmt::format(" Output array '{}'.", outputArrayPath.toString()); + } + } + for(auto& warning : result.warnings()) + { + if(warning.code == k_SmoothingGaussianClippedIntegerOutput) + { + warning.message += fmt::format(" Output array '{}'.", outputArrayPath.toString()); + } + } + return result; } // ----------------------------------------------------------------------------- diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutorDetail.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutorDetail.hpp index 905a3cea5d..b790689127 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutorDetail.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutorDetail.hpp @@ -3,9 +3,12 @@ #include "NXImageProcessing/utils/ImageFilterExecutors.hpp" #include "simplnx/Common/Range.hpp" +#include "simplnx/Common/TypesUtility.hpp" #include "simplnx/DataStructure/AbstractDataStore.hpp" #include "simplnx/DataStructure/DataStore.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" +#include "simplnx/Utilities/ImageProcessing/ImageTransferResult.hpp" +#include "simplnx/Utilities/ImageProcessing/MorphologicalReconstructionEngine.hpp" #include "simplnx/Utilities/ImageProcessing/StreamingStatistics.hpp" #include "simplnx/Utilities/ParallelDataAlgorithm.hpp" @@ -608,8 +611,8 @@ Result<> CropSubtractFromStore(const AbstractDataStore& padded, const Abstrac * stays bounded (a fixed chunk for the height markers, one z-plane for Fillhole), so an out-of-core input * yields an out-of-core-bounded marker. @p dims is (X,Y,Z); @p height feeds MinusHeight/PlusHeight only. * - * MinusHeight/PlusHeight offset every voxel by +/-height through @ref SaturateCastFromDouble, so an offset that - * leaves the type range saturates (ITK-faithful clamp) instead of wrapping. + * For integer pixels an exact offset preserves native units, including values beyond float64 precision. + * A floating offset uses floating-point arithmetic. Both paths saturate integer marker values to native bounds. * * The Fillhole/GrindPeak marker border is the boundary in ITK's EFFECTIVE dimensionality: the legacy filter * processes a (W,H,1) volume as a 2D ITK image (ITKArrayHelper selects Dimension 2 when Z==1), so X and Y are always @@ -619,14 +622,23 @@ Result<> CropSubtractFromStore(const AbstractDataStore& padded, const Abstrac * rule, including "needle" geometries where a non-collapsed axis has extent 1 (every voxel is then a border voxel * and the image is left unchanged). * - * @pre @p markerStore has the same tuple/element layout as @p inStore (X fastest). @tparam T scalar type. + * @tparam T Scalar marker type. + * @param inStore Original mask values. + * @param markerStore Receives marker values; has the input's tuple and element layout. + * @param dims Image dimensions in X, Y, Z order. + * @param kind Selects a height or border marker. + * @param height Prepared offset in intensity units. + * @param shouldCancel Requests cancellation between transfers. + * @return The first transfer or dimension error, or a valid result. + * @pre @p markerStore has the same tuple/element layout as @p inStore (X fastest). */ template -Result<> BuildReconstructionMarker(const AbstractDataStore& inStore, AbstractDataStore& markerStore, const SizeVec3& dims, ReconMarker kind, float64 height, const std::atomic_bool& shouldCancel) +Result<> BuildReconstructionMarker(const AbstractDataStore& inStore, AbstractDataStore& markerStore, const SizeVec3& dims, ReconMarker kind, const ReconstructionHeight& height, + const std::atomic_bool& shouldCancel) { if(kind == ReconMarker::MinusHeight || kind == ReconMarker::PlusHeight) { - const float64 signedHeight = (kind == ReconMarker::MinusHeight) ? -height : height; + const bool lower = kind == ReconMarker::MinusHeight; const usize total = inStore.getSize(); const usize chunkValues = inStore.getStoreType() == IDataStore::StoreType::OutOfCore || markerStore.getStoreType() == IDataStore::StoreType::OutOfCore ? std::max(1, (64ULL * 1024ULL * 1024ULL) / sizeof(T)) : @@ -643,10 +655,7 @@ Result<> BuildReconstructionMarker(const AbstractDataStore& inStore, Abstract { return r; } - for(usize i = 0; i < count; ++i) - { - buffer[i] = SaturateCastFromDouble(static_cast(buffer[i]) + signedHeight); - } + ApplyReconstructionHeight(nonstd::span(buffer.get(), count), height, lower); if(Result<> r = markerStore.copyFromBuffer(start, nonstd::span(buffer.get(), count)); r.invalid()) { return r; @@ -865,5 +874,388 @@ inline usize SelectRelabelStagingValues(usize numValues, uint64 grantedBytes, us return stagingSlabs == 0 ? fallbackValues : stagingSlabs * slabPlan->slabValues; } +/** + * @brief Subtracts HConvex reconstruction values in one owned resident range without signed overflow. + * @tparam T Signed integer scalar type. + * @param inputValues Original image values. + * @param reconstructionValues Reconstruction values, each no greater than the corresponding input. + * @param outputValues Contrast output; may alias either input span. + * @param start Global tuple offset for diagnostics. + * @param inputPath Original array path for diagnostics. + * @return The first contrast overflow, or a valid result. + */ +template +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters) -- The two read-only spans have the same type but distinct subtraction roles. +Result<> SubtractHConvexContrastRange(nonstd::span inputValues, nonstd::span reconstructionValues, nonstd::span outputValues, usize start, const DataPath& inputPath) +{ + static_assert(std::is_integral_v && std::is_signed_v); + const usize count = inputValues.size(); + std::atomic firstInvalid{count}; + ParallelDataAlgorithm parallelAlgorithm; + parallelAlgorithm.setRange(0, count); + parallelAlgorithm.execute([=, &firstInvalid](const Range& range) { + for(usize index = range.min(); index < range.max(); ++index) + { + const T inputValue = inputValues[index]; + const T reconstructionValue = reconstructionValues[index]; + // max + a negative value is representable. Check before subtracting, including for int64 minima. + if(reconstructionValue < 0 && inputValue > std::numeric_limits::max() + reconstructionValue) + { + PublishSmallerIndex(firstInvalid, index); + continue; + } + outputValues[index] = static_cast(inputValue - reconstructionValue); + } + }); + const usize invalid = firstInvalid.load(std::memory_order_relaxed); + if(invalid != count) + { + constexpr int32 k_HConvexContrastOverflow = -29102; + return MakeErrorResult(k_HConvexContrastOverflow, + fmt::format("H Convex contrast at tuple {} of input array '{}' exceeds the {} output maximum {}. Reduce Height or explicitly convert the input to a wider or " + "floating-point type before this filter.", + start + invalid, inputPath.toString(), DataTypeToString(GetDataType()), std::numeric_limits::max())); + } + return {}; +} + +/** + * @brief Computes signed HConvex contrast through bounded chunks with serial store transfers. + * @tparam T Signed integer scalar type. + * @param input Original image store. + * @param reconstruction Reconstruction store. + * @param output Contrast output; may alias reconstruction. + * @param inputPath Original array path for diagnostics. + * @param shouldCancel Requests cancellation between chunks. + * @param chunkValues Maximum number of values in each owned buffer. + * @return The first transfer or contrast error, with warnings from completed transfers. + */ +template +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters) -- The input and reconstruction are distinct stores of the same element type. +Result<> SubtractHConvexContrastChunked(const AbstractDataStore& input, const AbstractDataStore& reconstruction, AbstractDataStore& output, const DataPath& inputPath, + const std::atomic_bool& shouldCancel, usize chunkValues = k_ElementwiseChunkValues) +{ + static_assert(std::is_integral_v && std::is_signed_v); + const usize size = input.getSize(); + chunkValues = std::max(1, chunkValues); + auto inputBuffer = std::make_unique>(std::min(chunkValues, size)); + auto reconstructionBuffer = std::make_unique>(std::min(chunkValues, size)); + Result<> accumulatedResult; + for(usize start = 0; start < size; start += chunkValues) + { + if(shouldCancel) + { + return accumulatedResult; + } + const usize count = std::min(chunkValues, size - start); + AccumulateTransferResult(accumulatedResult, input.copyIntoBuffer(start, nonstd::span(inputBuffer->data(), count))); + if(accumulatedResult.invalid()) + { + return accumulatedResult; + } + AccumulateTransferResult(accumulatedResult, reconstruction.copyIntoBuffer(start, nonstd::span(reconstructionBuffer->data(), count))); + if(accumulatedResult.invalid()) + { + return accumulatedResult; + } + AccumulateTransferResult(accumulatedResult, SubtractHConvexContrastRange(nonstd::span(inputBuffer->data(), count), nonstd::span(reconstructionBuffer->data(), count), + nonstd::span(inputBuffer->data(), count), start, inputPath)); + if(accumulatedResult.invalid()) + { + return accumulatedResult; + } + AccumulateTransferResult(accumulatedResult, output.copyFromBuffer(start, nonstd::span(inputBuffer->data(), count))); + if(accumulatedResult.invalid()) + { + return accumulatedResult; + } + } + return accumulatedResult; +} + +/** + * @brief Computes HConvex contrast, preserving the resident fast path and bounded serial store transfers. + * @tparam T Numeric scalar type. + * @param input Original image store. + * @param reconstruction Reconstruction store. + * @param output Contrast output; may alias reconstruction. + * @param inputPath Original array path for diagnostics. + * @param shouldCancel Requests cancellation before resident work or between chunks. + * @return The first transfer or signed contrast error, with warnings from completed transfers. + * + * Unsigned and floating arrays retain the existing subtraction. Signed arrays check before each subtraction. + * Completed chunks may already contain contrast when a later chunk fails; this operation does not promise atomic output. + */ +template +Result<> SubtractHConvexContrast(const AbstractDataStore& input, const AbstractDataStore& reconstruction, AbstractDataStore& output, const DataPath& inputPath, + const std::atomic_bool& shouldCancel) +{ + if constexpr(!std::is_integral_v || !std::is_signed_v) + { + return SubtractStores(input, reconstruction, output, shouldCancel); + } + else + { + if(shouldCancel) + { + return {}; + } + const auto* residentInputPtr = dynamic_cast*>(&input); + const auto* residentReconstructionPtr = dynamic_cast*>(&reconstruction); + auto* residentOutputPtr = dynamic_cast*>(&output); + if(residentInputPtr != nullptr && residentReconstructionPtr != nullptr && residentOutputPtr != nullptr) + { + const auto inputValues = residentInputPtr->createSpan(); + const auto reconstructionValues = residentReconstructionPtr->createSpan(); + auto outputValues = residentOutputPtr->createSpan(); + return SubtractHConvexContrastRange(inputValues, reconstructionValues, outputValues, 0, inputPath); + } + + return SubtractHConvexContrastChunked(input, reconstruction, output, inputPath, shouldCancel); + } +} + +inline constexpr int32 k_MarkerIdConversionError = -79073; +inline constexpr int32 k_MarkerIdConversionWarning = -79074; +inline constexpr int32 k_MarkerIdCopyAllocationFailed = -79075; +inline constexpr int32 k_MarkerIdRestoreAllocationFailed = -79076; + +/** @brief Constant-size native context for the existing bounded marker-copy pass. */ +template +class MarkerIdConversionState +{ +public: + MarkerIdConversionState() = default; + ~MarkerIdConversionState() noexcept = default; + MarkerIdConversionState(const MarkerIdConversionState&) = delete; + MarkerIdConversionState(MarkerIdConversionState&&) = delete; + MarkerIdConversionState& operator=(const MarkerIdConversionState&) = delete; + MarkerIdConversionState& operator=(MarkerIdConversionState&&) = delete; + + bool observe(usize index, T nativeValue, uint32 encodedValue) noexcept + { + const T restoredValue = static_cast(encodedValue); + if(restoredValue == nativeValue) + { + return false; + } + if(m_ChangedCount == 0) + { + m_FirstIndex = index; + m_FirstNativeValue = nativeValue; + m_FirstRestoredValue = restoredValue; + } + ++m_ChangedCount; + return true; + } + + Result<> finish(const DataPath& markerPath, MarkerIdConversionHandling handling, Result<> result = {}) const + { + if(m_ChangedCount == 0) + { + return result; + } + const auto context = fmt::format("Marker array '{}' has {} changed marker occurrence(s) observed. First change at flat index {}: native ID {} restores as {} after uint32 conversion. ", + markerPath.toString(), m_ChangedCount, m_FirstIndex, m_FirstNativeValue, m_FirstRestoredValue); + if(handling == MarkerIdConversionHandling::Error) + { + return MergeResults(std::move(result), + MakeErrorResult(k_MarkerIdConversionError, + context + "Execution stopped before flooding. Use IDs that round-trip, or select 'Warn and Continue (Legacy Behavior)' under " + "'Marker ID Conversion Handling' only if you intentionally accept seed loss, renamed IDs, merged basins, and incorrect region measurements.")); + } + return MergeResults(std::move(result), MakeWarningVoidResult(k_MarkerIdConversionWarning, + context + "'Warn and Continue (Legacy Behavior)' retains the old conversion and flood. Seeds can disappear or merge, IDs can be " + "renamed, and basin boundaries, region sizes, and downstream feature measurements can be incorrect.")); + } + +private: + usize m_ChangedCount = 0; + usize m_FirstIndex = 0; + T m_FirstNativeValue = {}; + T m_FirstRestoredValue = {}; +}; + +/** + * @brief Functor that copies an integer marker array's values into a uint32 store, dispatched on + * the source element type S via the IntegerOnly policy (which calls operator()() through + * ExecuteDataFunctionIntType). The source is read through the SAFE typed accessor + * getDataRefAs> -- not a raw dynamic_cast -- so a type mismatch throws rather than being UB. + * Single-component is guaranteed by the caller's preflight, so getSize() (values) == the tuple count. + */ +struct WidenIntegerArrayToUInt32Fn +{ + const DataStructure& dataStructure; + const DataPath& srcPath; + AbstractDataStore& dst; + const std::atomic_bool& shouldCancel; + MarkerIdConversionHandling ConversionHandling = MarkerIdConversionHandling::Error; + + template + Result<> operator()() const + { + const AbstractDataStore& s = dataStructure.getDataRefAs>(srcPath).getDataStoreRef(); + const usize total = s.getSize(); + MarkerIdConversionState conversionState; + Result<> accumulated; + try + { + constexpr usize chunkValues = 65536; + std::vector inputValues(std::min(chunkValues, total)); + std::vector encodedValues(std::min(chunkValues, total)); + for(usize start = 0; start < total;) + { + if(shouldCancel) + { + return conversionState.finish(srcPath, ConversionHandling, std::move(accumulated)); + } + const usize count = std::min(chunkValues, total - start); + AccumulateTransferResult(accumulated, s.copyIntoBuffer(start, nonstd::span(inputValues.data(), count))); + if(accumulated.invalid()) + { + return conversionState.finish(srcPath, ConversionHandling, std::move(accumulated)); + } + for(usize index = 0; index < count; ++index) + { + const S nativeValue = inputValues[index]; + // Promote narrow signed IDs without changing the legacy conversion modulo 2^32. + const uint32 encodedValue = static_cast(+nativeValue); + if(conversionState.observe(start + index, nativeValue, encodedValue) && ConversionHandling == MarkerIdConversionHandling::Error) + { + // Stop before writing this chunk or entering either flood route. + return conversionState.finish(srcPath, ConversionHandling, std::move(accumulated)); + } + encodedValues[index] = encodedValue; + } + AccumulateTransferResult(accumulated, dst.copyFromBuffer(start, nonstd::span(encodedValues.data(), count))); + if(accumulated.invalid()) + { + return conversionState.finish(srcPath, ConversionHandling, std::move(accumulated)); + } + // count <= total - start, so both the next offset and start + index remain in range. + start += count; + } + return conversionState.finish(srcPath, ConversionHandling, std::move(accumulated)); + } catch(const std::bad_alloc&) + { + return conversionState.finish( + srcPath, ConversionHandling, + MergeResults(std::move(accumulated), MakeErrorResult(k_MarkerIdCopyAllocationFailed, "Morphological watershed could not allocate working storage while copying marker IDs."))); + } + } +}; + +/** + * @brief Copies the integer marker array at @p srcPath (any of the 8 integer element types) into @p dst as uint32. + * The flood runs in uint32 (see @ref ApplyWatershedFromMarkers) but the marker array may be any integer + * type. All native 8/16/32-bit integers round-trip, including negative signed values. The lossless int64/uint64 + * domain is 0 through UINT32_MAX, inclusive. Error stops during this copy before the affected chunk is written; + * Warn keeps the legacy encoding and returns one summary warning, also on cancellation or a later transfer error. + */ +inline Result<> WidenIntegerArrayToUInt32(const DataStructure& dataStructure, const DataPath& srcPath, AbstractDataStore& dst, const std::atomic_bool& shouldCancel, + MarkerIdConversionHandling conversionHandling = MarkerIdConversionHandling::Error) +{ + const auto& srcArray = dataStructure.getDataRefAs(srcPath); + return IntegerOnly::dispatch(srcArray.getDataType(), + WidenIntegerArrayToUInt32Fn{.dataStructure = dataStructure, .srcPath = srcPath, .dst = dst, .shouldCancel = shouldCancel, .ConversionHandling = conversionHandling}); +} + +/** + * @brief Functor that copies a uint32 store's values into an integer output array (narrowing cast), dispatched on + * the destination element type D via the IntegerOnly policy. The destination is written through the SAFE + * typed accessor getDataRefAs> -- not a raw dynamic_cast. The output is created of the marker's + * type by preflight. This is the legacy conversion back from the internal uint32 labels; Warn may have already + * removed, aliased, or renamed native 64-bit marker identities during the initial copy. + */ +struct NarrowUInt32StoreToIntegerArrayFn +{ + const AbstractDataStore& src; + DataStructure& dataStructure; + const DataPath& dstPath; + const std::atomic_bool& shouldCancel; + + template + Result<> operator()() const + { + AbstractDataStore& d = dataStructure.getDataRefAs>(dstPath).getDataStoreRef(); + const usize total = src.getSize(); + Result<> accumulated; + try + { + constexpr usize chunkValues = 65536; + std::vector encodedValues(std::min(chunkValues, total)); + std::vector outputValues(std::min(chunkValues, total)); + for(usize start = 0; start < total;) + { + if(shouldCancel) + { + return accumulated; + } + const usize count = std::min(chunkValues, total - start); + AccumulateTransferResult(accumulated, src.copyIntoBuffer(start, nonstd::span(encodedValues.data(), count))); + if(accumulated.invalid()) + { + return accumulated; + } + for(usize index = 0; index < count; ++index) + { + outputValues[index] = static_cast(encodedValues[index]); + } + AccumulateTransferResult(accumulated, d.copyFromBuffer(start, nonstd::span(outputValues.data(), count))); + if(accumulated.invalid()) + { + return accumulated; + } + start += count; // count <= total - start, including the final short chunk. + } + return accumulated; + } catch(const std::bad_alloc&) + { + return MergeResults(std::move(accumulated), MakeErrorResult(k_MarkerIdRestoreAllocationFailed, "Morphological watershed could not allocate working storage while restoring marker IDs.")); + } + } +}; + +/** + * @brief Narrows the uint32 flood output into the integer output array at @p dstPath (whose element type is the + * marker's type, set by the filter's preflight). Inverse of @ref WidenIntegerArrayToUInt32. + */ +inline Result<> NarrowUInt32StoreToIntegerArray(const AbstractDataStore& src, DataStructure& dataStructure, const DataPath& dstPath, const std::atomic_bool& shouldCancel) +{ + const auto& dstArray = dataStructure.getDataRefAs(dstPath); + return IntegerOnly::dispatch(dstArray.getDataType(), NarrowUInt32StoreToIntegerArrayFn{src, dataStructure, dstPath, shouldCancel}); +} + +/** + * @brief The border sentinel for the uint32 flood: static_cast(NumericTraits::max()). ITK's + * MorphologicalWatershedFromMarkers uses NumericTraits::max() as the out-of-bounds marker-image + * boundary constant. This value substitutes only out-of-bounds neighbors; UINT32_MAX is a valid in-bounds seed. + * For uint32/int64/uint64 the integer cast yields 0xFFFFFFFF. It does not saturate marker values. + */ +inline uint32 MarkerTypeMaxAsUInt32(DataType markerType) +{ + switch(markerType) + { + case DataType::int8: + return static_cast(std::numeric_limits::max()); + case DataType::uint8: + return static_cast(std::numeric_limits::max()); + case DataType::int16: + return static_cast(std::numeric_limits::max()); + case DataType::uint16: + return static_cast(std::numeric_limits::max()); + case DataType::int32: + return static_cast(std::numeric_limits::max()); + case DataType::uint32: + return static_cast(std::numeric_limits::max()); + case DataType::int64: + return static_cast(std::numeric_limits::max()); + case DataType::uint64: + return static_cast(std::numeric_limits::max()); + default: + return std::numeric_limits::max(); + } +} + } // namespace detail } // namespace nx::core::ImageProcessing diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutors.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutors.hpp index a1d1b70df2..764b923a71 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutors.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterExecutors.hpp @@ -15,6 +15,13 @@ namespace nx::core::ImageProcessing { +/** @brief Policy for native marker IDs that change during uint32 encoding and restoration. */ +enum class MarkerIdConversionHandling : uint8 +{ + Error = 0, + WarnAndContinueLegacy = 1 +}; + /** * @brief The composite grayscale-morphology operation to apply, each built from the Dilate/Erode * primitives (and, for the three difference forms, a single elementwise store subtraction): @@ -199,12 +206,47 @@ NXIMAGEPROCESSING_EXPORT Result<> ExecuteBinaryMorphologyCompositeImageFilter(Da * reconstruction result is subtracted from the input in place after reconstruction (output = input - * reconstruction). Output type == input type (SameAsInput). The caller's preflight must have enforced a * scalar input (@ref PreflightImageFilter requireScalar=true) and, for the height markers, a finite - * @p height. + * @p height. The marker offset uses floating-point arithmetic. + * @param dataStructure Owns the selected arrays and geometry. + * @param imageGeomPath Image geometry used for dimensions. + * @param inputArrayPath Scalar input image and reconstruction mask. + * @param outputArrayPath Receives reconstruction or contrast in the input type. + * @param op Selects reconstruction by dilation or erosion. + * @param fullyConnected Enables face, edge and vertex neighbors instead of faces only. + * @param markerKind Selects a height or border marker. + * @param height Validated finite height in intensity units. + * @param shouldCancel Requests cancellation during reconstruction and between transfers. + * @param messageHandler Receives progress messages. + * @param differenceFromInput Selects HConvex contrast with checked signed subtraction. + * @return A reconstruction, contrast or transfer error, or a valid result. */ NXIMAGEPROCESSING_EXPORT Result<> ExecuteMorphologicalReconstructionImageFilter(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& outputArrayPath, ReconstructOp op, bool fullyConnected, detail::ReconMarker markerKind, float64 height, const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler, bool differenceFromInput = false); +namespace detail +{ +/** + * @brief Reconstructs with a validated height. Integer images use an exact native offset. + * @param dataStructure Owns the selected arrays and geometry. + * @param imageGeomPath Image geometry used for dimensions. + * @param inputArrayPath Scalar input image and reconstruction mask. + * @param outputArrayPath Output image of the same type and shape as the input. + * @param op Reconstruction direction. + * @param fullyConnected Selects full connectivity when true. + * @param markerKind Selects the height marker. + * @param height Validated offset in intensity units. + * @param shouldCancel Requests cancellation during reconstruction and between transfers. + * @param messageHandler Receives progress messages. + * @param differenceFromInput Selects checked contrast subtraction when true. + * @return A reconstruction, contrast or transfer error, or a valid result. + * @pre Height is finite and nonnegative. Integer input requires a whole Height. + */ +Result<> ExecuteMorphologicalReconstructionWithValidatedHeight(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& outputArrayPath, + ReconstructOp op, bool fullyConnected, ReconMarker markerKind, float64 height, const std::atomic_bool& shouldCancel, + const IFilter::MessageHandler& messageHandler, bool differenceFromInput); +} // namespace detail + /** * @brief Execute opening-by-reconstruction (@p firstOp == Erode) or closing-by-reconstruction (@p firstOp == * Dilate): a grayscale morphological erode/dilate with @p se followed by a geodesic reconstruction of that @@ -364,11 +406,12 @@ NXIMAGEPROCESSING_EXPORT Result<> ExecuteApproximateSignedDistanceMapImageFilter * @brief Execute the (ITK-free) ConnectedComponent filter: labels foreground (non-zero) voxels of an integer scalar * image into consecutive uint32 components (background 0), via the streaming scanline union-find @ref * LabelConnectedComponents engine. The output is a FIXED uint32 label image, not the input element type. - * Reproduces legacy ITK's ConnectedComponentImageFilter label VALUES exactly (see the Parity model). The - * caller's preflight must have enforced an integer scalar input. + * Below the provisional uint32 capacity limit, preserves the legacy label values. Only this filter exposes + * legacy overflow continuation; shared consumers retain Error. The caller must enforce an integer scalar input. */ NXIMAGEPROCESSING_EXPORT Result<> ExecuteConnectedComponentImageFilter(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& outputArrayPath, - bool fullyConnected, const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler); + bool fullyConnected, const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler, + ConnectedComponentLabelLimitHandling labelLimitHandling = ConnectedComponentLabelLimitHandling::Error); /** * @brief Execute the (ITK-free) ZeroCrossing filter: marks the voxels closest to sign changes (zero crossings) among @@ -416,12 +459,11 @@ NXIMAGEPROCESSING_EXPORT Result<> ExecuteBinaryThinningImageFilter(DataStructure const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler); /** - * @brief Execute the (ITK-free) ThresholdMaximumConnectedComponents filter: bisection-searches the threshold value - * that MAXIMIZES the number of connected components (size >= MinimumObjectSizeInPixels) via @ref + * @brief Execute the native ThresholdMaximumConnectedComponents heuristic using component scores (size >= MinimumObjectSizeInPixels) via @ref * detail::ThresholdMaxCCExecuteFn (which uses @ref CountConnectedComponents each iteration), then writes the * final binary threshold [ThresholdValue, UpperBoundary] as a FIXED uint8 image (InsideValue/OutsideValue). - * Reproduces legacy ITK's ThresholdMaximumConnectedComponentsImageFilter output exactly (see the Parity - * model). The caller's preflight must have enforced a scalar input. + * Uses native safe arithmetic, the absolute two-unit stop and finite native bounds. + * The caller's preflight must have enforced a scalar input. */ NXIMAGEPROCESSING_EXPORT Result<> ExecuteThresholdMaximumConnectedComponentsImageFilter(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& outputArrayPath, uint32 minimumObjectSizeInPixels, float64 upperBoundary, uint8 insideValue, @@ -429,16 +471,17 @@ NXIMAGEPROCESSING_EXPORT Result<> ExecuteThresholdMaximumConnectedComponentsImag /** * @brief Execute the (ITK-free, out-of-core) MorphologicalWatershedFromMarkers filter: a marker-controlled - * hierarchical-queue (FAH) watershed flood (see @ref ApplyWatershedFromMarkers). - * Dispatches the grayscale input over the 10 numeric scalar types in @c AllNumeric. The marker array is - * any integer type and the output is created of the marker's type by the filter's preflight. Reproduces legacy - * ITK's MorphologicalWatershedFromMarkersImageFilter output EXACTLY, including label values (see the Parity - * model and the direct-ITK oracle test). The caller's preflight must have validated the grayscale (scalar, + * hierarchical-queue (FAH) watershed flood (see @ref ApplyWatershedFromMarkers). Dispatches on the grayscale + * input element type (all 10 scalar types); the marker array is + * any integer type and the output is created of the marker's type by preflight. Error protects native marker + * identity before flooding; Warn retains the legacy conversion and flood with one conversion diagnostic. + * The caller's preflight must have validated the grayscale (scalar, * allowed type, tuple==cells) and the marker (integer scalar, tuple==grayscale). */ NXIMAGEPROCESSING_EXPORT Result<> ExecuteMorphologicalWatershedFromMarkersImageFilter(DataStructure& dataStructure, const DataPath& imageGeomPath, const DataPath& inputArrayPath, const DataPath& markerArrayPath, const DataPath& outputArrayPath, bool markWatershedLine, bool fullyConnected, - const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler); + const std::atomic_bool& shouldCancel, const IFilter::MessageHandler& messageHandler, + MarkerIdConversionHandling conversionHandling = MarkerIdConversionHandling::Error); /** * @brief Execute the (ITK-free, out-of-core) MorphologicalWatershed filter: the ITK composite (HMinima -> diff --git a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp index 8d2077e69f..f0c8ab609b 100644 --- a/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp +++ b/src/Plugins/NXImageProcessing/src/NXImageProcessing/utils/ImageFilterTemplateExecutors.hpp @@ -6,14 +6,12 @@ #include "simplnx/Utilities/ImageProcessing/BoxNeighborhoodEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ContourEngine.hpp" #include "simplnx/Utilities/ImageProcessing/FiniteDifferenceEngine.hpp" -#include "simplnx/Utilities/ImageProcessing/HistogramEngine.hpp" #include "simplnx/Utilities/ImageProcessing/ImageProcessingFilterUtilities.hpp" #include "simplnx/Utilities/ImageProcessing/PointwiseEngine.hpp" #include "simplnx/Utilities/ImageProcessing/StreamingStatistics.hpp" #include #include -#include #include namespace nx::core::ImageProcessing @@ -134,59 +132,6 @@ struct ContourExecuteFn } }; -template