module #include "diplib/boundary.h"
Boundary Handling image boundary extension for filtering
Aliases

using dip::
Option:: = dip::detail::OptionsExtendImageFlags  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:: : uint8{ Masked, ExpandTensor }ExtendImage  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
byborderSizes
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
byborderSizes
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
tosizes
. 
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
tosizes
. 
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 boundaryextended 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 lowlevel 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 boundaryextended 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 lowlevel 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 boundaryextended 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 lowlevel 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.