Surface spline world coordinate transformation. More...

#include <WorldTransformation.h>

Inheritance diagram for pcl::SplineWorldTransformation:

Public Member Functions
	SplineWorldTransformation (const Array< DPoint > &controlPointsW, const Array< DPoint > &controlPointsI, float smoothness=__PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS, const FVector &weights=FVector(), int order=__PCL_WCS_DEFAULT_SPLINE_ORDER, bool enableSimplifier=__PCL_WCS_SURFACE_SIMPLIFIER_DEFAULT_ENABLED, float simplifierRejectFraction=__PCL_WCS_SURFACE_SIMPLIFIER_DEFAULT_REJECT_FRACTION)

	SplineWorldTransformation (const ByteArray &data, const LinearTransformation &linearIW=LinearTransformation::Null())

	SplineWorldTransformation (const PropertyArray &properties, const LinearTransformation &linearIW=LinearTransformation::Null())

	SplineWorldTransformation (const SplineWorldTransformation &)=default

	SplineWorldTransformation (SplineWorldTransformation &&)=default

	~SplineWorldTransformation () override

const LinearTransformation &	ApproximateLinearTransform () const override

WorldTransformation *	Clone () const override

DPoint	Direct (const DPoint &pW) const override

void	GetSplineErrors (double &xWI, double &yWI, double &xIW, double &yIW) const

void	GetSplineLengths (int &xWI, int &yWI, int &xIW, int &yIW) const

bool	HasGridInterpolations () const

const Array< DPoint > &	ImageControlPoints () const

void	InitializeGridInterpolations (const Rect &rectI, int deltaI=16)

DPoint	Inverse (const DPoint &pI) const override

bool	IsEmpty () const override

const Array< DPoint > &	NativeControlPoints () const

int	NumberOfControlPoints () const

SplineWorldTransformation &	operator= (const SplineWorldTransformation &)=default

SplineWorldTransformation &	operator= (SplineWorldTransformation &&)=default

void	Serialize (ByteArray &data) const

float	SimplifierRejectFraction () const

bool	SimplifiersEnabled () const

int	SplineOrder () const

PropertyArray	ToProperties () const

bool	TruncatedControlPoints () const

const IsoString &	Version () const

Public Member Functions inherited from pcl::WorldTransformation
	WorldTransformation ()=default

	WorldTransformation (const WorldTransformation &)=default

virtual	~WorldTransformation ()

Static Public Member Functions
static IsoString	PropertyPrefix ()

Detailed Description

SplineWorldTransformation implements a world coordinate transform based on 2-D interpolating/approximating surface splines (also known as thin plate splines). These mathematical modeling devices allow for accurate representations of coordinate systems subject to arbitrary local distortions, which are impossible to achieve with linear transformations.

The underlying implementation of this class uses the SurfaceSpline, PointSurfaceSpline, SurfaceSimplifier and PointGridInterpolation classes.

Definition at line 250 of file WorldTransformation.h.

Constructor & Destructor Documentation

◆ SplineWorldTransformation() [1/5]

pcl::SplineWorldTransformation::SplineWorldTransformation	(	const Array< DPoint > &	controlPointsW,
		const Array< DPoint > &	controlPointsI,
		float	smoothness = `__PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS`,
		const FVector &	weights = `FVector()`,
		int	order = `__PCL_WCS_DEFAULT_SPLINE_ORDER`,
		bool	enableSimplifier = `__PCL_WCS_SURFACE_SIMPLIFIER_DEFAULT_ENABLED`,
		float	simplifierRejectFraction = `__PCL_WCS_SURFACE_SIMPLIFIER_DEFAULT_REJECT_FRACTION`
	)

inline

Constructs a 2-D spline based world coordinate transformation.

Parameters

controlPointsW	Array of world control points. Each point in this array must contain spherical coordinates in the native world coordinate system of the astrometric solution, expressed in degrees. For a given point p in this array, p.x is the native longitude coordinate and p.y is the latitude.
controlPointsI	Array of image control points. Each point in this array must contain the coordinates on the X and Y axes of the image plane corresponding to the same point in the controlPointsW array. In other words, there must be a one-to-one correspondence between world and image control points.
smoothness	Spline regularization factor. When this parameter is greater than zero, approximating splines will be generated instead of interpolating splines. The higher this value, the closer the 2-D approximating surface will be to the reference plane of the image. Approximating surface splines are more robust to noise in the sets of control points and hence recommended in virtually all cases. The value of this parameter should be relatively small if enableSimplifier is true, since the surface simplification algorithm already performs robust rejection of outliers. The default value is 0.005.
weights	When the smoothness parameter is greater than zero and this vector is not empty, it must define a positive weight greater than zero for each point defined by the controlPointsW and controlPointsI arrays. If smoothness is zero or negative, this parameter will be ignored. See the PointSurfaceSpline::Initialize() member function for detailed information on 2-D spline node weights. If enableSimplifier is true, control point weights are not used and hence the value of this parameter will be ignored.
order	Derivative order of continuity. The default value is 2. Higher orders, such as 3 or 4, can improve adaptability to model complex field distortions. Orders above 4 can lead to ill-conditioned linear systems, causing errors while building the surface splines.
enableSimplifier	If true, a surface simplification algorithm will be applied to the lists of control points for surface spline generation. The use of surface simplification greatly improves efficiency of surface splines by removing all redundant points and keeping only the control points required to define the coordinate transformations accurately. In addition, the applied surface simplification algorithm implements robust PCA fitting and outlier rejection techniques that improve the generated interpolation devices in terms of resilience to noise and invalid data in the underlying astrometric solution. This option is enabled by default. When this parameter is true, the weights parameter is ignored.
simplifierRejectFraction	Fraction of rejected control points for simplification of surface subregions. The default value is 0.10.

Thanks to the implemented surface simplification algorithms, we can work with very large sets of control points to generate astrometric solutions able to model strong and complex arbitrary field distortions accurately and efficiently. Surface simplification concentrates control points just where they are necessary to represent distortions, leaving undistorted regions of the image covered by a minimal grid.

Newly constructed instances are guaranteed to be valid (in the structural and numerical senses; note that this does not necessarily imply that the underlying astrometric solution is valid). In the event of invalid input data or spline initialization problems, this constructor will throw an Error exception.

After surface spline initialization, an approximate linear transformation will also be calculated automatically.

Definition at line 340 of file WorldTransformation.h.

◆ SplineWorldTransformation() [2/5]

pcl::SplineWorldTransformation::SplineWorldTransformation	(	const PropertyArray &	properties,
		const LinearTransformation &	linearIW = `LinearTransformation::Null()`
	)

Constructs a SplineWorldTransformation object from a list of XISF image properties and optional linear approximation linearIW.

This constructor will acquire structural parameters and data from properties with the PCL:AstrometricSolution:SplineWorldTransformation: identifier prefix.

If a valid linear transformation is specified, the PCL:AstrometricSolution:SplineWorldTransformation:LinearApproximation property will be ignored and the specified linear transformation will be used instead.

◆ SplineWorldTransformation() [3/5]

pcl::SplineWorldTransformation::SplineWorldTransformation	(	const ByteArray &	data,
		const LinearTransformation &	linearIW = `LinearTransformation::Null()`
	)

inline

Constructs a SplineWorldTransformation instance by deserializing the specified raw data, with an optional approximate linear transformation linearIW.

If no valid linear transformation is specified, an approximate one will be calculated automatically.

Definition at line 383 of file WorldTransformation.h.

◆ SplineWorldTransformation() [4/5]

pcl::SplineWorldTransformation::SplineWorldTransformation ( const SplineWorldTransformation & )

default

Copy constructor.

◆ SplineWorldTransformation() [5/5]

pcl::SplineWorldTransformation::SplineWorldTransformation ( SplineWorldTransformation && )

default

Move constructor.

◆ ~SplineWorldTransformation()

pcl::SplineWorldTransformation::~SplineWorldTransformation ( )

inlineoverride

Destroys a SplineWorldTransformation object.

Definition at line 406 of file WorldTransformation.h.

Member Function Documentation

◆ ApproximateLinearTransform()

const LinearTransformation& pcl::SplineWorldTransformation::ApproximateLinearTransform ( ) const

inlineoverridevirtual

Returns an approximate linear transformation from image to native spherical coordinates, computed from the internal point surface splines.

Implements pcl::WorldTransformation.

Definition at line 491 of file WorldTransformation.h.

◆ Clone()

WorldTransformation* pcl::SplineWorldTransformation::Clone ( ) const

inlineoverridevirtual

Returns a dynamically allocated copy of this object.

Implements pcl::WorldTransformation.

Definition at line 434 of file WorldTransformation.h.

◆ Direct()

DPoint pcl::SplineWorldTransformation::Direct ( const DPoint & pW ) const

inlineoverridevirtual

Transforms from native spherical coordinates to image coordinates.

The point pW contains native spherical coordinates: pW.x is the native longitude and pW.y is the native latitude, both expressed in degrees. Returns image coordinates in pixels corresponding to pW.

If grid interpolations have been initialized for this object, and the specified point pW is included in the reference rectangle used for grid initialization, they will be used transparently by this member function. Otherwise, the surface splines will be evaluated directly, which can be much slower, depending on the number of control points defined by the astrometric solution.

See also: Inverse(), InitializeGridInterpolations()

Implements pcl::WorldTransformation.

Definition at line 455 of file WorldTransformation.h.

◆ GetSplineErrors()

void pcl::SplineWorldTransformation::GetSplineErrors	(	double &	xWI,
		double &	yWI,
		double &	xIW,
		double &	yIW
	)		const

inline

Returns the residual errors in pixels after surface simplification.

Parameters

[out]	xWI	Simplification error for the world-to-image coordinate transformation on the native longitude direction.
[out]	yWI	Simplification error for the world-to-image coordinate transformation on the native latitude direction.
[out]	xIW	Simplification error for image-to-world coordinate transformation on the X-axis direction.
[out]	yIW	Simplification error for image-to-world coordinate transformation on the Y-axis direction.

Definition at line 734 of file WorldTransformation.h.

◆ GetSplineLengths()

void pcl::SplineWorldTransformation::GetSplineLengths	(	int &	xWI,
		int &	yWI,
		int &	xIW,
		int &	yIW
	)		const

inline

Provides the number of data points in the internal surface splines used for coordinate transformations.

Parameters

[out]	xWI	Number of spline points used for world-to-image coordinate transformations on the native longitude direction.
[out]	yWI	Number of spline points used for world-to-image coordinate transformations on the native latitude direction.
[out]	xIW	Number of spline points used for image-to-world coordinate transformations on the X-axis direction.
[out]	yIW	Number of spline points used for image-to-world coordinate transformations on the Y-axis direction.

Definition at line 673 of file WorldTransformation.h.

◆ HasGridInterpolations()

bool pcl::SplineWorldTransformation::HasGridInterpolations ( ) const

inline

Returns true if the internal grid interpolation devices have been initialized. See InitializeGridInterpolations() for information on grid interpolation.

Definition at line 570 of file WorldTransformation.h.

◆ ImageControlPoints()

const Array<DPoint>& pcl::SplineWorldTransformation::ImageControlPoints ( ) const

inline

Returns a reference to the list of control points in image coordinates.

For each point p in the returned array, p.x and p.y are the components of a control point in image coordinates, expressed in pixels.

For each point p in the returned array, there is a corresponding point q in the array of native control points returned by the NativeControlPoints() member function, whose q.x and q.y components are the spherical native coordinates in degrees corresponding to p.

Definition at line 641 of file WorldTransformation.h.

◆ InitializeGridInterpolations()

void pcl::SplineWorldTransformation::InitializeGridInterpolations	(	const Rect &	rectI,
		int	deltaI = `16`
	)

inline

Initializes the internal grid interpolation devices for the specified reference rectangular region rectI and grid distance deltaI in pixels.

A grid distance of 16 pixels is applied by default. This is normally more than sufficient to yield accurate coordinate readouts, even for strongly distorted images. The accepted range is from 1 to 64 pixels.

See GridInterpolation::Initialize() for detailed information on spline grid interpolation and its working parameters.

Note: This member function will show no console messages. If some feedback must be provided to the user during the potentially long operation, it must be given before calling this function.

Definition at line 521 of file WorldTransformation.h.

References pcl::GenericRectangle< T >::Height(), pcl::Range(), pcl::GenericRectangle< T >::Width(), pcl::GenericPoint< T >::x, pcl::GenericRectangle< T >::x0, pcl::GenericRectangle< T >::x1, pcl::GenericPoint< T >::y, pcl::GenericRectangle< T >::y0, and pcl::GenericRectangle< T >::y1.

◆ Inverse()

DPoint pcl::SplineWorldTransformation::Inverse ( const DPoint & pI ) const

inlineoverridevirtual

Transforms from image coordinates to native spherical coordinates.

The specified point pI contains image coordinates in pixels. Returns a point pW where pW.x is the native longitude and pW.y is the native latitude, both expressed in degrees, corresponding to pI.

If grid interpolations have been initialized for this object, and the specified point pI is included in the reference rectangle used for grid initialization, they will be used transparently by this member function. Otherwise, the surface splines will be evaluated directly, which can be much slower, depending on the number of control points defined by the astrometric solution.

See also: Direct(), InitializeGridInterpolations()

Implements pcl::WorldTransformation.

Definition at line 479 of file WorldTransformation.h.

◆ IsEmpty()

bool pcl::SplineWorldTransformation::IsEmpty ( ) const

inlineoverridevirtual

Returns true iff this object has no working data.

With the restrictions imposed by class constructors, this can only happen if this object is an xvalue after move construction or assignment.

Reimplemented from pcl::WorldTransformation.

Definition at line 426 of file WorldTransformation.h.

◆ NativeControlPoints()

const Array<DPoint>& pcl::SplineWorldTransformation::NativeControlPoints ( ) const

inline

Returns a reference to the list of control points in native spherical coordinates.

For each point p in the returned array, p.x is the native longitude and p.y is the native latitude, both expressed in degrees.

For each point p in the returned array, there is a corresponding point q in the array of image control points returned by the ImageControlPoints() member function, whose q.x and q.y components are the image coordinates in pixels corresponding to p.

Definition at line 624 of file WorldTransformation.h.

◆ NumberOfControlPoints()

int pcl::SplineWorldTransformation::NumberOfControlPoints ( ) const

inline

Returns the number of control points employed to generate the surface splines used for coordinate transformations.

The value returned by this function is the length of the original list of control points specified upon object construction or deserialization; the actual sets of data points being used internally by surface splines are usually smaller because surface simplification is enabled by default.

See also: NativeControlPoints(), ImageControlPoints(), GetSplineLengths()

Definition at line 607 of file WorldTransformation.h.

◆ operator=() [1/2]

SplineWorldTransformation& pcl::SplineWorldTransformation::operator= ( const SplineWorldTransformation & )

default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

SplineWorldTransformation& pcl::SplineWorldTransformation::operator= ( SplineWorldTransformation && )

default

Move assignment operator. Returns a reference to this object.

◆ PropertyPrefix()

static IsoString pcl::SplineWorldTransformation::PropertyPrefix ( )

inlinestatic

Returns the identifier prefix of all XISF properties used to serialize a SplineWorldTransformation object.

Definition at line 579 of file WorldTransformation.h.

◆ Serialize()

void pcl::SplineWorldTransformation::Serialize ( ByteArray & data ) const

Serializes this SplineWorldTransformation instance in raw binary format and stores the result in the specified data array.

◆ SimplifierRejectFraction()

float pcl::SplineWorldTransformation::SimplifierRejectFraction ( ) const

inline

Returns the outlier rejection fraction of the surface simplifier used for generation of surface splines. See the class constructor for more information.

Definition at line 714 of file WorldTransformation.h.

◆ SimplifiersEnabled()

bool pcl::SplineWorldTransformation::SimplifiersEnabled ( ) const

inline

Returns true iff the surface simplification algorithm has been enabled for generation of surface splines. See the class constructor for more information.

Definition at line 704 of file WorldTransformation.h.

◆ SplineOrder()

int pcl::SplineWorldTransformation::SplineOrder ( ) const

inline

Returns the derivative order of continuity of the internal surface splines used for coordinate transformations.

Definition at line 650 of file WorldTransformation.h.

◆ ToProperties()

PropertyArray pcl::SplineWorldTransformation::ToProperties ( ) const

Returns a list of XISF image properties serializing this SplineWorldTransformation object.

◆ TruncatedControlPoints()

bool pcl::SplineWorldTransformation::TruncatedControlPoints ( ) const

inline

Returns true iff the lists of transformation control points were truncated before generation of surface splines.

No truncation should happen under normal working conditions if surface simplification is enabled.

If no simplification is used, truncation may happen directly on the original lists of control points. Without surface simplification, a maximum of 2100 control points is imposed in the current implementation to prevent excessive execution times for surface spline generation, which grow approximately with O(n^3) complexity.

Definition at line 694 of file WorldTransformation.h.

◆ Version()

const IsoString& pcl::SplineWorldTransformation::Version ( ) const

inline

Returns the serialization version of this SplineWorldTransformation object. Currently this member function returns "1.3".

Definition at line 500 of file WorldTransformation.h.

The documentation for this class was generated from the following file:

WorldTransformation.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SplineWorldTransformation() [1/5]

◆ SplineWorldTransformation() [2/5]

◆ SplineWorldTransformation() [3/5]

◆ SplineWorldTransformation() [4/5]

◆ SplineWorldTransformation() [5/5]

◆ ~SplineWorldTransformation()

Member Function Documentation

◆ ApproximateLinearTransform()

◆ Clone()

◆ Direct()

◆ GetSplineErrors()

◆ GetSplineLengths()

◆ HasGridInterpolations()

◆ ImageControlPoints()

◆ InitializeGridInterpolations()

◆ Inverse()

◆ IsEmpty()

◆ NativeControlPoints()

◆ NumberOfControlPoints()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PropertyPrefix()

◆ Serialize()

◆ SimplifierRejectFraction()

◆ SimplifiersEnabled()

◆ SplineOrder()

◆ ToProperties()

◆ TruncatedControlPoints()

◆ Version()