The PLplot Plotting Library

Programmer's Reference Manual

Maurice J. LeBrun

Geoff Furnish

University of Texas at Austin
Institute for Fusion Studies

The PLplot Plotting Library

Redistribution and use in source (XML DocBook) and "compiled" forms (HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.

  2. Redistributions in compiled form (transformed to other DTDs, converted to HTML, PDF, PostScript, and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Release version: 5.9.4

Release date: 2009-05-10


Table of Contents
I. Introduction
1. Introduction
The PLplot Plotting Library
Getting a Copy of the PLplot Package
Installing and Using the PLplot Library
Organization of this Manual
Copyrights
Credits
II. Programming
2. Simple Use of PLplot
Plotting a Simple Graph
Initializing PLplot
Defining Plot Scales and Axes
Labeling the Graph
Drawing the Graph
Finishing Up
In Case of Error
3. Advanced Use of PLplot
Command Line Arguments
Output Devices
Adding FreeType Library Support to Bitmap Drivers
View Surfaces, (Sub-)Pages, Viewports and Windows
Setting Line Attributes
Setting the Area Fill Pattern
Setting Color
Setting Character Attributes
Three Dimensional Surface Plots
Contour and Shade Plots
4. Deploying programs that use PLplot
5. The PLplot Display Driver Family
The Xwin Driver (X-Windows)
The GCW Driver (Gnome 2)
The Tk Driver
The AquaTerm Driver (Mac OS X)
The wxWidgets Driver (Linux, Mac OS X, Windows)
6. The PLplot Output Driver Family
The GD Driver
The PDF Driver
The PostScript Driver
The TrueType PostScript Driver
The LaTeX PostScript Driver
The SVG Driver
III. Language Bindings
7. Ada Language
Overview
The Bindings
The Examples
Obtaining the Software
How to use the Ada bindings
Unique Features of the Ada bindings
Parts That Retain a C Flavor
Known Variances
Compilation notes
Notes for Apple Macintosh OS X users
8. C Language
9. A C++ Interface for PLplot
Motivation for the C++ Interface
Design of the PLplot C++ Interface
Specializing the PLplot C++ Interface
Status of the C++ Interface
10. Fortran 77 Language
11. Fortran 95 Language
12. OCaml Language
Overview
The Bindings
The Examples
Obtaining the Software
How to use the OCaml bindings
Known Issues
13. Using PLplot from Perl
14. Using PLplot from Python
15. Using PLplot from Tcl
Motivation for the Tcl Interface to PLplot
Overview of the Tcl Language Binding
The PLplot Tcl Matrix Extension
Contouring and Shading from Tcl
Understanding the Performance Characteristics of Tcl
16. Building an Extended WISH
Introduction to Tcl
Introduction to Tk
Introduction to [incr Tcl]
PLplot Extensions to Tcl
Custom Extensions to Tcl
17. Embedding Plots in Graphical User Interfaces
The PlplotCanvas Widget for Gnome/GTK Applications
IV. Reference
18. Bibliography
References
19. The Common API for PLplot
pl_setcontlabelformat: Set format of numerical label for contours
pl_setcontlabelparam: Set parameters of contour labelling other than format of numerical label
pladv: Advance the (sub-)page
plaxes: Draw a box with axes, etc. with arbitrary origin
plbin: Plot a histogram from binned data
plbop: Begin a new page
plbox: Draw a box with axes, etc
plbox3: Draw a box with axes, etc, in 3-d
plcalc_world: Calculate world coordinates and corresponding window index from relative device coordinates
plclear: Clear current (sub)page
plcol0: Set color, map0
plcol1: Set color, map1
plcont: Contour plot
plcpstrm: Copy state parameters from the reference stream to the current stream
plend: End plotting session
plend1: End plotting session for current stream
plenv0: Same as plenv but if in multiplot mode does not advance the subpage, instead clears it.
plenv: Set up standard window and draw box
pleop: Eject current page
plerrx: Draw x error bar
plerry: Draw y error bar
plfamadv: Advance to the next family file on the next new page
plfill: Draw filled polygon
plfill3: Draw filled polygon in 3D
plflush: Flushes the output stream
plfont: Set character font
plfontld: Load character font
plgchr: Get character default height and current (scaled) height
plgcol0: Returns 8-bit RGB values for given color from color map0
plgcol0a: Returns 8-bit RGB values and double alpha value for given color from color map0.
plgcolbg: Returns the background color (cmap0[0]) by 8-bit RGB value
plgcolbga: Returns the background color (cmap0[0]) by 8-bit RGB value and double alpha value.
plgcompression: Get the current device-compression setting
plgdev: Get the current device (keyword) name
plgdidev: Get parameters that define current device-space window
plgdiori: Get plot orientation
plgdiplt: Get parameters that define current plot-space window
plgfam: Get family file parameters
plgfci: Get FCI (font characterization integer)
plgfnam: Get output file name
plgfont: Get family, style and weight of the current font
plglevel: Get the (current) run level
plgpage: Get page parameters
plgra: Switch to graphics screen
plgriddata: Grid data from irregularly sampled data
plgspa: Get current subpage parameters
plgstrm: Get current stream number
plgver: Get the current library version number
plgvpd: Get viewport limits in normalized device coordinates
plgvpw: Get viewport limits in world coordinates
plgxax: Get x axis parameters
plgyax: Get y axis parameters
plgzax: Get z axis parameters
plhist: Plot a histogram from unbinned data
plhlsrgb: Convert HLS color to RGB
plimagefr: Plot a 2D matrix using color map1
plimage: Plot a 2D matrix using color map1 with automatic colour adjustment
plinit: Initialize PLplot
pljoin: Draw a line between two points
pllab: Simple routine to write labels
pllightsource: Sets the 3D position of the light source
plline: Draw a line
plline3: Draw a line in 3 space
pllsty: Select line style
plmap: Plot continental outline in world coordinates.
plmeridians: Plot latitude and longitude lines.
plmesh: Plot surface mesh
plmeshc: Magnitude colored plot surface mesh with contour.
plmkstrm: Creates a new stream and makes it the default
plmtex: Write text relative to viewport boundaries
plmtex3: Write text relative to viewport boundaries in 3D plots.
plot3d: Plot 3-d surface plot
plot3dc: Magnitude colored plot surface with contour.
plparseopts: Parse command-line arguments
plpat: Set area fill pattern
plpoin: Plots a character at the specified points
plpoin3: Plots a character at the specified points in 3 space
plpoly3: Draw a polygon in 3 space
plprec: Set precision in numeric labels
plpsty: Select area fill pattern
plptex: Write text inside the viewport
plptex3: Write text inside the viewport of a 3D plot.
plrandd: Random number generator returning a real random number in the range [0,1].
plreplot: Replays contents of plot buffer to current device/file
plrgbhls: Convert RGB color to HLS
plschr: Set character size
plscmap0: Set color map0 colors by 8-bit RGB values
plscmap0a: Set color map0 colors by 8-bit RGB values and double alpha value.
plscmap0n: Set number of colors in color map0
plscmap1: Set color map1 colors using 8-bit RGB values
plscmap1a: Set color map1 colors using 8-bit RGB values and double alpha values.
plscmap1l: Set color map1 colors using a piece-wise linear relationship
plscmap1la: Set color map1 colors using a piece-wise linear relationship
plscmap1n: Set number of colors in color map1
plscol0: Set a given color from color map0 by 8 bit RGB value
plscol0a: Set a given color from color map0 by 8 bit RGB value and double alpha value.
plscolbg: Set the background color by 8-bit RGB value
plscolbga: Set the background color by 8-bit RGB value and double alpha value.
plscolor: Used to globally turn color output on/off
plscompression: Set device-compression level
plsdev: Set the device (keyword) name
plsdidev: Set parameters that define current device-space window
plsdimap: Set up transformation from metafile coordinates
plsdiori: Set plot orientation
plsdiplt: Set parameters that define current plot-space window
plsdiplz: Set parameters incrementally (zoom mode) that define current plot-space window
plseed: Set seed for internal random number generator.
plsesc: Set the escape character for text strings
plsetopt: Set any command-line option
plsfam: Set family file parameters
plsfci: Set FCI (font characterization integer)
plsfnam: Set output file name
plsfont: Set family, style and weight of the current font
plshades: Shade regions on the basis of value
plshade: Shade individual region on the basis of value
plshade1: Shade individual region on the basis of value
plsmaj: Set length of major ticks
plsmem: Set the memory area to be plotted
plsmin: Set length of minor ticks
plsori: Set orientation
plspage: Set page parameters
plspause: Set the pause (on end-of-page) status
plsstrm: Set current output stream
plssub: Set the number of subpages in x and y
plssym: Set symbol size
plstar: Initialization
plstart: Initialization
plstripa: Add a point to a stripchart
plstripc: Create a 4-pen stripchart
plstripd: Deletes and releases memory used by a stripchart
plstyl: Set line style
plsurf3d: Plot shaded 3-d surface plot
plsvect: Set arrow style for vector plots
plsvpa: Specify viewport in absolute coordinates
plsxax: Set x axis parameters
plsyax: Set y axis parameters
plsym: Plots a symbol at the specified points
plszax: Set z axis parameters
pltext: Switch to text screen
pltimefmt: Set format for date / time labels
plvasp: Specify viewport using aspect ratio only
plvect: Vector plot
plvpas: Specify viewport using coordinates and aspect ratio
plvpor: Specify viewport using coordinates
plvsta: Select standard viewport
plw3d: Set up window for 3-d plotting
plwid: Set pen width
plwind: Specify world coordinates of viewport boundaries
plxormod: Enter or leave xor mode
20. The Specialized C API for PLplot
plabort: Error abort
plAlloc2dGrid: Allocate a block of memory for use as a 2-d grid of type PLFLT.
plClearOpts: Clear internal option table info structure.
plexit: Error exit
plFree2dGrid: Free the memory associated with a 2-d grid allocated using plAlloc2dGrid.
plGetCursor: Wait for graphics input event and translate to world coordinates.
plgfile: Get output file handle
plMergeOpts: Merge use option table into internal info structure.
plMinMax2dGrid: Find the minimum and maximum of a 2d grid allocated using plAlloc2dGrid.
plOptUsage: Print usage and syntax message.
plMergeOpts: Reset internal option table info structure.
plsabort: Set abort handler
plSetUsage: Set the strings used in usage and syntax messages.
plsexit: Set exit handler
plsfile: Set output file handle
pltr0: Identity transformation for grid to world mapping
pltr1: Linear interpolation for grid to world mapping using singly dimensioned coord arrays
pltr2: Linear interpolation for grid to world mapping using doubly dimensioned coord arrays (column dominant, as per normal C 2d arrays)
PLGraphicsIn: PLplot Graphics Input structure
PLOptionTable: PLplot command line options table structure
21. The Specialized Fortran 95 API for PLplot
plcont: Contour plot for Fortran 95
plshade: Shaded plot for Fortran 95
plshades: Continuously shaded plot for Fortran 95
plvect: Vector plot for Fortran 95
plmesh: Plot surface mesh for Fortran 95
plot3d: Plot 3-d surface plot for Fortran 95
plparseopts: parse arguments for Fortran 95
plsesc: Set the escape character for text strings for Fortran 95
22. The Specialized Fortran 77 API for PLplot
plcon0: Contour plot, identity mapping for Fortran 77
plcon1: Contour plot, general 1-d mapping for Fortran 77
plcon2: Contour plot, general 2-d mapping for Fortran 77
plcont: Contour plot, fixed linear mapping for Fortran 77
plvec0: Vector plot, identity mapping for Fortran 77
plvec1: Vector plot, general 1-d mapping for Fortran 77
plvec2: Vector plot, general 2-d mapping for Fortran 77
plvect: Vector plot, fixed linear mapping for Fortran 77
plmesh: Plot surface mesh for Fortran 77
plot3d: Plot 3-d surface plot for Fortran 77
plparseopts: parse arguments for Fortran 77
plsesc: Set the escape character for text strings for Fortran 77
23. API compatibility definition
What is in the API?
Regression test for backwards compatibility
24. Obsolete/Deprecated API for PLplot
plclr: Eject current page
plcol: Set color
plhls: Set current color by HLS
plHLS_RGB: Convert HLS color to RGB
plpage: Begin a new page
plrgb: Set line color by red, green
plrgb1: Set line color by 8-bit RGB values
25. Internal C functions in PLplot
plP_checkdriverinit: Checks to see if any of the specified drivers have been initialized
plP_getinitdriverlist: Get the initialized-driver list
26. Notes for each Operating System that We Support
Linux/Unix Notes
Windows Notes
DJGPP Notes
27. The PLplot Libraries
Bindings Libraries
The PLplot Core Library
Enhancement Libraries
Device-driver Libraries
List of Tables
3-1. PLplot Terminal Output Devices
3-2. PLplot File Output Devices
3-3. FCI interpretation
3-4. Roman Characters Corresponding to Greek Characters
19-1. Bounds on coordinates
27-1. Bindings Libraries