This function creates a new
Ellipse and optionally
initialises its attributes.
A Ellipse is a Region which represents a elliptical area within the supplied 2-dimensional Frame.
RESULT = AST_ELLIPSE( FRAME, FORM, CENTRE, POINT1, POINT2, UNC, OPTIONS,
STATUS )
FRAME = INTEGER (Given)
A pointer to the Frame in which the region is
defined. It must have exactly 2 axes. 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.
FORM = INTEGER (Given)
Indicates how the ellipse is described by the remaining parameters. A
value of zero indicates that the ellipse is specified by a centre position and two positions on the
circumference. A value of one indicates that the ellipse is specified by its centre position, the
half-lengths of its two axes, and the orientation of its first axis.
CENTRE( 2 ) = DOUBLE
PRECISION (Given)
An array containing the coordinates at the centre of the ellipse.
POINT1( 2 ) = DOUBLE PRECISION (Given)
If FORM is zero, this array should contain the
coordinates of one of the four points where an axis of the ellipse crosses the circumference of the
ellipse. If FORM is one, it should contain the lengths of semi-major and semi-minor axes
of the ellipse, given as geodesic distances within the Frame.
POINT2( 2 ) = DOUBLE
PRECISION (Given)
If FORM is zero, this array should containing the coordinates at some other
point on the circumference of the ellipse, distinct from POINT1. If FORM is one, the first
element of this array should hold the angle between the second axis of the Frame and the first
ellipse axis (i.e. the ellipse axis which is specified first in the POINT1 array), and the second
element will be ignored. The angle should be given in radians, measured positive in the
same sense as rotation from the positive direction of the second Frame axis to the positive
direction of the first Frame axis.
UNC = INTEGER (Given)
An optional pointer to an
existing Region which specifies the uncertainties associated with the boundary of the Ellipse
being created. The uncertainty in any point on the boundary of the Ellipse 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 Ellipse. Alternatively, a null Object pointer
(AST__NULL) may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6
of the size of the Ellipse being created.
The uncertainty Region has two uses: 1) when the AST_OVERLAP 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
AST_SIMPLIFY), the uncertainties are used to determine if the transformed boundary
can be accurately represented by a specific shape of Region.
OPTIONS = CHARACTER
(
) (Given)
A character string containing an optional comma-separated list of attribute
assignments to be used for initialising the new Ellipse. The syntax used is identical to that for
the
AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.