astPlotastPlot - Create a Plot

Description:
This function creates a new PlotPlot and optionally initialises its attributes.

A Plot is a specialised form of FrameSetFrameSet, in which the base FrameFrame describes a "graphical" coordinate system and is associated with a rectangular plotting area in the underlying graphics system. This plotting area is where graphical output appears. It is defined when the Plot is created.

The current Frame of a Plot describes a "physical" coordinate system, which is the coordinate system in which plotting operations are specified. The results of each plotting operation are automatically transformed into graphical coordinates so as to appear in the plotting area (subject to any clipping which may be in effect).

Because the MappingMapping between physical and graphical coordinates may often be non-linear, or even discontinuous, most plotting does not result in simple straight lines. The basic plotting element is therefore not a straight line, but a geodesic curve (see astCurveastCurve). A Plot also provides facilities for drawing markers or symbols (astMarkastMark), text (astTextastText) and grid lines (astGridLineastGridLine). It is also possible to draw curvilinear axes with optional coordinate grids (astGridastGrid). A range of Plot attributes is available to allow precise control over the appearance of graphical output produced by these functions.

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 Plot, using its CurrentCurrent attribute. You may also set up clipping (see astClipastClip) to limit the extent of any plotting you perform, and this may be done in any of the coordinate systems associated with the Plot, not necessarily the one you are plotting in.

Like any FrameSet, a Plot 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 Plot describes the inter-relation between graphical coordinates (its base Frame) and physical coordinates (its current Frame). It differs from a normal FrameSet, however, in that an attempt to transform points which lie in clipped areas of the Plot will result in bad coordinate values (AST__BAD).

Synopsis:
AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ], const double basebox[ 4 ], 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 ObjectObject pointer (AST__NULL) is given, a default 2-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)Labelaxis) for the Plot.

graphbox
An array giving the position and extent of the plotting area (on the plotting surface 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 pair of values should give the coordinates of the bottom left corner of the plotting area and the second pair 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 area, 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 Plot. The syntax used is identical to that for the astSetastSet 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:
astPlot()
A pointer to the new Plot.
Notes:
  • The base Frame of the returned Plot 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 Plot. The choice of base Frame (BaseBase attribute) should not, in general, be changed once a Plot 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 Plot 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 Plot (where their Frame indices are increased by 1), with the FrameSet's current Frame becoming the current Frame of the Plot.

  • If a null Object pointer (AST__NULL) is supplied (via the "frame" pointer), then the returned Plot 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 Plot TitleTitle 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 2-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.