The library infrastructure » Boundary module

#include "diplib/boundary.h"

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.

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.

To impose a boundary condition that is a constant other than 0, min or max, subtract the desired value from the image, apply the operation with the boundary condition "add zeros", then add that value back to the image. This might require converting the image to a signed type for the initial subtraction to do the right thing. For example, to use a value of 100 as the constant boundary condition:

int bc = 100;
dip::Image img = dip::ImageRead("examples/cameraman.tif");
dip::Image rotated = dip::Rotation2D(img - bc, dip::pi/4, "", "add zeros") + bc;
rotated.Convert(dip::DT_UINT8);

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.

dip::BoundaryCondition dip::StringToBoundaryCondition( dip::String const& bc)

Convert a string to a boundary condition.

dip::BoundaryConditionArray dip::StringArrayToBoundaryConditionArray( dip::StringArray const& bc)

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.

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:

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.