astEllipse - Create a Ellipse

**Description:****Synopsis:**`AstEllipse astEllipse( AstFrame frame, int form, const double centre[2], const double point1[2], const double point2[2], AstRegion unc, const char options, ... )`

**Parameters:****frame**- 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**- 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**- An array of 2 doubles, containing the coordinates at the centre of the ellipse.
**point1**-
An array of 2 doubles. 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**-
An array of 2 doubles. 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**-
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 Ellipse. 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:****astEllipse()**- A pointer to the new Ellipse.

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

Starlink User Note 211

R.F. Warren-Smith & D.S. Berry

7th December 2012

E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council