astMapBox

Find a bounding box for a Mapping

Description:

This function 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 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.

Synopsis

void astMapBox( AstMapping $\ast$this, const double lbnd_in[], const double ubnd_in[], int forward, int coord_out, double $\ast$lbnd_out, double $\ast$ubnd_out, double xl[], double xu[] );

Parameters:

this
Pointer to the Mapping.
lbnd_in
Pointer to an array of double, with one element for each Mapping input coordinate. This should contain the lower bound of the input box in each input dimension.
ubnd_in
Pointer to an array of double, 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
If this value is non-zero, 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" parameter, below, should nominate one of the Mapping s input coordinates.)

coord_out
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
Pointer to a double in which to return the lowest value taken by the nominated output coordinate within the specified region of input coordinate space.
ubnd_out
Pointer to a double in which to return the highest value taken by the nominated output coordinate within the specified region of input coordinate space.
xl
An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with 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 " $\ast$lbnd_out" .

If these coordinates are not required, a NULL pointer may be supplied.

xu
An optional pointer to an array of double, with one element for each Mapping input coordinate. If given, this array will be filled with 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 " $\ast$ubnd_out" .

If these coordinates are not required, a NULL pointer may be supplied.

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 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.