Find a bounding box for a Mapping
" 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 function 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. Optionally, 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" parameter, below, should
nominate one of the Mapping’ s input coordinates.)
"
∗lbnd_out"
.
If these coordinates are not required, a NULL pointer may be supplied.
"
∗ubnd_out"
.
If these coordinates are not required, a NULL pointer may be supplied.
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 function 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 function should fail for any reason. Their initial values on
entry will not be altered if the function is invoked with the AST error status set.