Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions docs/Coding_Knowledge_Base.md
Original file line number Diff line number Diff line change
Expand Up @@ -1101,8 +1101,8 @@ chunks, of the same store can still race.

**Example of the broken rule:** `ComputeAvgOrientations::computeVmfWatsonAverage()` ran workers that wrote the
per-feature output stores without a gate (PR #1645 made it serial). `ComputeFeatureFaceMisorientation` was fixed in
PR #1618. `CombineStlFiles` (issue #1876), `ConvertOrientations`, `PointSampleEdgeGeometry` and `FeatureFaceCurvature`
still launch workers that write shared stores without a gate.
PR #1618, and `FeatureFaceCurvature` in the change that fixed issue #1908 items L73 to L79. `CombineStlFiles` (issue
#1876), `ConvertOrientations` and `PointSampleEdgeGeometry` still launch workers that write shared stores without a gate.

**Why:** out-of-core stores do not support concurrent writes, and a race between two writers can lose values without
an error. Distinct tuple ranges do not make the writes safe.
Expand Down
2 changes: 2 additions & 0 deletions src/Plugins/NXImageProcessing/docs/BlackTopHatImageFilter.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale morphology (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is zero everywhere.

### Safe Border

When *Safe Border* is enabled (the default), the internal closing pads the image by the kernel radius before its dilation/erosion passes and crops back afterward, matching the legacy ITK filter and avoiding boundary artifacts near the image edge. When disabled, the closing runs directly on the image with out-of-bounds neighbors skipped (equivalent to ITK's `SafeBorder = false`); results are identical in the image interior and differ only within one kernel radius of the border.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The input array must be single-component (scalar); the output element type match

The structuring element shape (Annulus, Ball, Box, or Cross) and its per-axis radius, used by the dilation.

On a 2D image (Z = 1), the filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input, with **Preserve Intensities** on or off.

### Fully Connected

Selects the connectivity of the reconstruction: **Off** (default) uses face connectivity only; **On** uses face + edge + vertex connectivity.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale dilation (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input.

## Algorithm

### In-Core Path
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale erosion (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input.

## Algorithm

### In-Core Path
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale morphology (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input.

### Safe Border

When *Safe Border* is enabled (the default), the image is padded by the kernel radius before the dilation/erosion passes and cropped back afterward, matching the legacy ITK filter and avoiding boundary artifacts near the image edge. When disabled, the two passes run directly on the image with out-of-bounds neighbors skipped (equivalent to ITK's `SafeBorder = false`); results are identical in the image interior and differ only within one kernel radius of the border.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale morphology (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input.

### Safe Border

When *Safe Border* is enabled (the default), the image is padded by the kernel radius before the erosion/dilation passes and cropped back afterward, matching the legacy ITK filter and avoiding boundary artifacts near the image edge. When disabled, the two passes run directly on the image with out-of-bounds neighbors skipped (equivalent to ITK's `SafeBorder = false`); results are identical in the image interior and differ only within one kernel radius of the border.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale morphology (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is zero everywhere.

## Algorithm

### In-Core Path
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The input array must be single-component (scalar); the output element type match

The structuring element shape (Annulus, Ball, Box, or Cross) and its per-axis radius, used by the erosion.

On a 2D image (Z = 1), the filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is a copy of the input, with **Preserve Intensities** on or off.

### Fully Connected

Selects the connectivity of the reconstruction: **Off** (default) uses face connectivity only; **On** uses face + edge + vertex connectivity.
Expand Down
6 changes: 3 additions & 3 deletions src/Plugins/NXImageProcessing/docs/ReadImageFilter.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ IO (Input)

Reads an image file into a newly created **Image Geometry**. This filter is dimension-aware: a single-page raster file is read as a 2D image (`Z = 1`), a multi-page TIFF is read as a 3D Z-stack (one page per Z slice), and a NRRD file is read as its native 2D or 3D volume. This filter does not depend on ITK. It uses stb_image for PNG/JPEG/BMP files, libtiff for TIFF files, and an ITK-free (zlib-only) reader for NRRD files.

In a multi-page TIFF, the first page (page 0) sets the component count and the stored data type. The output array has this data type, unless **Set Image Data Type** is on: then the filter converts the values to the **Output Data Type**. Each page that the filter reads must have the same component count, stored data type, width and height as page 0. Otherwise, the filter returns an error. The filter reads only the pages inside the Z crop. When it reads a single page (as Read Image Stack does), it reads only page 0. It does not check the pages that it does not read.

The following image types are supported:

- PNG (via stb)
Expand All @@ -16,9 +18,7 @@ The following image types are supported:
- TIFF / TIF, including multi-page TIFF read as a 3D Z-stack (via libtiff)
- NRRD (`.nrrd` attached, `.nhdr` detached) (ITK-free, zlib only)

All pages of a multi-page TIFF must have the same dimensions, component count, and scalar type. The filter compares the number of bytes per pixel and the dimensions of each page it reads with page 0. It does not compare component counts or scalar types. A change in component count or scalar type can go undetected when the number of bytes per pixel stays the same. This can cause incorrect pixel values.

If the first page is 8-bit RGB and a later page is 8-bit grayscale, the filter fails with error `-2007` when it reads that later page. The number of bytes per pixel differs (3 and 1), so it fails before it copies any pixels of that page. This intentionally differs from DREAM3D 6.5.171, which could crash on mixed-page TIFF files (KI-053).
All pages of a multi-page TIFF that the filter reads must have the same dimensions, component count, and scalar type. Before it reads any pixels, the filter compares the component count and stored data type of each of these pages with page 0. A difference is error `-50579`, for example when page 0 is 8-bit RGB and a later page is 8-bit grayscale. While it reads, the filter compares the dimensions of each page with page 0. A difference is error `-2007`. This intentionally differs from DREAM3D 6.5.171, which could crash on mixed-page TIFF files (KI-053).

### NRRD Volumes

Expand Down
2 changes: 2 additions & 0 deletions src/Plugins/NXImageProcessing/docs/WhiteTopHatImageFilter.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ The *Kernel Type* parameter selects the structuring element used for the morphol

**Note on a zero radius component (e.g. `{2, 1, 0}`) with a Box kernel on a 3D image:** This filter computes the correct grayscale morphology (a radius of 0 on an axis simply means the kernel has extent 1 on that axis). The legacy ITK filter's decomposable-Box (van Herk–Gil–Werman anchor) path produces an incorrect result for a zero-radius axis on a 3D image, reaching values outside the intended neighborhood. Results therefore differ from the legacy filter *by design* for this case; a radius of 0 on the Z axis of a genuinely 2D (single-slice) image is unaffected.

**Note on a 2D image (Z = 1):** The filter ignores the kernel offsets along Z. If the kernel has only Z offsets (for example an Annulus with radius `{0, 0, 2}`), the output is zero everywhere.

### Safe Border

When *Safe Border* is enabled (the default), the internal opening pads the image by the kernel radius before its erosion/dilation passes and crops back afterward, matching the legacy ITK filter and avoiding boundary artifacts near the image edge. When disabled, the opening runs directly on the image with out-of-bounds neighbors skipped (equivalent to ITK's `SafeBorder = false`); results are identical in the image interior and differ only within one kernel radius of the border.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,22 @@ namespace fs = std::filesystem;

namespace
{
std::string DescribePageLayout(const IImageIO::PageMetadata& layout)
{
switch(layout.sampleFormat)
{
case IImageIO::SampleFormat::Unsigned:
return fmt::format("{}-component uint{}", layout.numComponents, layout.bitsPerSample);
case IImageIO::SampleFormat::Signed:
return fmt::format("{}-component int{}", layout.numComponents, layout.bitsPerSample);
case IImageIO::SampleFormat::Float:
return fmt::format("{}-component float{}", layout.numComponents, layout.bitsPerSample);
case IImageIO::SampleFormat::Unknown:
break;
}
return fmt::format("{}-component {}-bit samples of an unsupported type", layout.numComponents, layout.bitsPerSample);
}

/**
* @brief Geometry of one raster read (2D raster or multi-page TIFF Z-stack).
*
Expand Down Expand Up @@ -297,6 +313,12 @@ Result<> ReadRasterBackend(DataStructure& dataStructure, const ReadImageInputVal
return MakeErrorResult(-2001, fmt::format("Crop window (start=[{},{},{}], size=[{},{},{}]) does not fit within the source image (size=[{},{},{}])", stream.xStart, stream.yStart, stream.zStart,
stream.dstWidth, stream.dstHeight, stream.dstDepth, stream.srcWidth, stream.srcHeight, metadata.numPages));
}
// Only the decoded pages are validated. Page 0 sets the output layout, so each decoded page is compared with it.
auto layoutResult = ReadImage::ValidatePageLayouts(*imageIO, inputFilePath, stream.singlePageOnly ? usize{0} : stream.zStart, stream.dstDepth);
if(layoutResult.invalid())
{
return layoutResult;
}

const DataType destType = imageArray.getDataType();
const DataType srcType = metadata.dataType;
Expand Down Expand Up @@ -468,3 +490,36 @@ Result<> ReadImage::operator()()

return ReadRasterBackend(m_DataStructure, m_InputValues, m_MessageHandler, m_ShouldCancel);
}

// -----------------------------------------------------------------------------
Result<> ReadImage::ValidatePageLayouts(const IImageIO& imageIO, const std::filesystem::path& filePath, usize firstPage, usize pageCount)
{
// Page 0 sets the output layout. A read of page 0 alone has nothing to compare.
if(pageCount == 0 || (firstPage == 0 && pageCount == 1))
{
return {};
}
auto result = imageIO.readPageLayouts(filePath);
if(result.invalid())
{
return ConvertResult(std::move(result));
}
const auto& layouts = result.value();
if(layouts.empty())
{
return {};
}
const auto& first = layouts.front();
const usize endPage = std::min(layouts.size(), firstPage + pageCount);
for(usize page = std::max(firstPage, usize{1}); page < endPage; ++page)
{
const auto& current = layouts[page];
if(current.numComponents != first.numComponents || current.bitsPerSample != first.bitsPerSample || current.sampleFormat != first.sampleFormat)
{
return MakeErrorResult(
-50579, fmt::format("TIFF '{}': page {} is {}, page 0 is {}. Each page that is read must have the same component count and data type as page 0. Use a TIFF with matching page layouts.",
filePath.string(), page, DescribePageLayout(current), DescribePageLayout(first)));
}
}
return {};
}
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@

namespace nx::core
{
class IImageIO;

/**
* @struct ReadImageInputValues
Expand Down Expand Up @@ -77,6 +78,20 @@ class NXIMAGEPROCESSING_EXPORT ReadImage
*/
Result<> operator()();

/**
* @brief Checks that each page the read decodes has the component count and sample type of page 0.
*
* Page 0 sets the output array layout, so it is the reference even when it is outside the read.
* Pages outside [firstPage, firstPage + pageCount) are not checked. A read of page 0 alone returns
* success. Page dimensions are not compared here; they are checked when each page is decoded.
* @param imageIO Image backend that reads the page layouts.
* @param filePath Image file to check.
* @param firstPage First decoded page (the Z crop start, or 0).
* @param pageCount Number of decoded pages (1 for a single-page read).
* @return Success, the backend's metadata error, or error -50579 for the first decoded page that differs.
*/
static Result<> ValidatePageLayouts(const IImageIO& imageIO, const std::filesystem::path& filePath, usize firstPage, usize pageCount);

private:
DataStructure& m_DataStructure;
const ReadImageInputValues& m_InputValues;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,8 @@ IFilter::PreflightResult ReadImageFilter::preflightImpl(const DataStructure& dat
bool cropImage = croppingOptions.type != CropGeometryParameter::CropValues::TypeEnum::NoCropping;
const bool zCropActive = cropImage && croppingOptions.cropZ && dims[2] > 1;
bool cropAnyDim = cropImage && (croppingOptions.cropX || croppingOptions.cropY || zCropActive);
// First source page that the read decodes. A Z crop moves it; otherwise the read starts at page 0.
usize firstPage = 0;
if(cropAnyDim)
{
DataStructure tmpDs;
Expand Down Expand Up @@ -371,6 +373,17 @@ IFilter::PreflightResult ReadImageFilter::preflightImpl(const DataStructure& dat
dims = croppedGeom.getDimensions().toContainer<std::vector<usize>>();
spacing = croppedGeom.getSpacing().toContainer<std::vector<float32>>();
origin = croppedGeom.getOrigin().toContainer<std::vector<float32>>();
if(zCropActive)
{
firstPage = static_cast<usize>(cropBounds.zMin);
}
}

// Only the decoded pages are validated. Page 0 sets the output layout, so each decoded page is compared with it.
auto layoutResult = ReadImage::ValidatePageLayouts(*imageIO, fileName, firstPage, dims[2]);
if(layoutResult.invalid())
{
return {ConvertResultTo<OutputActions>(std::move(layoutResult), {})};
}

if(originSpacingProcessing == OriginSpacingProcessing::Postprocessed)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -163,3 +163,19 @@ TEST_CASE("NXImageProcessing::ClosingByReconstructionImageFilter: Ordinary Kerne
{
morph_test::RequireOrdinaryKernelRadius<ClosingByReconstructionImageFilter>({5, 5, 5});
}

// -----------------------------------------------------------------------------
// 2D image (Z = 1) with an Annulus that has only Z offsets: the kernel is empty in the plane, so the filter copies
// the input with Preserve Intensities on or off (#1908 L73).
// -----------------------------------------------------------------------------
TEST_CASE("NXImageProcessing::ClosingByReconstructionImageFilter: 2D out-of-plane Annulus passthrough", "[NXImageProcessing][ClosingByReconstructionImageFilter]")
{
const auto scenario = GENERATE(from_range(UnitTest::SelectAlgorithmTestScenariosForInMemoryStores()));
CAPTURE(scenario);
UnitTest::AlgorithmTestScope scope(scenario);
const uint32 radiusZ = GENERATE(1, 2);
const bool preserveIntensities = GENERATE(false, true);
const bool fullyConnected = GENERATE(false, true);
CAPTURE(radiusZ, preserveIntensities, fullyConnected);
rt::RequireZOnlyAnnulus2DPassthrough<ClosingByReconstructionImageFilter>(scope, radiusZ, preserveIntensities, fullyConnected);
}
Loading