next up previous 264
Next: astIntraMap - Create an IntraMap
Up: AST Function Descriptions
Previous: astIntersect - Find the point of intersection between two geodesic curves


astInterval - Create a Interval

Description:
This function creates a new Interval and optionally initialises its attributes.

A Interval is a Region which represents upper and/or lower limits on one or more axes of a Frame. For a point to be within the region represented by the Interval, the point must satisfy all the restrictions placed on all the axes. The point is outside the region if it fails to satisfy any one of the restrictions. Each axis may have either an upper limit, a lower limit, both or neither. If both limits are supplied but are in reverse order (so that the lower limit is greater than the upper limit), then the interval is an excluded interval, rather than an included interval.

At least one axis limit must be supplied.

Note, The Interval class makes no allowances for cyclic nature of some coordinate systems (such as SkyFrame coordinates). A Box should usually be used in these cases since this requires the user to think about suitable upper and lower limits,

Synopsis:
AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[], const double ubnd[], AstRegion $*$unc, const char $*$options, ... )
Parameters:
frame
A pointer to the Frame in which the region is defined. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region.
lbnd
An array of double, with one element for each Frame axis (Naxes attribute) containing the lower limits on each axis. Set a value to AST__BAD to indicate that the axis has no lower limit.
ubnd
An array of double, with one element for each Frame axis (Naxes attribute) containing the upper limits on each axis. Set a value to AST__BAD to indicate that the axis has no upper limit.
unc
An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied "uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) or be a Prism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL Object pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created.

The uncertainty Region has two uses: 1) when the astOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region.

options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Interval. The syntax used is identical to that for the astSet function and may include "printf" format specifiers identified by "%" symbols in the normal way.
...
If the "options" string contains "%" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C "printf" function).
Returned Value:
astInterval()
A pointer to the new Interval.
Notes:
  • A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".


next up previous 264
Next: astIntraMap - Create an IntraMap
Up: AST Function Descriptions
Previous: astIntersect - Find the point of intersection between two geodesic curves

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

Copyright (C) 2009 Science \& Technology Facilities Council