astLinearApprox

←Prev
AST
A Library for Handling
World Coordinate Systems
in Astronomy
Next→
TOC ↑

astLinearApprox

Obtain a linear approximation to a Mapping, if appropriate

Description:

This function tests the forward coordinate transformation implemented by a Mapping over a given range of input coordinates. If the transformation is found to be linear to a specified level of accuracy, then an array of fit coefficients is returned. These may be used to implement a linear approximation to the Mapping’ s forward transformation within the specified range of output coordinates. If the transformation is not sufficiently linear, no coefficients are returned.

Synopsis

int astLinearApprox( AstMapping

*

this, const double

*

lbnd, const double

*

ubnd, double tol, double

*

fit )

Parameters:

this

Pointer to the Mapping.

lbnd

Pointer to an array of doubles containing the lower bounds of a box defined within the input coordinate system of the Mapping. The number of elements in this array should equal the value of the Mapping’ s Nin attribute. This box should specify the region over which linearity is required.

ubnd

Pointer to an array of doubles containing the upper bounds of the box specifying the region over which linearity is required.

tol

The maximum permitted deviation from linearity, expressed as a positive Cartesian displacement in the output coordinate space of the Mapping. If a linear fit to the forward transformation of the Mapping deviates from the true transformation by more than this amount at any point which is tested, then no fit coefficients will be returned.

fit

Pointer to an array of doubles in which to return the co-efficients of the linear approximation to the specified transformation. This array should have at least " ( Nin

+

1 )

*

Nout" , elements. The first Nout elements hold the constant offsets for the transformation outputs. The remaining elements hold the gradients. So if the Mapping has 2 inputs and 3 outputs the linear approximation to the forward transformation is:

X_out = fit[0] $+$ fit[3] $*$ X_in $+$ fit[4] $*$ Y_in

Y_out = fit[1] $+$ fit[5] $*$ X_in $+$ fit[6] $*$ Y_in

Z_out = fit[2] $+$ fit[7] $*$ X_in $+$ fit[8] $*$ Y_in

Returned Value

astLinearApprox()

If the forward transformation is sufficiently linear, a non-zero value is returned. Otherwise zero is returned and the fit co-efficients are set to AST__BAD.

Notes:

This function fits the Mapping’ s forward transformation. To fit the inverse transformation, the Mapping should be inverted using astInvert before invoking this function.
If a Mapping output is found to have a bad value (AST__BAD) at one or more of the test points used in the linearity test, then all the values in the returned fit that correspond to that output are set to AST__BAD. However, this does not affect the linearity tests on the other Mapping outputs - if they are all found to be linear then usable coefficients will be returned for them in the fit, and the function will return a non-zero value. Consequently, it may be necessary to check that the values in the returned fit are not AST__BAD before using them. If all Mapping outputs generate bad values, then zero is returned as the function value.
A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.
If all tested positions within the supplied box generate bad output positions, then the returned function value will be zero. However, the returned coefficients will represent a unit transformation, except that the constant term for each output will be set to AST__BAD.

←Prev
AST
A Library for Handling
World Coordinate Systems
in Astronomy
Next→
TOC ↑