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, rbf_type rbf=__PCL_WCS_DEFAULT_SPLINE_RBF, float smoothness=__PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS, int order=__PCL_WCS_DEFAULT_SPLINE_ORDER, bool enableSimplifier=__PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_ENABLED, float simplifierRejectFraction=__PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_REJECT_FRACTION, const FVector &weights=FVector())

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

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

	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

double	GridInterpolationDelta () 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

int	MaxSplinePoints () const

const Array< DPoint > &	NativeControlPoints () const

int	NumberOfControlPoints () const

SplineWorldTransformation &	operator= (const SplineWorldTransformation &)=default

SplineWorldTransformation &	operator= (SplineWorldTransformation &&)=default

rbf_type	RBFType () const

IsoString	RBFTypeName () const

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 258 of file WorldTransformation.h.

Constructor & Destructor Documentation

◆ SplineWorldTransformation() [1/5]

pcl::SplineWorldTransformation::SplineWorldTransformation	(	const Array< DPoint > &	controlPointsW,
		const Array< DPoint > &	controlPointsI,
		rbf_type	rbf = `__PCL_WCS_DEFAULT_SPLINE_RBF`,
		float	smoothness = `__PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS`,
		int	order = `__PCL_WCS_DEFAULT_SPLINE_ORDER`,
		bool	enableSimplifier = `__PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_ENABLED`,
		float	simplifierRejectFraction = `__PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_REJECT_FRACTION`,
		const FVector &	weights = `FVector()`
	)

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.
rbf	The type of radial basis function (RBF) that will be used for the generation of interpolation or approximation surface splines. Currently the following RBFs are supported for spline-based astrometric solutions: RadialBasisFunction::ThinPlateSpline RadialBasisFunction::VariableOrder RadialBasisFunction::DDMVariableOrder RadialBasisFunction::DDMThinPlateSpline RadialBasisFunction::DDMMultiquadric The default value is DDMThinPlateSpline when a running core PixInsight application is available; ThinPlateSpline otherwise.
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 small if enableSimplifier is true, since the surface simplification algorithm already performs robust rejection of outliers. The default value is 0.005.
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.
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.

Thanks to the implemented surface simplification and DDM-based RBF interpolation algorithms (the latter only when a running PixInsight core application is available), we can work with 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 where they are necessary to represent distortions, leaving undistorted image regions covered by a minimal grid. DDM RBF interpolation/approximation allows us to use very large sets of control points thanks to its O(n^2) time complexity, in contrast to standard implementations based on the solution of dense linear systems, requiring O(n^3) time.

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 371 of file WorldTransformation.h.

◆ SplineWorldTransformation() [2/5]

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

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

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

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

If the regenerate parameter is true, the internal surface splines and other working structures will be recalculated, even if they can be reconstructed from existing properties, and no grid interpolations will be loaded or calculated.

◆ 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.

Deprecated:: This constructor is only provided for compatibility with old modules where spline world transformations were serialized as single ByteArray objects. It will be removed in a future version of PCL.

Definition at line 426 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 450 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 535 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 478 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 499 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 824 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 763 of file WorldTransformation.h.

◆ GridInterpolationDelta()

double pcl::SplineWorldTransformation::GridInterpolationDelta ( ) const

inline

Returns the grid distance in pixels used for generation of grid interpolations, or zero if grid interpolations have not been initialized or are not valid in this SplineWorldTransformation object.

See InitializeGridInterpolations() for information on grid interpolation.

Definition at line 626 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 614 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 701 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 565 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 523 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 470 of file WorldTransformation.h.

◆ MaxSplinePoints()

int pcl::SplineWorldTransformation::MaxSplinePoints ( ) const

inline

Returns the maximum number of interpolation points allowed for the internal surface splines used for coordinate transformations.

Definition at line 740 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 684 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 667 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 635 of file WorldTransformation.h.

◆ RBFType()

rbf_type pcl::SplineWorldTransformation::RBFType ( ) const

inline

Returns the type of radial basis function (RBF) used by the internal surface splines. In the current implementation the following basis functions are supported for spline-based astrometric solutions:

RadialBasisFunction::ThinPlateSpline
RadialBasisFunction::VariableOrder
RadialBasisFunction::DDMThinPlateSpline
RadialBasisFunction::DDMMultiquadric

Definition at line 716 of file WorldTransformation.h.

◆ RBFTypeName()

IsoString pcl::SplineWorldTransformation::RBFTypeName ( ) const

Returns an identifying name for the RBF interpolation used for generation of surface splines.

◆ 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.

Deprecated:: This function only exists to support legacy modules and applications, and will be removed in a future PCL version. It must not be used in newly produced code.

◆ 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 804 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 794 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 725 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 784 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 544 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()

◆ GridInterpolationDelta()

◆ HasGridInterpolations()

◆ ImageControlPoints()

◆ InitializeGridInterpolations()

◆ Inverse()

◆ IsEmpty()

◆ MaxSplinePoints()

◆ NativeControlPoints()

◆ NumberOfControlPoints()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PropertyPrefix()

◆ RBFType()

◆ RBFTypeName()

◆ Serialize()

◆ SimplifierRejectFraction()

◆ SimplifiersEnabled()

◆ SplineOrder()

◆ ToProperties()

◆ TruncatedControlPoints()

◆ Version()