next up previous 264
Next: AST_POINTLIST - Create a PointList
Up: AST Routine Descriptions
Previous: AST_PLOT - Create a Plot


AST_PLOT3D - Create a Plot3D

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.

Invocation:
RESULT = AST_PLOT3D( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS )
Arguments:
FRAME = INTEGER (Given)
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( 6 ) = REAL (Given)
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( 6 ) = DOUBLE PRECISION (Given)
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 = CHARACTER $*$ ( $*$ ) (Given)
A character 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 AST_SET routine. If no initialisation is required, a blank value may be supplied.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_PLOT3D = INTEGER
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.

  • 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 STATUS set to an error value, or if it should fail for any reason.


next up previous 264
Next: AST_POINTLIST - Create a PointList
Up: AST Routine Descriptions
Previous: AST_PLOT - Create a Plot

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council