The library infrastructure » Boundary module
#include "diplib/boundary.h"

Handling image boundary extension for filtering

Contents

Aliases

using dip::Option::ExtendImageFlags = dip::detail::Options
Combines any number of dip::Option::ExtendImage constants together.
using dip::BoundaryConditionArray = dip::DimensionArray
An array to hold boundary conditions.

Enums

enum class dip::BoundaryCondition: uint8{ SYMMETRIC_MIRROR, DEFAULT, ASYMMETRIC_MIRROR, PERIODIC, ASYMMETRIC_PERIODIC, ADD_ZEROS, ADD_MAX_VALUE, ADD_MIN_VALUE, ZERO_ORDER_EXTRAPOLATE, FIRST_ORDER_EXTRAPOLATE, SECOND_ORDER_EXTRAPOLATE, THIRD_ORDER_EXTRAPOLATE, ALREADY_EXPANDED }
Enumerates various ways of extending image data beyond its boundary.
enum class dip::Option::ExtendImage: uint8{ Masked, ExpandTensor }
Defines options to the dip::ExtendImage function.

Functions

auto dip::StringToBoundaryCondition(dip::String const& bc) -> dip::BoundaryCondition
Convert a string to a boundary condition.
auto dip::StringArrayToBoundaryConditionArray(dip::StringArray const& bc) -> dip::BoundaryConditionArray
Convert an array of strings to an array of boundary conditions.
void dip::BoundaryArrayUseParameter(dip::BoundaryConditionArray& bc, dip::uint nDims)
Check the length of a BoundaryConditionArray, and extend it if necessary and possible.
auto dip::ReadPixelWithBoundaryCondition(dip::Image const& img, dip::IntegerArray coords, dip::BoundaryConditionArray const& bc) -> dip::Image::Pixel
Returns a pixel with a copy of the sample values at coords.
void dip::ExtendImage(dip::Image const& in, dip::Image& out, dip::UnsignedArray borderSizes, dip::BoundaryConditionArray boundaryConditions = {}, dip::Option::ExtendImageFlags options = {})
Extends the image in by borderSizes along each dimension.
void dip::ExtendImage(dip::Image const& in, dip::Image& out, dip::UnsignedArray borderSizes, dip::StringArray const& boundaryConditions, dip::StringSet const& options = {})
Extends the image in by borderSizes along each dimension.
void dip::ExtendImageToSize(dip::Image const& in, dip::Image& out, dip::UnsignedArray const& sizes, dip::Option::CropLocation cropLocation = Option::CropLocation::CENTER, dip::BoundaryConditionArray boundaryConditions = {}, dip::Option::ExtendImageFlags options = {})
Extends the image in to sizes.
void dip::ExtendImageToSize(dip::Image const& in, dip::Image& out, dip::UnsignedArray const& sizes, dip::String const& cropLocation, dip::StringArray const& boundaryConditions = {}, dip::StringSet const& options = {})
Extends the image in to sizes.
void dip::ExtendRegion(dip::Image& image, dip::RangeArray ranges, dip::BoundaryConditionArray boundaryConditions = {})
Fills the pixels outside a region in the image using a boundary condition.
void dip::ExtendRegion(dip::Image& image, dip::RangeArray const& ranges, dip::StringArray const& boundaryConditions)
Fills the pixels outside a region in the image using a boundary condition.
void dip::ExtendRegion(dip::Image& image, dip::UnsignedArray origin, dip::UnsignedArray sizes, dip::StringArray const& boundaryConditions)
Fills the pixels outside a region in the image using a boundary condition.

Enum documentation

enum class dip::BoundaryCondition: uint8

Enumerates various ways of extending image data beyond its boundary.

This enumerator is used by the framework functions and some internal functions. Externally, the boundary condition is represented by strings.

Most functions will take a string instead of a dip::BoundaryCondition constant. The following table links boundary condition constants and their string representations.

BoundaryCondition constant String Definition
SYMMETRIC_MIRROR “mirror” The data are mirrored, with the value at -1 equal to the value at 0, at -2 equal to at 1, etc.
ASYMMETRIC_MIRROR “asym mirror” The data are mirrored and inverted.
PERIODIC “periodic” The data are repeated periodically, with the value at -1 equal to the value of the last pixel.
ASYMMETRIC_PERIODIC “asym periodic” The data are repeated periodically and inverted.
ADD_ZEROS “add zeros” The boundary is filled with zeros.
ADD_MAX_VALUE “add max” The boundary is filled with the max value for the data type.
ADD_MIN_VALUE “add min” The boundary is filled with the min value for the data type.
ZERO_ORDER_EXTRAPOLATE “zero order” The value at the border is repeated indefinitely.
FIRST_ORDER_EXTRAPOLATE “first order” A linear function is defined based on the value closest to the border, the function reaches zero at the end of the extended boundary.
SECOND_ORDER_EXTRAPOLATE “second order” A quadratic function is defined based on the two values closest to the border, the function reaches zero at the end of the extended boundary.
THIRD_ORDER_EXTRAPOLATE “third order” A cubic function is defined based on the two values closest to the border, the function reaches zero with a zero derivative at the end of the extended boundary.
DEFAULT “default” or “” The default value, currently equal to SYMMETRIC_MIRROR.
ALREADY_EXPANDED “already expanded” The dangerous option. The image is an ROI of a larger image, the filter should read existing data outside of the image. The user must be sure that there exists sufficient data to satisfy the filter, for this she must understand how far the filter will read data outside of the image bounds. Not supported by all functions, and cannot always be combined with other options.

enum class dip::Option::ExtendImage: uint8

Defines options to the dip::ExtendImage function.

Implicitly casts to dip::Option::ExtendImageFlags. Combine constants together with the + operator.

Enumerators
Masked = 0 The output image is a window on the boundary-extended image of the same size as the input.
ExpandTensor = 1 The output image has normal tensor storage.

Function documentation

void dip::BoundaryArrayUseParameter(dip::BoundaryConditionArray& bc, dip::uint nDims)

Check the length of a BoundaryConditionArray, and extend it if necessary and possible.

The output will have nDims elements. If the input has a single value, it will be used for all dimensions. If the input is an empty array, the default boundary condition will be used for all dimensions. If the array has nDims elements, it is copied unchanged. For any other length, an exception is thrown.

dip::Image::Pixel dip::ReadPixelWithBoundaryCondition(dip::Image const& img, dip::IntegerArray coords, dip::BoundaryConditionArray const& bc)

Returns a pixel with a copy of the sample values at coords.

If coords falls outside the image, then the boundary condition bc is used to determine what values to write into the output pixel.

First, second and third order interpolations are not implemented, because their functionality is impossible to reproduce in this simple function. Use dip::ExtendImage to get the functionality of these boundary conditions.

void dip::ExtendImage(dip::Image const& in, dip::Image& out, dip::UnsignedArray borderSizes, dip::BoundaryConditionArray boundaryConditions = {}, dip::Option::ExtendImageFlags options = {})

Extends the image in by borderSizes along each dimension.

This function is identical to the dip::ExtendImage below, except it uses boundary condition constants and option constants instead of strings. This version is meant to be used by low-level library functions.

void dip::ExtendImage(dip::Image const& in, dip::Image& out, dip::UnsignedArray borderSizes, dip::StringArray const& boundaryConditions, dip::StringSet const& options = {})

Extends the image in by borderSizes along each dimension.

The output image has size in.Size( ii ) + 2 * borderSizes[ ii ] along dimension ii.

The new regions are filled using the boundary condition bc. If boundaryConditions is an empty array, the default boundary condition is used along all dimensions. If boundaryConditions has a single element, it is used for all dimensions. Similarly, if borderSizes has a single element, it is used for all dimensions.

If options contains "masked", the output image is a window on the boundary-extended image, of the same size as in. That is, out will be identical to in except that it is possible to access pixels outside of its domain.

If options contains "expand tensor", the output image will have normal tensor storage (dip::Tensor::HasNormalOrder is true). This affects only those input images that have a transposed, symmetric or triangular matrix as tensor shape.

void dip::ExtendImageToSize(dip::Image const& in, dip::Image& out, dip::UnsignedArray const& sizes, dip::Option::CropLocation cropLocation = Option::CropLocation::CENTER, dip::BoundaryConditionArray boundaryConditions = {}, dip::Option::ExtendImageFlags options = {})

Extends the image in to sizes.

This function is identical to the dip::ExtendImageToSize below, except it uses boundary condition constants and option constants instead of strings. This version is meant to be used by low-level library functions.

void dip::ExtendImageToSize(dip::Image const& in, dip::Image& out, dip::UnsignedArray const& sizes, dip::String const& cropLocation, dip::StringArray const& boundaryConditions = {}, dip::StringSet const& options = {})

Extends the image in to sizes.

The output image has size sizes( ii ) along dimension ii. sizes must have in.Dimensionality() elements.

The string cropLocation determines where in the output image in is placed. Its values translate to one of the dip::Option::CropLocation values as follows:

CropLocation constant String
dip::Option::CropLocation::CENTER "center"
dip::Option::CropLocation::MIRROR_CENTER "mirror center"
dip::Option::CropLocation::TOP_LEFT "top left"
dip::Option::CropLocation::BOTTOM_RIGHT "bottom right"

The new regions are filled using the boundary condition bc. If boundaryConditions is an empty array, the default boundary condition is used along all dimensions. If boundaryConditions has a single element, it is used for all dimensions. Similarly, if borderSizes has a single element, it is used for all dimensions.

If options contains "masked", the output image is a window on the boundary-extended image, of the same size as in. That is, out will be identical to in except that it is possible to access pixels outside of its domain.

If options contains "expand tensor", the output image will have normal tensor storage (dip::Tensor::HasNormalOrder is true). This affects only those input images that have a transposed, symmetric or triangular matrix as tensor shape.

This function is similar to dip::Image::Pad, which fills the new regions with a constant value.

void dip::ExtendRegion(dip::Image& image, dip::RangeArray ranges, dip::BoundaryConditionArray boundaryConditions = {})

Fills the pixels outside a region in the image using a boundary condition.

This function is identical to the dip::ExtendRegion below, except it uses boundary condition constants instead of strings. This version is meant to be used by low-level library functions.

void dip::ExtendRegion(dip::Image& image, dip::RangeArray const& ranges, dip::StringArray const& boundaryConditions)

Fills the pixels outside a region in the image using a boundary condition.

The region that is preserved is specified through ranges. The step sizes are ignored, only the start and stop values of ranges are used.

The pixels outside of the region are filled using the boundary condition boundaryConditions, using only those values inside the region. If boundaryConditions is an empty array, the default boundary condition is used along all dimensions. If boundaryConditions has a single element, it is used for all dimensions. ranges is similarly expanded if it has a single element.

void dip::ExtendRegion(dip::Image& image, dip::UnsignedArray origin, dip::UnsignedArray sizes, dip::StringArray const& boundaryConditions)

Fills the pixels outside a region in the image using a boundary condition.

The region that is preserved is specified through origin and sizes.

The pixels outside of the region are filled using the boundary condition boundaryConditions, using only those values inside the region. If boundaryConditions is an empty array, the default boundary condition is used along all dimensions. If boundaryConditions has a single element, it is used for all dimensions. origin and sizes are similarly expanded if they have a single element.