Find a bounding box for a Mapping AST_MAPBOX
" 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.
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.
’ 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.)
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.