Namespace for collection of image 2D transformation functions from the Foundation package. More...

Classes
class	NonLinearTransformation
	Object implementing the non linear polynomially approximated transform implemented in the CVB Foundation package. More...

class	PerspectiveTransformation
	Perspective transformation coefficients. More...

Typedefs
typedef std::shared_ptr< NonLinearTransformation >	NonLinearTransformationPtr
	Convenience shared pointer for NonLinearTransformation.

Enumerations
enum class	Interpolation { NearestNeighbor = CExports::IP_NearestNeighbour , Linear = CExports::IP_Linear , Cubic = CExports::IP_Cubic , Lanczos = CExports::IP_Lanczos , Supersample = CExports::IP_Supersample }
	Interpolation modes available inside the Foundation package. More...

enum class	Axis { NoAxis = 0 , X = 1 , Y = 2 , Both = 3 }
	Axis enumeration. More...

enum class	CalibrationPatternContrast { BlackOnWhite = CExports::CPC_Black_On_White , WhiteOnBlack = CExports::CPC_White_On_Black }
	Definition of the contrast of the pattern used for automatic calibration. More...

enum class	CalibrationPatternStyle { UniformDots = CExports::CPS_Uniform_Dots , AsymmetricDots = CExports::CPS_Asymmetric_Dots }
	Definition of the calibration pattern style used for automatic calibration. More...

enum class	CalibrationPatternFormat { A4 , Letter }
	Definition of the paper format used for printing calibration patterns. More...

enum class	CalibrationPatternOrientation { Portrait , Landscape }
	Format orientation for the CalibrationPatternFormat. More...

Functions
std::unique_ptr< Image >	MatrixTransform (const Image &image, const Matrix2D &matrix, Interpolation interpolation=Interpolation::Linear)
	Use a matrix to transform an image.

std::unique_ptr< Image >	Mirror (const Image &image, Axis axis)
	Mirror the input image on the x and/or y axis.

std::unique_ptr< Image >	Perspective (const Image &image, const PerspectiveTransformation &coeffs, Size2D< int > targetSize, Interpolation interpolation=Interpolation::Linear)
	Apply the perspective transformation coefficients to the image.

std::unique_ptr< Image >	Resize (const Image &image, Size2D< int > targetSize, Interpolation interpolation=Interpolation::Linear)
	Resize the input image.

std::unique_ptr< Image >	Rotate (const Image &image, Angle angle, Interpolation interpolation=Interpolation::Linear)
	Rotate the input image by the given angle.

std::unique_ptr< Image >	Shear (const Image &image, double shearX, double shearY, Interpolation interpolation=Interpolation::Linear)
	Shear the input image.

std::unique_ptr< Image >	CreateCalibrationPattern (CalibrationPatternStyle style, CalibrationPatternContrast contrast, int width, int height, int numColumns, int numRows)
	Create a user-definable calibration pattern.

std::unique_ptr< Image >	CreatePrintableCalibrationPattern (CalibrationPatternStyle style, CalibrationPatternContrast contrast, CalibrationPatternFormat paperSize, CalibrationPatternOrientation orientation, int numColumns, int numRows, double horizontalBorder, double verticalBorder, int dpi)
	Create a user-definable calibration pattern suitable for printing on a sheet of paper.

void	ExtractCalibrationLists (const ImagePlane &plane, CalibrationPatternStyle style, CalibrationPatternContrast contrast, int gridSpacing, int minContrast, double maxRatio, Area2D aoi, std::vector< Point2D< double > > &originalPixels, std::vector< Point2D< double > > &transformedPixels)
	Automatically extracts the pixel lists required for creating a NonLinearTransformation object.

void	ExtractCalibrationLists (const ImagePlane &plane, CalibrationPatternStyle style, CalibrationPatternContrast contrast, int gridSpacing, int minContrast, double maxRatio, std::vector< Point2D< double > > &originalPixels, std::vector< Point2D< double > > &transformedPixels)
	Automatically extracts the pixel lists required for creating a NonLinearTransformation object.

Detailed Description

Namespace for collection of image 2D transformation functions from the Foundation package.

Remarks: CMake users: Link to imported target CVB::CvbFoundationTransform2D

Enumeration Type Documentation

◆ Axis

enum class Axis

strong

Axis enumeration.

Enumerator
NoAxis	No axis.
X	X-axis
Y	Y-axis
Both	Both axes.

◆ CalibrationPatternContrast

enum class CalibrationPatternContrast

strong

Definition of the contrast of the pattern used for automatic calibration.

Enumerator
BlackOnWhite	Black objects on white background.
WhiteOnBlack	White objects on black background.

◆ CalibrationPatternFormat

enum class CalibrationPatternFormat

strong

Definition of the paper format used for printing calibration patterns.

Enumerator
A4	A4 paper size (210 x 297 mm).
Letter	Letter sized paper (8.5 x 11 inches).

◆ CalibrationPatternOrientation

enum class CalibrationPatternOrientation

strong

Format orientation for the CalibrationPatternFormat.

Enumerator
Portrait	Portrait has the long side vertically.
Landscape	Landscape has the long side horizontally.

◆ CalibrationPatternStyle

enum class CalibrationPatternStyle

strong

Definition of the calibration pattern style used for automatic calibration.

Enumerator
UniformDots	Symmetric grid of uniformly sized, circle-shaped dots. With this pattern it is not possible to determine origin and/or orientation of the calibration pattern!
AsymmetricDots	Symmetric grid of dots. Four dots are bigger than the others and define the pattern's origin and orientation.

◆ Interpolation

enum class Interpolation

strong

Interpolation modes available inside the Foundation package.

Enumerator
NearestNeighbor	Simple nearest neighbor interpolation. May result in a less pleasant output image, but yields the fastest results.
Linear	Linear interpolation in x and y. Good trade off between visual quality and speed. Default interpolation mode in CVB.
Cubic	Cubic interpolation in x and y. Slower than linear interpolation, but better in terms of results.
Lanczos	Interpolation using a 3-lobed Lanczos window function.
Supersample	Interpolation through super sampling and averaging of the target position from sub pixel positions.

Function Documentation

◆ CreateCalibrationPattern()

std::unique_ptr< Image > CreateCalibrationPattern	(	CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		int	width,
		int	height,
		int	numColumns,
		int	numRows )

inline

Create a user-definable calibration pattern.

Parameters

[in]	style	Dot style to use (see CalibrationPatternStyle).
[in]	contrast	Selects whether to use white on black or black on white dots (see CalibrationPatternContrast).
[in]	width	Width of the output image in pixels.
[in]	height	Height of the output image in pixels.
[in]	numColumns	Number of dot columns in the image.
[in]	numRows	Number of dot rows in the image.

Returns: Calibration pattern image.

Exceptions

Any	exception derived from std::exception including CvbException.

The calibration pattern will consist of a regular spaced matrix of dots, the size of which will be determined by the input parameters. The distance between the dots in x- and y-direction will be 2.5 times the diameter of the dots.
If an asymmetric pattern was selected, the bigger dots will have 2.5 times the area of the smaller dots (meaning that their radius is sqrt(2.5) times the radius of the small dots).

◆ CreatePrintableCalibrationPattern()

std::unique_ptr< Image > CreatePrintableCalibrationPattern	(	CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		CalibrationPatternFormat	paperSize,
		CalibrationPatternOrientation	orientation,
		int	numColumns,
		int	numRows,
		double	horizontalBorder,
		double	verticalBorder,
		int	dpi )

inline

Create a user-definable calibration pattern suitable for printing on a sheet of paper.

Parameters

[in]	style	Dot style to use (see CalibrationPatternStyle).
[in]	contrast	Selects whether to use white on black or black on white dots (see CalibrationPatternContrast).
[in]	paperSize	Size of the paper on which to print the calibration pattern later on (see CalibrationPatternFormat).
[in]	orientation	Choose orientation; only relevant for CalibrationPatternStyle::AsymmetricDots.
[in]	numColumns	Number of dot columns in the image.
[in]	numRows	Number of dot rows in the image.
[in]	horizontalBorder	Horizontal borders to be applied (in inches).
[in]	verticalBorder	Vertical borders to be applied (in inches).
[in]	dpi	Dot density to use (in dots per inch).

Returns: Calibration pattern image.

Exceptions

Any	exception derived from std::exception including CvbException.

The calibration pattern will consist of a regularly spaced matrix of dots, the size of which will be determined by the input parameters. The size of the pattern image will be suitable for printing it on an piece of paper defined by the paperSize parameter. The calibration pattern will consist of a regular rectangular grid of dots. The distance between the dots in x- and y-direction will be 2.5 times the diameter of the dots. If an asymmetric pattern was selected, the bigger dots will have 2.5 times the area of the smaller dots (meaning that their radius is sqrt(2.5) times the radius of the small dots).
The horizontal and vertical border values should match the setting that is going to be used for printing the resulting image. Must not be negative. The meaning of horizontal/vertical refers to the paper size definition and is independent of orientation setting.
It usually makes sense to set the dpi parameter to the printer's physical dot density or half or quarter of that. Minimum value is 150.

◆ ExtractCalibrationLists() [1/2]

void ExtractCalibrationLists	(	const ImagePlane &	plane,
		CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		int	gridSpacing,
		int	minContrast,
		double	maxRatio,
		Area2D	aoi,
		std::vector< Point2D< double > > &	originalPixels,
		std::vector< Point2D< double > > &	transformedPixels )

inline

Automatically extracts the pixel lists required for creating a NonLinearTransformation object.

Parameters

[in]	plane	Image plane to work on.
[in]	style	Calibration pattern style visible in the image (see CalibrationPatternStyle).
[in]	contrast	Selects whether the image shows CalibrationPatternContrast::BlackOnWhite or CalibrationPatternContrast::WhiteOnBlack dots.
[in]	gridSpacing	Spacing of the calibration dot grid in the target image. Defines the distance of the points that will end up in the transformed pixels.
[in]	minContrast	Minimum gray value contrast between the object and the background of the calibration target pattern.
[in]	maxRatio	Maximum ratio between the biggest and the smallest calibration dot.
[in]	aoi	Area of interest in which to look for the calibration pattern's dots.
[out]	originalPixels	Point list to contain the locations of the calibration dots in the input image in pixel coordinates (output).
[out]	transformedPixels	Pixel list to contain the appropriate locations of the calibration dots in the target image of the calibration (output).

Exceptions

Any	exception derived from std::exception including CvbException.

Note that a more convenient alternative is to call the method NonLinearTransformation::FromCalibrationPattern. It will do the list extraction and the generation of the transformation object in a single function call. The image plane given to this method needs to contain a calibration pattern as generated by the function CreateCalibrationPattern: A regularly spaced matrix of dots, the distance between the dots in x- and y-direction should be 2.5 times the diameter of the dots, if an asymmetric pattern was used, the bigger dots should have 2.5 times the area of the smaller dots (meaning that their radius is sqrt(2.5) times the radius of the small dots). Note that, although the area of interest is given as a Area2D here (and in the processing of the Area2D the image's coordinate system will be respected), the actual output of this method uses CoordinateSystemType::PixelCoordinates! This seemingly inconsistent mix in this case is in fact useful, because a Area2D will better capture the actual location of a calibration pattern, especially if the image has been rotated, than a Rectangle style area of interest. But the calibration functions usually assume that the pixel lists are given in pixel coordinates. To avoid misunderstandings and complications in the interpretation of the image content, it is recommended to use a default coordinate system on the input image. The minimum contrast (minContrast) value to be set depends on the quality of the image taken from the pattern, but in a typical situation this contrast should not drop below 64 gray values, otherwise it might become difficult to extract the calibration points. The maximum ratio (maxRatio) value will be used to identify outliers when looking for calibration dots. It should be set high enough to allow for the area variations to be expected due to perspective distortions and small enough to eliminate the candidates that are either too big or too small to be valid calibration pattern dots. Typically, values of about 3.0 to 5.0 are big enough - even if there is notable perspective distortion visible in the images. If an asymmetric calibration pattern has been selected, the ratio used for calculation will be adapted accordingly.

◆ ExtractCalibrationLists() [2/2]

void ExtractCalibrationLists	(	const ImagePlane &	plane,
		CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		int	gridSpacing,
		int	minContrast,
		double	maxRatio,
		std::vector< Point2D< double > > &	originalPixels,
		std::vector< Point2D< double > > &	transformedPixels )

inline

Automatically extracts the pixel lists required for creating a NonLinearTransformation object.

Parameters

[in]	plane	Image plane to work on.
[in]	style	Calibration pattern style visible in the image (see CalibrationPatternStyle).
[in]	contrast	Selects whether the image shows CalibrationPatternContrast::BlackOnWhite or CalibrationPatternContrast::WhiteOnBlack dots.
[in]	gridSpacing	Spacing of the calibration dot grid in the target image. Defines the distance of the points that will end up in the transformed pixels.
[in]	minContrast	Minimum gray value contrast between the object and the background of the calibration target pattern.
[in]	maxRatio	Maximum ratio between the biggest and the smallest calibration dot.
[out]	originalPixels	Point list to contain the locations of the calibration dots in the input image in pixel coordinates (output).
[out]	transformedPixels	Pixel list to contain the appropriate locations of the calibration dots in the target image of the calibration (output).

Exceptions

Any	exception derived from std::exception including CvbException.

Note that a more convenient alternative is to call the method NonLinearTransformation::FromCalibrationPattern. It will do the list extraction and the generation of the transformation object in a single function call. The image plane given to this method needs to contain a calibration pattern as generated by the function CreateCalibrationPattern: A regularly spaced matrix of dots, the distance between the dots in x- and y-direction should be 2.5 times the diameter of the dots, if an asymmetric pattern was used, the bigger dots should have 2.5 times the area of the smaller dots (meaning that their radius is sqrt(2.5) times the radius of the small dots). To avoid misunderstandings and complications in the interpretation of the image content, it is recommended to use a default coordinate system on the input image. The minimum contrast (minContrast) value to be set depends on the quality of the image taken from the pattern, but in a typical situation this contrast should not drop below 64 gray values, otherwise it might become difficult to extract the calibration points. The maximum ratio (maxRatio) value will be used to identify outliers when looking for calibration dots. It should be set high enough to allow for the area variations to be expected due to perspective distortions and small enough to eliminate the candidates that are either too big or too small to be valid calibration pattern dots. Typically, values of about 3.0 to 5.0 are big enough - even if there is notable perspective distortion visible in the images. If an asymmetric calibration pattern has been selected, the ratio used for calculation will be adapted accordingly.

◆ MatrixTransform()

std::unique_ptr< Image > MatrixTransform	(	const Image &	image,
		const Matrix2D &	matrix,
		Interpolation	interpolation = Interpolation::Linear )

inline

Use a matrix to transform an image.

Parameters

[in]	image	Image to transform.
[in]	matrix	Matrix with which the image is to be transformed.
[in]	interpolation	Interpolation to use (Linear by default). Supported values are NearestNeighbor, Linear and Cubic.

Returns: The transformed image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Mirror()

std::unique_ptr< Image > Mirror	(	const Image &	image,
		Axis	axis )

inline

Mirror the input image on the x and/or y axis.

Parameters

[in]	image	Image to mirror.
[in]	axis	Axis(es) around which it is to be flipped.

Returns: The mirrored image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Perspective()

std::unique_ptr< Image > Perspective	(	const Image &	image,
		const PerspectiveTransformation &	coeffs,
		Size2D< int >	targetSize,
		Interpolation	interpolation = Interpolation::Linear )

inline

Apply the perspective transformation coefficients to the image.

Parameters

[in]	image	Image to transform.
[in]	coeffs	Perspective transformaton coefficients.
[in]	targetSize	Size of the destination image.
[in]	interpolation	Interpolation to use (Linear by default). Supported values are NearestNeighbor, Linear and Cubic.

Returns: The transformed image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Resize()

std::unique_ptr< Image > Resize	(	const Image &	image,
		Size2D< int >	targetSize,
		Interpolation	interpolation = Interpolation::Linear )

inline

Resize the input image.

Parameters

[in]	image	Image to resize.
[in]	targetSize	Size to go with it.
[in]	interpolation	Interpolation to use (Linear by default). Supported values are NearestNeighbor, Linear and Cubic.

Returns: The resized image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Rotate()

std::unique_ptr< Image > Rotate	(	const Image &	image,
		Angle	angle,
		Interpolation	interpolation = Interpolation::Linear )

inline

Rotate the input image by the given angle.

Parameters

[in]	image	Image to rotate.
[in]	angle	Angle by which it is to be rotated.
[in]	interpolation	Interpolation to use (Linear by default). Supported values are NearestNeighbor, Linear and Cubic.

Returns: The rotated image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Shear()

std::unique_ptr< Image > Shear	(	const Image &	image,
		double	shearX,
		double	shearY,
		Interpolation	interpolation = Interpolation::Linear )

inline

Shear the input image.

Parameters

[in]	image	Image to shear.
[in]	shearX	Shear factor in x-direction.
[in]	shearY	Shear factor in y-direction.
[in]	interpolation	Interpolation to use (Linear by default). Supported values are NearestNeighbor, Linear and Cubic.

Returns: The sheared image.

Exceptions

Any	exception derived from std::exception including CvbException.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ Axis

◆ CalibrationPatternContrast

◆ CalibrationPatternFormat

◆ CalibrationPatternOrientation

◆ CalibrationPatternStyle

◆ Interpolation

Function Documentation

◆ CreateCalibrationPattern()

◆ CreatePrintableCalibrationPattern()

◆ ExtractCalibrationLists() [1/2]

◆ ExtractCalibrationLists() [2/2]

◆ MatrixTransform()

◆ Mirror()

◆ Perspective()

◆ Resize()

◆ Rotate()

◆ Shear()