next up previous 264
Next: AST_PRISM - Create a Prism
Up: AST Routine Descriptions
Previous: AST_POLYMAP - Create a PolyMap


AST_POLYTRAN - Fit a PolyMap inverse or forward transformation

Description:
This function creates a new PolyMap which is a copy of the supplied PolyMap, in which a specified transformation (forward or inverse) has been replaced by a new polynomial function. The coefficients of the new transformation are estimated by sampling the other transformation and performing a least squares polynomial fit in the opposite direction to the sampled positions and values.

The transformation to create is specified by the FORWARD parameter. In what follows "X" refers to the inputs of the PolyMap, and "Y" to the outputs of the PolyMap. The forward transformation transforms input values (X) into output values (Y), and the inverse transformation transforms output values (Y) into input values (X). Within a PolyMap, each transformation is represented by an independent set of polynomials: Y=P_f(X) for the forward transformation and X=P_i(Y) for the inverse transformation.

If FORWARD is .FALSE., a new inverse transformation is created by first finding the output values (Y) using the forward transformation (which must be available) at a regular grid of points (X) covering a rectangular region of the PolyMap's input space. The coefficients of the required inverse polynomial, X=P_i(Y), are chosen in order to minimise the sum of the squared residuals between the sampled values of X and P_i(Y).

If FORWARD is .TRUE., a new forward transformation is created by first finding the input values (X) using the inverse transformation (which must be available) at a regular grid of points (Y) covering a rectangular region of the PolyMap's output space. The coefficients of the required forward polynomial, Y=P_f(X), are chosen in order to minimise the sum of the squared residuals between the sampled values of Y and P_f(X).

This fitting process is performed repeatedly with increasing polynomial orders (starting with quadratic) until the target accuracy is achieved, or a specified maximum order is reached. If the target accuracy cannot be achieved even with this maximum-order polynomial, the best fitting maximum-order polynomial is returned so long as its accuracy is better than MAXACC. If it is not, an error is reported.

Invocation:
RESULT = AST_POLYTRAN( THIS, FORWARD, ACC, MAXACC, MAXORDER, LBND, UBND, STATUS )
Arguments:
THIS = INTEGER (Given)
Pointer to the original Mapping.
FORWARD = LOGICAL (Given)
If .TRUE., the forward PolyMap transformation is replaced. Otherwise the inverse transformation is replaced.
ACC = DOUBLE (Given)
The target accuracy, expressed as a geodesic distance within the PolyMap's input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
MAXACC = DOUBLE (Given)
The maximum allowed accuracy for an acceptable polynomial, expressed as a geodesic distance within the PolyMap's input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
MAXORDER = INTEGER (Given)
The maximum allowed polynomial order. This is one more than the maximum power of either input axis. So for instance, a value of 3 refers to a quadratic polynomial.
LBND( $*$ ) = DOUBLE PRECISION (Given)
An array holding the lower bounds of a rectangular region within the PolyMap's input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap's Nin or Nout attribute, depending on FORWARD.
UBND( $*$ ) = DOUBLE PRECISION (Given)
An array holding the upper bounds of a rectangular region within the PolyMap's input space (if FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.). The new polynomial will be evaluated over this rectangle. The length of this array should equal the value of the PolyMap's Nin or Nout attribute, depending on FORWARD.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_POLYTRAN = INTEGER
A pointer to the new PolyMap.
Notes:
  • This function can only be used on 1D or 2D PolyMaps which have the same number of inputs and outputs.

  • An error will be reported if a successfull fit cannot be found.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason.


next up previous 264
Next: AST_PRISM - Create a Prism
Up: AST Routine Descriptions
Previous: AST_POLYMAP - Create a PolyMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council