Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
98 commits
Select commit Hold shift + click to select a range
46c6bc2
BUG: Preserve fractional angles in AcosImageFilter
jmarquisbq Oct 26, 2026
4c26545
BUG: Preserve fractional angles in AsinImageFilter
jmarquisbq Oct 26, 2026
64ed19b
BUG: Preserve Exp range and fractional results for integer input
jmarquisbq Oct 26, 2026
96e3af5
BUG: Preserve negative exponential range for integer input
jmarquisbq Oct 26, 2026
9383ec9
BUG: Preserve natural logarithm results for integer input
jmarquisbq Oct 26, 2026
00b26e6
DOC: Clarify Exp pointwise buffer limits
jmarquisbq Oct 27, 2026
ce19dd4
DOC: Clarify ExpNegative pointwise buffer limits
jmarquisbq Oct 27, 2026
98d296a
DOC: Clarify Log pointwise buffer limits
jmarquisbq Oct 27, 2026
f391952
BUG: Preserve decimal logarithm results for integer input
jmarquisbq Oct 27, 2026
a4a4612
BUG: Preserve fractional square roots for integer input
jmarquisbq Oct 27, 2026
8708667
BUG: Preserve signed fractional tangent results
jmarquisbq Oct 27, 2026
47e785c
BUG: Widen integer squares and reject 64-bit overflow
jmarquisbq Oct 27, 2026
b9fe586
BUG: Preserve native HConvex markers and check signed contrast
jmarquisbq Oct 27, 2026
f68d4f6
BUG: Preserve native HMinima intensities and Height offsets
jmarquisbq Oct 27, 2026
9bf8b07
BUG: Check Curvature Flow terminal numeric conversions
jmarquisbq Oct 27, 2026
0539aac
BUG: Check recursive Gaussian smoothing conversions
jmarquisbq Oct 27, 2026
ca2383a
BUG: Guard Connected Component provisional label capacity
jmarquisbq Oct 27, 2026
28b0d21
BUG: Guard watershed marker ID conversion
jmarquisbq Oct 27, 2026
6aab281
BUG: Validate Otsu numeric input and add explicit masks
jmarquisbq Oct 27, 2026
9bd4469
BUG: Guard nonfinite color exports and native normalization
jmarquisbq Oct 27, 2026
75ba530
BUG: Correct threshold search arithmetic and nonfinite handling
jmarquisbq Oct 27, 2026
c94a865
BUG: Clarify ImageProcessing numeric migration help
jmarquisbq Oct 27, 2026
862799c
DOC: Complete ImageProcessing numeric helper contracts
jmarquisbq Oct 27, 2026
89369f3
BUG: Save C15 policy defaults in shipped pipelines
jmarquisbq Nov 2, 2026
88cc583
TEST: Check portable exponential underflow bounds
jmarquisbq Nov 3, 2026
1a1c0d0
STY: Use sized owners for C15 working buffers
jmarquisbq Nov 3, 2026
ad711f9
TEST: Verify C15 resident consumer chains
jmarquisbq Nov 3, 2026
019ca3c
BUG: Reserve Otsu scan payload before the optional ring
jmarquisbq Nov 3, 2026
9e157e3
BUG: Retain checked Curvature Flow tile warnings
jmarquisbq Nov 3, 2026
ec48d11
STY: Size the image writer byte-mask buffer
jmarquisbq Nov 3, 2026
a31a96c
BUG: Give new Otsu diagnostics unique codes
jmarquisbq Nov 3, 2026
682b4b7
PERF: Skip unused mask reads in integral color range scans
jmarquisbq Nov 3, 2026
a3a6aeb
BUG: Distinguish threshold transfer and fallback errors
jmarquisbq Nov 3, 2026
f397c6c
BUG: Scale finite color ranges at the rounded overflow bound
jmarquisbq Nov 3, 2026
612454a
TEST: Name the promoted Log10 output accurately
jmarquisbq Nov 3, 2026
71cedb4
REV: Address clang-tidy findings in C15 image processing
jmarquisbq Nov 3, 2026
e3370f3
REV: Resolve C15 clang-tidy diagnostics
jmarquisbq Nov 3, 2026
f9418c0
COMP: Match C15 sources to NXImageProcessing
jmarquisbq Nov 12, 2026
8b9c650
STY: Resolve C15 image-writer clang-tidy diagnostics
jmarquisbq Nov 12, 2026
9318456
BUG: Reject nonnumeric Otsu masks in preflight
jmarquisbq Nov 12, 2026
2996fb2
REV: Report image dimensions in size diagnostics
jmarquisbq Nov 12, 2026
1367f83
DOC: Correct Write Image input type guidance
jmarquisbq Nov 12, 2026
2ea4885
STY: Use local naming for the Otsu mask error constant
jmarquisbq Nov 12, 2026
51b14cc
DOC: Distinguish image conversion contracts
jmarquisbq Nov 16, 2026
336b722
DOC: Restore spacing in threshold examples
jmarquisbq Nov 16, 2026
dfb6894
DOC: Simplify image filter help
jmarquisbq Nov 16, 2026
b0c77e6
REV: Preserve warnings from raw image exports
jmarquisbq Nov 16, 2026
1197742
REV: Pass typed integer Heights to reconstruction
jmarquisbq Nov 16, 2026
425abc5
REV: Share image conversion state and caller diagnostics
jmarquisbq Nov 16, 2026
93ea054
DOC: Explain Connected Component wrap in the tooltip
jmarquisbq Nov 16, 2026
4e9fc6a
REV: Fit Otsu thresholds with finite samples only
jmarquisbq Nov 16, 2026
9c68e4b
REV: Report the first nonfinite threshold sample
jmarquisbq Nov 16, 2026
c3c9eea
REV: Name nonfinite input handling choices
jmarquisbq Nov 16, 2026
96e1d06
REV: Keep Otsu and cutoff validation in preflight
jmarquisbq Nov 16, 2026
e877af2
REV: Construct image results through the Result API
jmarquisbq Nov 16, 2026
f0a1176
REV: Assign and name image filter diagnostic codes
jmarquisbq Nov 16, 2026
a57a27f
STY: Match existing image member naming
jmarquisbq Nov 16, 2026
2569379
TEST: Load plugins only when image tests need them
jmarquisbq Nov 16, 2026
4dc3727
REV: Validate the final Otsu mask size and install the operation types
jmarquisbq Nov 17, 2026
2847444
REV: Address review findings for ImageProcessing numeric fixes
jmarquisbq Nov 17, 2026
d85bc54
TEST: Fix lint findings in the Gaussian pipeline regression
jmarquisbq Nov 18, 2026
a347f10
DOC: Define handling of nonfinite input arrays
jmarquisbq Nov 18, 2026
f208b80
DOC: Explain integer precision in H Convex reconstruction
jmarquisbq Nov 18, 2026
2b3b8f0
TEST: Name image filter integration cases by behavior
jmarquisbq Nov 18, 2026
3414c84
TEST: Cover allocation failure during watershed marker restoration
jmarquisbq Nov 18, 2026
28a1ded
REV: Give label and marker failures distinct diagnostics
jmarquisbq Nov 18, 2026
b7636cc
STY: Name the default label limit and marker conversion choices
jmarquisbq Nov 18, 2026
02439ad
TEST: Observe the effective Connected Component label policy
jmarquisbq Nov 18, 2026
529e939
STY: Order the installed image processing headers
jmarquisbq Nov 18, 2026
57d1fd2
REF: Remove the retired histogram executor templates
jmarquisbq Nov 18, 2026
19a6158
DOC: Describe storage resolution for floating angle outputs
jmarquisbq Nov 18, 2026
c2e8c21
BUG: Round-trip signed infinite threshold cutoffs in JSON and Python
jmarquisbq Nov 18, 2026
48af024
BUG: Round finite Float32 endpoint results before overflow
jmarquisbq Nov 18, 2026
dffae63
BUG: Validate smoothing spacing on the final image geometry
jmarquisbq Nov 18, 2026
53d3bdf
BUG: Count final smoothing conversions and preserve completed blocks
jmarquisbq Nov 18, 2026
698351c
BUG: Compute finite image ranges without an input validation control
jmarquisbq Nov 18, 2026
2dc5260
TEST: Verify image numeric helpers in the core test suite
jmarquisbq Nov 18, 2026
da48470
DOC: Explain wide-integer color differences between export routes
jmarquisbq Nov 18, 2026
829296c
TEST: Allow one Float64 step at the 64-bit log bound
jmarquisbq Nov 18, 2026
a4509db
REF: Share equivalent pointwise filter test setup
jmarquisbq Nov 18, 2026
c78eeaf
TEST: Cancel Square after its range scan starts
jmarquisbq Nov 18, 2026
5d45d68
STY: Use structured results in reconstruction regressions
jmarquisbq Nov 18, 2026
0cd517d
DOC: Link numeric filter help to its shipped example pipelines
jmarquisbq Nov 18, 2026
5298588
PERF: Run short masked Otsu label batches serially
jmarquisbq Nov 19, 2026
363e0a9
PERF: Reuse the validated reciprocal when binning Otsu samples
jmarquisbq Nov 19, 2026
97311ef
BUG: Validate Gaussian Z sigma against the final image depth
jmarquisbq Nov 19, 2026
c71ffd9
BUG: Prepare masked Otsu output before reserving label buffers
jmarquisbq Nov 19, 2026
dc96d67
TEST: Check the orientation of the smoothed image step
jmarquisbq Nov 19, 2026
d6ece81
BUG: Reject nonempty threshold stores for a zero-volume image
jmarquisbq Nov 19, 2026
104c7e9
BUG: Keep Square range-read warnings when the transfer fails
jmarquisbq Nov 19, 2026
3a62d17
BUG: Accumulate smoothing and image writer warnings in order
jmarquisbq Nov 19, 2026
2069db8
TEST: Use the shared backing-file assertion for image arrays
jmarquisbq Nov 19, 2026
8c3c2c6
STY: Include image processing declarations from their owning headers
jmarquisbq Nov 19, 2026
d351838
REV: Prepare threshold destinations before reserving output buffers
jmarquisbq Nov 19, 2026
e3628ac
REV: Preserve Square range-scan read warnings
jmarquisbq Nov 20, 2026
1ec5ed8
REV: Append transfer warnings in image processing loops
jmarquisbq Nov 20, 2026
76eebb1
DOC: Clarify Otsu classification precision for large integers
jmarquisbq Nov 20, 2026
d9517fe
DOC: Specify the tuple shape of the Write Image mask
jmarquisbq Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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()
Expand Down
73 changes: 39 additions & 34 deletions docs/Coding_Knowledge_Base.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<U>()`, 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<U>()` 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
Expand All @@ -760,9 +769,9 @@ general rule is in the numeric-correctness reference of `cpp-best-practices`.

**What to look for:** `static_cast<U>(floatingExpression)` where `U` can be integral.

**Pattern to use:** `SaturateCastFromDouble<U>()` 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

Expand All @@ -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
Expand All @@ -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

Expand Down
2 changes: 2 additions & 0 deletions src/Plugins/NXImageProcessing/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
39 changes: 36 additions & 3 deletions src/Plugins/NXImageProcessing/docs/AcosImageFilter.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
41 changes: 38 additions & 3 deletions src/Plugins/NXImageProcessing/docs/AsinImageFilter.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
Loading