#### Description:

This function creates a new Frame and optionally initialises its attributes.

A Frame is used to represent a coordinate system. It does this in rather the same way that a frame around a graph describes the coordinate space in which data are plotted. Consequently, a Frame has a Title (string) attribute, which describes the coordinate space, and contains axes which in turn hold information such as Label and Units strings which are used for labelling (e.g.) graphical output. In general, however, the number of axes is not restricted to two.

Functions are available for converting Frame coordinate values into a form suitable for display, and also for calculating distances and offsets between positions within the Frame.

Frames may also contain knowledge of how to transform to and from related coordinate systems.

#### Synopsis

AstFrame ∗astFrame( int naxes, const char ∗options, ... )

#### Parameters:

##### naxes

The number of Frame axes (i.e. the number of dimensions of the coordinate space which the Frame describes).

##### options

Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Frame. 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 no initialisation is required, a zero-length string may be supplied.

##### ...

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

##### astFrame()

A pointer to the new Frame.

#### Examples:

frame = astFrame( 2, `"` Title=Energy Spectrum: Plot %d`"` , n );

  Creates a new 2-dimensional Frame and initialises its Title attribute to the string `"` Energy Spectrum: Plot <n >`"` , where <n > takes the value of the int variable `"` n`"` .

frame = astFrame( 2, `"` Label(1)=Energy, Label(2)=Response`"` );

  Creates a new 2-dimensional Frame and initialises its axis Label attributes to suitable string values.

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

Copyright (C) 2021 East Asian Observatory