#### Description:

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

A Plot3D is a specialised form of Plot that provides facilities for producing 3D graphical output.

#### Synopsis

AstPlot3D ∗astPlot3D( AstFrame ∗frame, const float graphbox[ 6 ], const double basebox[ 6 ], const char ∗options, ... )

#### Parameters:

##### frame

Pointer to a Frame describing the physical coordinate system in which to plot. A pointer to a FrameSet may also be given, in which case its current Frame will be used to define the physical coordinate system and its base Frame will be mapped on to graphical coordinates (see below).

If a null Object pointer (AST__NULL) is given, a default 3-dimensional Frame will be used to describe the physical coordinate system. Labels, etc. may then be attached to this by setting the appropriate Frame attributes (e.g. Label(axis)) for the Plot.

##### graphbox

An array giving the position and extent of the plotting volume (within the plotting space of the underlying graphics system) in which graphical output is to appear. This must be specified using graphical coordinates appropriate to the underlying graphics system.

The first triple of values should give the coordinates of the bottom left corner of the plotting volume and the second triple should give the coordinates of the top right corner. The coordinate on the horizontal axis should be given first in each pair. Note that the order in which these points are given is important because it defines up, down, left and right for subsequent graphical operations.

##### basebox

An array giving the coordinates of two points in the supplied Frame (or in the base Frame if a FrameSet was supplied) which correspond to the bottom left and top right corners of the plotting volume, as specified above. This range of coordinates will be mapped linearly on to the plotting area. The coordinates should be given in the same order as above.

##### options

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

##### astPlot3D()

A pointer to the new Plot3D.

#### Notes:

- The base Frame of the returned Plot3D will be a new Frame which is created by this function to represent the coordinate system of the underlying graphics system (graphical coordinates). It is given a Frame index of 1 within the Plot3D. The choice of base Frame (Base attribute) should not, in general, be changed once a Plot3D has been created (although you could use this as a way of moving the plotting area around on the plotting surface).

- If a Frame is supplied (via the `"` frame`"` pointer), then it becomes the current Frame of the new Plot3D and is given a Frame index of 2.

- If a FrameSet is supplied (via the `"` frame`"` pointer), then all the Frames within this FrameSet become part of the new Plot3D (where their Frame indices are increased by 1), with the FrameSet`’` s current Frame becoming the current Frame of the Plot3D.

- At least one of the three axes of the current Frame must be independent of the other two current Frame axes.

- If a null Object pointer (AST__NULL) is supplied (via the `"` frame`"` pointer), then the returned Plot3D will contain two Frames, both created by this function. The base Frame will describe graphics coordinates (as above) and the current Frame will be a basic Frame with no attributes set (this will therefore give default values for such things as the Plot3D Title and the Label on each axis). Physical coordinates will be mapped linearly on to graphical coordinates.

- An error will result if the Frame supplied (or the base Frame if a FrameSet was supplied) is not 3-dimensional.

- 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