A Plot3D is a specialised form of Plot that provides facilities for producing 3D graphical output, including fully annotated 3D coordinate grids. The base Frame in a Plot3D describes a 3-dimensional " graphical" coordinate system. The axes of this coordinate system are assumed to be right-handed (that is, if X appears horizontally to the right and Y vertically upwards, then Z is out of the screen towards the viewer), and are assumed to be equally scaled (that is, the same units are used to measure positions on each of the 3 axes). The upper and lower bounds of a volume within this graphical coordinate system is specified when the Plot3D is created, and all subsequent graphics are " drawn" in this volume.

The Plot3D class does not itself include any ability to draw on a graphics device. Instead it calls upon function in an externally supplied module (the " grf3d" module) to do the required drawing. A module should be written that implements the functions of the grf3d interface using the facilities of a specific graphics system This module should then be linked into the application so that the Plot3D class can use its functions (see the description of the ast_link commands for details of how to do this). The grf3d interface defines a few simple functions for drawing primitives such as straight lines, markers and character strings. These functions all accept positions in the 3D graphics coordinate system (the base Frame of the Plot3D), and so the grf3d module must also manage the projection of these 3D coordinates onto the 2D viewing surface, including the choice of " eye" /" camera" position, direction of viewing, etc. The AST library includes a sample implementation of the grf3d interface based on the PGPLOT graphics system (see file grf3d_pgplot.c). This implementation also serves to document the grf3d interface itself and should be consulted for details before writing a new implementation.

The current Frame of a Plot3D describes a " physical" 3-dimensional coordinate system, which is the coordinate system in which plotting operations are specified when invoking the methods of the Plot3D class. The results of each plotting operation are automatically transformed into 3D graphical coordinates before being plotted using the facilities of the grf3d module linked into the application. Note, at least one of the three axes of the current Frame must be independent of the other two current Frame axes.

You may select different physical coordinate systems in which to plot (including the native graphical coordinate system itself) by selecting different Frames as the current Frame of a Plot3D, using its Current attribute.

Like any FrameSet, a Plot3D may also be used as a Frame. In this case, it behaves like its current Frame, which describes the physical coordinate system.

When used as a Mapping, a Plot3D describes the inter-relation between 3D graphical coordinates (its base Frame) and 3D physical coordinates (its current Frame).

Although the Plot3D class inherits from the Plot class, several of the facilities of the Plot class are not available in the Plot3D class, and an error will be reported if any attempt is made to use them. Specifically, the Plot3D class does not support clipping using the astClip function. AST_CLIP routine. Nor does it support the specification of graphics primitive functions at run-time using the AST_GRFSET, AST_GRFPOP, AST_GRFPUSH, and AST_GETGRFCONTEXT routines.

AST_PLOT3D

The Plot3D class inherits from the Plot class.

In addition to those attributes common to all Plots, every Plot3D also has the following attributes:

• Norm: Normal vector defining the 2D plane used for text and markers

• RootCorner: Specifies which edges of the 3D box should be annotated.

Some attributes of the Plot class refer to specific physical coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic Plot, the axis index must be 1 or 2, but for a Plot3D the axis index can be 1, 2 or 3.

Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, DrawTitle, TitleGap, etc). Consult the Plot attribute documentation for details. All other Plot attributes can be set for a specific plane of the 3-d plot by appending one of the strings " _XY" , " _XZ" or " _YZ" to the end of the Plot attribute name. For instance, "Grid_YZ" refers to the " Grid" attribute for the plane spanning the second (Y) and third (Z) axes of the 3-d plot.

The Plot3D class does not define any new routines beyond those which are applicable to all Plots. Note, however, that the following methods inherited from the Plot class cannot be used with a Plot3D and will report an error if called:

• AST_BOUNDINGBOX, AST_CLIP, AST_CURVE, AST_GENCURVE, AST_GETGRFCONTEXT, AST_GRFPOP, AST_GRFPUSH, AST_GRFSET, AST_GRIDLINE, AST_POLYCURVE.