astCircleastCircle - Create a Circle

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

A Circle is a RegionRegion which represents a circle or sphere within the supplied FrameFrame.

Synopsis:
AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[], const double point[], 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.
form
Indicates how the circle is described by the remaining parameters. A value of zero indicates that the circle is specified by a centre position and a position on the circumference. A value of one indicates that the circle is specified by a centre position and a scalar radius.
centre
An array of double, with one element for each Frame axis (NaxesNaxes attribute) containing the coordinates at the centre of the circle or sphere.
point
If "form" is zero, then this array should have one element for each Frame axis (Naxes attribute), and should be supplied holding the coordinates at a point on the circumference of the circle or sphere. If "form" is one, then this array should have one element only which should be supplied holding the scalar radius of the circle or sphere, as a geodesic distance within the Frame.
unc
An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Circle being created. The uncertainty in any point on the boundary of the Circle 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. BoxBox, Circle, EllipseEllipse, etc.) or be a PrismPrism 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 Circle. Alternatively, a NULL ObjectObject pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Circle being created.

The uncertainty Region has two uses: 1) when the astOverlapastOverlap 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 astSimplifyastSimplify), 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 Circle. The syntax used is identical to that for the astSetastSet 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:
astCircle()
A pointer to the new Circle.
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.