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

#include <cvb/foundation/transform_2d.hpp>

Public Member Functions
	NonLinearTransformation (const String &fileName)
	Load a saved transformation from a file.

	NonLinearTransformation (NonLinearTransformation &&) noexcept=default
	Move constructor.

NonLinearTransformation &	operator= (NonLinearTransformation &&) noexcept=default
	Move assignment operator.

void *	Handle () const noexcept
	Classic API NLTRANSFORMATION handle.

int	Order () const noexcept
	Gets the transformation order.

std::vector< double >	CoefficientsX () const
	Return an array of the coefficients used for the transformation of x coordinates.

std::vector< double >	CoefficientsY () const
	Return an array of the coefficients used for the transformation of y coordinates.

std::vector< double >	CoefficientsXInverse () const
	Return an array of the coefficients used for the inverse transformation of x coordinates.

std::vector< double >	CoefficientsYInverse () const
	Return an array of the coefficients used for the inverse transformation of x coordinates.

void	Save (const String &fileName) const
	Write the transformation to a file.

std::unique_ptr< Image >	Transform (const Image &image, Size2D< int > targetSize, Point2D< int > targetOffset)
	Transform an image with this nonlinear transformation.

Point2D< double >	Transform (Point2D< double > point)
	Transform a point with this nonlinear transformation.

Rect< double >	Transform (Rect< double > rect)
	Transform a rect with this nonlinear transformation.

template<class RANGE>
TypedRange< std::vector< Point2D< double > >, Point2D< double >, RANGE >::type	Transform (const RANGE &points)
	Transform a sequence of points with this nonlinear transformation.

std::unique_ptr< Image >	InverseTransform (const Image &image, Size2D< int > targetSize, Point2D< int > targetOffset)
	Back transform an image with this nonlinear transformation.

Point2D< double >	InverseTransform (Point2D< double > point)
	Back transform a point with this nonlinear transformation.

template<class RANGE>
TypedRange< std::vector< Point2D< double > >, Point2D< double >, RANGE >::type	InverseTransform (const RANGE &points)
	Back transform a sequence of points with this nonlinear transformation.

Static Public Member Functions
static std::unique_ptr< NonLinearTransformation >	Load (const String &fileName)
	Load a saved transformation from a file.

static std::unique_ptr< NonLinearTransformation >	FromHandle (HandleGuard< NonLinearTransformation > &&guard)
	Creates transformation from a classic API handle.

template<class RANGE>
static TypedRange< std::unique_ptr< NonLinearTransformation >, Point2D< double >, RANGE >::type	FromPositionLists (const RANGE &originalPixels, const RANGE &transformedPixels, int order, CreationProgress progressCallback=CreationProgress())
	Create a non linear transformation that - approximately - matches the set of originalPixels to the set of transformedPixels.

static std::unique_ptr< NonLinearTransformation >	FromCalibrationPattern (const ImagePlane &plane, CalibrationPatternStyle style, CalibrationPatternContrast contrast, int gridSpacing, int minContrast, double maxRatio, int order, Area2D aoi, CreationProgress progressCallback=CreationProgress())
	Create a new transformation object by automatically extracting the pixel lists required for creating a NonLinearTransformation object.

static std::unique_ptr< NonLinearTransformation >	FromCalibrationPattern (const ImagePlane &plane, CalibrationPatternStyle style, CalibrationPatternContrast contrast, int gridSpacing, int minContrast, double maxRatio, int order, CreationProgress progressCallback=CreationProgress())
	Create a new transformation object by automatically extracting the pixel lists required for creating a NonLinearTransformation object.

Detailed Description

Object implementing the non linear polynomially approximated transform implemented in the CVB Foundation package.

Constructor & Destructor Documentation

◆ NonLinearTransformation()

NonLinearTransformation ( const String & fileName )

inline

Load a saved transformation from a file.

Parameters

[in] fileName Name of the file to load.

Exceptions

Any	exception derived from std::exception including CvbException.

Member Function Documentation

◆ CoefficientsX()

std::vector< double > CoefficientsX ( ) const

inline

Return an array of the coefficients used for the transformation of x coordinates.

Returns: The coefficients.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ CoefficientsXInverse()

std::vector< double > CoefficientsXInverse ( ) const

inline

Return an array of the coefficients used for the inverse transformation of x coordinates.

Returns: The coefficients.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ CoefficientsY()

std::vector< double > CoefficientsY ( ) const

inline

Return an array of the coefficients used for the transformation of y coordinates.

Returns: The coefficients.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ CoefficientsYInverse()

std::vector< double > CoefficientsYInverse ( ) const

inline

Return an array of the coefficients used for the inverse transformation of x coordinates.

Returns: The coefficients.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ FromCalibrationPattern() [1/2]

static std::unique_ptr< NonLinearTransformation > FromCalibrationPattern	(	const ImagePlane &	plane,
		CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		int	gridSpacing,
		int	minContrast,
		double	maxRatio,
		int	order,
		Area2D	aoi,
		CreationProgress	progressCallback = CreationProgress() )

inlinestatic

Create a new transformation object by automatically extracting 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]	order	Polynomial order of the transformation to be generated.
[in]	aoi	Area of interest in which to look for the calibration pattern's dots.
[in]	progressCallback	Callback to be used for passing progress information back to the caller.

Returns: Pointer to the transformation object.

Exceptions

Any	exception derived from std::exception including CvbException.

The image plane given to this method needs to contain a calibration pattern as generated by the method 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 working on the output of GetCalibrationLists 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.

◆ FromCalibrationPattern() [2/2]

static std::unique_ptr< NonLinearTransformation > FromCalibrationPattern	(	const ImagePlane &	plane,
		CalibrationPatternStyle	style,
		CalibrationPatternContrast	contrast,
		int	gridSpacing,
		int	minContrast,
		double	maxRatio,
		int	order,
		CreationProgress	progressCallback = CreationProgress() )

inlinestatic

Create a new transformation object by automatically extracting 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]	order	Polynomial order of the transformation to be generated.
[in]	progressCallback	Callback to be used for passing progress information back to the caller.

Returns: Pointer to the transformation object.

Exceptions

Any	exception derived from std::exception including CvbException.

The image plane given to this method needs to contain a calibration pattern as generated by the method 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). 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.

◆ FromHandle()

static std::unique_ptr< NonLinearTransformation > FromHandle ( HandleGuard< NonLinearTransformation > && guard )

inlinestatic

Creates transformation from a classic API handle.

Parameters

[in] guard Life time guard for C-API handle.

Returns: The transformation created from the classic API handle.

Exceptions

Any	exception derived from std::exception including CvbException.

The transformation takes ownership of the handle, so you must share it before using this function.

◆ FromPositionLists()

template<class RANGE>

static TypedRange< std::unique_ptr< NonLinearTransformation >, Point2D< double >, RANGE >::type FromPositionLists	(	const RANGE &	originalPixels,
		const RANGE &	transformedPixels,
		int	order,
		CreationProgress	progressCallback = CreationProgress() )

inlinestatic

Create a non linear transformation that - approximately - matches the set of originalPixels to the set of transformedPixels.

Parameters

[in]	originalPixels	Originial pixel locations. The pixels as measured from an image.
[in]	transformedPixels	Transformed pixels. The locations the corresponding pixels from originalPixels should ideally have.
[in]	order	Polynomial order of the transformation to be generated.
[in]	progressCallback	Callback to be used for passing progress information back to the caller.

Returns: Pointer to the transformation object.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Handle()

void * Handle ( ) const

inlinenoexcept

Classic API NLTRANSFORMATION handle.

Returns: Classic API handle.

Exceptions

Does	not throw any exception.

It is normally not necessary to work with this handle.

◆ InverseTransform() [1/3]

std::unique_ptr< Image > InverseTransform	(	const Image &	image,
		Size2D< int >	targetSize,
		Point2D< int >	targetOffset )

inline

Back transform an image with this nonlinear transformation.

Parameters

[in]	image	Image to transform.
[in]	targetSize	Target size of the transformed image.
[in]	targetOffset	Origin offset of the transformed image.

Returns: The transformed image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ InverseTransform() [2/3]

template<class RANGE>

TypedRange< std::vector< Point2D< double > >, Point2D< double >, RANGE >::type InverseTransform ( const RANGE & points )

inline

Back transform a sequence of points with this nonlinear transformation.

Parameters

[in] points Points to transform.

Returns: The transformed points.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ InverseTransform() [3/3]

Point2D< double > InverseTransform ( Point2D< double > point )

inline

Back transform a point with this nonlinear transformation.

Parameters

[in] point Point to transform.

Returns: The transformed point.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Load()

static std::unique_ptr< NonLinearTransformation > Load ( const String & fileName )

inlinestatic

Load a saved transformation from a file.

Parameters

[in] fileName Name of the file to load.

Returns: Pointer to the loaded transformation.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Order()

int Order ( ) const

inlinenoexcept

Gets the transformation order.

Returns: The projection mode.

Exceptions

Does	not throw any exception.

◆ Save()

void Save ( const String & fileName ) const

inline

Write the transformation to a file.

Parameters

[in] fileName Path to save to.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Transform() [1/4]

std::unique_ptr< Image > Transform	(	const Image &	image,
		Size2D< int >	targetSize,
		Point2D< int >	targetOffset )

inline

Transform an image with this nonlinear transformation.

Parameters

[in]	image	Image to transform.
[in]	targetSize	Target size of the transformed image.
[in]	targetOffset	Origin offset of the transformed image.

Returns: The transformed image.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Transform() [2/4]

template<class RANGE>

TypedRange< std::vector< Point2D< double > >, Point2D< double >, RANGE >::type Transform ( const RANGE & points )

inline

Transform a sequence of points with this nonlinear transformation.

Parameters

[in] points Points to transform.

Returns: The transformed points.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Transform() [3/4]

Point2D< double > Transform ( Point2D< double > point )

inline

Transform a point with this nonlinear transformation.

Parameters

[in] point Point to transform.

Returns: The transformed point.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ Transform() [4/4]

Rect< double > Transform ( Rect< double > rect )

inline

Transform a rect with this nonlinear transformation.

Parameters

[in] rect Rect to transform.

Returns: The transformed rect.

Exceptions

Any	exception derived from std::exception including CvbException.

Note: The transformed rect is a estimate of the target dimensions needed for a transformed image. Due to the non linearity of the transformation it may not be correct. Consider it a best guess.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NonLinearTransformation()

Member Function Documentation

◆ CoefficientsX()

◆ CoefficientsXInverse()

◆ CoefficientsY()

◆ CoefficientsYInverse()

◆ FromCalibrationPattern() [1/2]

◆ FromCalibrationPattern() [2/2]

◆ FromHandle()

◆ FromPositionLists()

◆ Handle()

◆ InverseTransform() [1/3]

◆ InverseTransform() [2/3]

◆ InverseTransform() [3/3]

◆ Load()

◆ Order()

◆ Save()

◆ Transform() [1/4]

◆ Transform() [2/4]

◆ Transform() [3/4]

◆ Transform() [4/4]