astMoc

Create a Moc

Description:

This function creates a new Moc object and optionally initialises its attributes.

The Moc class uses the IVOA MOC (Multi-Order Coverage) recommendation to describe a region on the sky. The region is made up of an arbitrary collection of cells from the HEALPix sky tessellation, and thus may represent any area on the sky, subject to the constraint that the edges of the area correspond to edges of the HEALPix cells. See the MOC recommendation for further information (http://www.ivoa.net/documents/MOC/).

As a description of a region on the sky, the Moc class can be seen as an alternative to the Region class. Note, Mocs and Regions are not interchangable (that is, a Moc is not a subclass of Region and therefore Region methods cannot be applied to Mocs). The Moc class is intended to describe an arbitrary collection of cells on the sky, whereas the Region classes describe exact geometric shapes. The Moc class has a method that allow a Region to be converted into an approximating Moc, but Mocs cannot be converted into Regions.

The MOC recommendation requires that a MOC always describes a sky area using the ICRS coordinate system. However, the Moc class allows its attributes to be changed so that it represents any celestial coordinate system that can be mapped to ICRS. Note, changing the System attribute will not change the area on the sky covered by the Moc - it will just change the way that area is described. For instance, if a Moc is created that covers a particular galaxy in ICRS, and the System attriubute is then changed to Galactic, the Moc will still cover the same galaxy, but it will now be described in Galactic coordinates rather than ICRS. When a Moc is written out through a FitsChan, FITS headers describing the Moc will be stored in the FitsChan. The binary data for the single column of the coresponding FITS binary table can be retrieved from the Moc using method astGetMocData.

In practice, to use this class an empty Moc object (i.e. a Moc describing a null area of the sky) should first be created using the astMoc constructor. Areas of the sky should then be added into the empty Moc using one or more of the class methods.

Synopsis

AstMoc astMoc( const char options, ... )

Parameters:

maxorder
options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Moc. 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 parameters 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

astMoc()
A pointer to the new Moc.

Notes:

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