next up previous 264
Next: AST_MAPCOPY - Copy entries from one KeyMap into another
Up: AST Routine Descriptions
Previous: AST_LUTMAP - Create a LutMap


AST_MAPBOX - Find a bounding box for a Mapping

Description:
This routine allows you to find the "bounding box" which just encloses another box after it has been transformed by a Mapping (using either its forward or inverse transformation). A typical use might be to calculate the size of an image after being transformed by a Mapping.

The routine works on one dimension at a time. When supplied with the lower and upper bounds of a rectangular region (box) of input coordinate space, it finds the lowest and highest values taken by a nominated output coordinate within that region. It also returns the input coordinates where these bounding values are attained. It should be used repeatedly to obtain the extent of the bounding box in more than one dimension.

Invocation:
CALL AST_MAPBOX( THIS, LBND_IN, UBND_IN, FORWARD, COORD_OUT, LBND_OUT, UBND_OUT, XL, XU, STATUS )
Arguments:
THIS = INTEGER (Given)
Pointer to the Mapping.
LBND_IN( $*$ ) = DOUBLE PRECISION (Given)
An array with one element for each Mapping input coordinate. This should contain the lower bound of the input box in each input dimension.
UBND_IN( $*$ ) = DOUBLE PRECISION (Given)
An array with one element for each Mapping input coordinate. This should contain the upper bound of the input box in each input dimension.

Note that it is permissible for the upper bound to be less than the corresponding lower bound, as the values will simply be swapped before use.

FORWARD = LOGICAL (Given)
If this value is .TRUE., then the Mapping's forward transformation will be used to transform the input box. Otherwise, its inverse transformation will be used.

(If the inverse transformation is selected, then references to "input" and "output" coordinates in this description should be transposed. For example, the size of the LBND_IN and UBND_IN arrays should match the number of output coordinates, as given by the Mapping's Nout attribute. Similarly, the COORD_OUT argument, below, should nominate one of the Mapping's input coordinates.)

COORD_OUT = INTEGER (Given)
The index of the output coordinate for which the lower and upper bounds are required. This value should be at least one, and no larger than the number of Mapping output coordinates.
LBND_OUT = DOUBLE PRECISION (Returned)
The lowest value taken by the nominated output coordinate within the specified region of input coordinate space.
UBND_OUT = DOUBLE PRECISION (Returned)
The highest value taken by the nominated output coordinate within the specified region of input coordinate space.
XL( $*$ ) = DOUBLE PRECISION (Returned)
An array with one element for each Mapping input coordinate. This will return the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the lower bound value returned in LBND_OUT.
XU( $*$ ) = DOUBLE PRECISION (Returned)
An array with one element for each Mapping input coordinate. This will return the coordinates of an input point (although not necessarily a unique one) for which the nominated output coordinate attains the upper bound value returned in UBND_OUT.
STATUS = INTEGER (Given and Returned)
The global status.
Notes:
  • Any input points which are transformed by the Mapping to give output coordinates containing the value AST__BAD are regarded as invalid and are ignored. They will make no contribution to determining the output bounds, even although the nominated output coordinate might still have a valid value at such points.

  • An error will occur if the required output bounds cannot be found. Typically, this might happen if all the input points which the routine considers turn out to be invalid (see above). The number of points considered before generating such an error is quite large, so this is unlikely to occur by accident unless valid points are restricted to a very small subset of the input coordinate space.

  • The values returned via LBND_OUT, UBND_OUT, XL and XU will be set to the value AST__BAD if this routine should fail for any reason. Their initial values on entry will not be altered if the routine is invoked with STATUS set to an error value.


next up previous 264
Next: AST_MAPCOPY - Copy entries from one KeyMap into another
Up: AST Routine Descriptions
Previous: AST_LUTMAP - Create a LutMap

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