The PLplot Plotting Library

Programmer's Reference Manual

Maurice J. LeBrun

Geoff Furnish

University of Texas at Austin
Institute for Fusion Studies

Version 5.10.0

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.10.0

Release date: 2014-02-12

Abstract

The PLplot Plotting Library


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
Additional Copyrights
Credits
II. Programming
2. Simple Use of PLplot
Plotting a Simple Graph
Initializing PLplot
Defining Plot Scales and Axes
Labelling the Graph
Drawing the Graph
Drawing Points
Drawing Lines or Curves
Writing Text on a Graph
Area Fills
More Complex Graphs
Finishing Up
In Case of Error
3. Advanced Use of PLplot
Command Line Arguments
Output Devices
Driver Functions
PLplot Metafiles and Plrender
Family File Output
Interactive Output Devices
Specifying the Output Device
Adding FreeType Library Support to Bitmap Drivers
Write a call back function to plot a single pixel
Initialize FreeType
Add A Command to redraw text (interactive drivers only)
Add Function Prototypes
Add Closing functions
View Surfaces, (Sub-)Pages, Viewports and Windows
Defining the Viewport
Defining the Window
Annotating the Viewport
Setting up a Standard Window
Setting Line Attributes
Setting the Area Fill Pattern
Setting Color
Color Map0
Color Map1
Setting Character Attributes
Hershey fonts
Unicode fonts
FCI
Escape sequences in text
Character size adjustment
Three Dimensional Surface Plots
Contour and Shade Plots
Contour Plots from C
Shade Plots from C
Contour Plots from the Fortran 95 interface
Shade Plots from the Fortran 95 interface
Legends and color bars
4. Deploying programs that use PLplot
5. The PLplot Display Driver Family
The Xwin Driver (X-Windows)
The Tk Driver
The AquaTerm Driver (Mac OS X)
The wxWidgets Driver (Linux, Mac OS X, Windows)
wxWidgets Driver Basics
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
Thin Binding
The Thick Bindings
Standard Thick Binding Using Enhanced Names
Thick Binding Using Traditional Names
The Examples
Obtaining the Software
Obtaining an Ada compiler
Download and install PLplot
The Ada bindings to PLplot
How to use the Ada bindings
Ada 95 versus Ada 2005
GNAT versus non-GNAT
Sample command line project
Unique Features of the Ada bindings
High-level features for simplified plotting
Integer Options Given Ada Names
One-offs
Parts That Retain a C Flavor
Map-drawing
Known Variances
Documentation
API
Compilation notes
Ada 95 Versus Ada 2005
GNAT Dependence
PLplot_Auxiliary
Notes for Apple Macintosh OS X users
Using Apple's Xcode IDE
AquaTerm
X11
GNAT for OS X
8. C Language
9. A C++ Interface for PLplot
Motivation for the C++ Interface
Design of the PLplot C++ Interface
Stream/Object Identity
Namespace Management
Abstraction of Data Layout
Collapsing the API
Specializing the PLplot C++ Interface
Status of the C++ Interface
10. Fortran 95 Language
11. OCaml Language
Overview
The Bindings
Core Binding
OCaml-specific variations to the core PLplot API
OCaml high level 2D plotting API
The Examples
Obtaining the Software
Obtaining the OCaml compiler
How to use the OCaml bindings
How to setup findlib for use with the OCaml bindings
Sample command line project (core API)
Sample command line project (OCaml-specific API)
Sample toplevel project
Known Issues
12. Using PLplot from Perl
13. Using PLplot from Python
14. Using PLplot from Tcl
Motivation for the Tcl Interface to PLplot
Overview of the Tcl Language Binding
The PLplot Tcl Matrix Extension
Using Tcl Matrices from Tcl
Using Tcl Matrices from C
Using Tcl Matrices from C++
Extending the Tcl Matrix facility
Contouring and Shading from Tcl
Drawing a Contour Plot from Tcl
Drawing a Shaded Plot from Tcl
Understanding the Performance Characteristics of Tcl
15. Building an Extended WISH
Introduction to Tcl
Motivation for Tcl
Capabilities of Tcl
Acquiring Tcl
Introduction to Tk
Introduction to [incr Tcl]
PLplot Extensions to Tcl
Custom Extensions to Tcl
WISH Construction
WISH Linking
WISH Programming
16. Embedding Plots in Graphical User Interfaces
IV. Reference
17. Bibliography
References
18. 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
plarc: Draw a circular or elliptical arc
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
plbtime: Calculate broken-down time from continuous time for the current stream
plcalc_world: Calculate world coordinates and corresponding window index from relative device coordinates
plclear: Clear current (sub)page
plcol0: Set color, cmap0
plcol1: Set color, cmap1
plcolorbar: Plot color bar for image, shade or gradient plots
plconfigtime: Configure the transformation between continuous and broken-down time for the current stream
plcont: Contour plot
plcpstrm: Copy state parameters from the reference stream to the current stream
plctime: Calculate continuous time from broken-down time for 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
plgcmap1_range: Get the cmap1 argument range for continuous color plots
plgcol0: Returns 8-bit RGB values for given color index from cmap0
plgcol0a: Returns 8-bit RGB values and double alpha transparency value for given color index from cmap0
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 transparency 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
plgdrawmode: Get drawing mode (depends on device support!)
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
plgradient: Draw linear gradient inside polygon
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 cmap1
plimage: Plot a 2D matrix using cmap1 with automatic colour adjustment
plinit: Initialize PLplot
pljoin: Draw a line between two points
pllab: Simple routine to write labels
pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols
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
plot3dcl: Magnitude colored plot surface with contour for z[x][y] with y index limits
plparseopts: Parse command-line arguments
plpat: Set area fill pattern
plpath: Draw a line between two points, accounting for coordinate transforms
plpoin: Plot a glyph at the specified points
plpoin3: Plot a glyph at the specified 3D points
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 cmap0 colors by 8-bit RGB values
plscmap0a: Set cmap0 colors by 8-bit RGB values and double alpha transparency value
plscmap0n: Set number of colors in cmap0
plscmap1_range: Set the cmap1 argument range for continuous color plots
plscmap1: Set cmap1 colors using 8-bit RGB values
plscmap1a: Set cmap1 colors using 8-bit RGB values and double alpha transparency values
plscmap1l: Set cmap1 colors using a piece-wise linear relationship
plscmap1la: Set cmap1 colors and alpha transparency using a piece-wise linear relationship
plscmap1n: Set number of colors in cmap1
plscol0: Set 8-bit RGB values for given cmap0 color index
plscol0a: Set 8-bit RGB values and double alpha transparency value for given cmap0 color index
plscolbg: Set the background color by 8-bit RGB value
plscolbga: Set the background color by 8-bit RGB value and double alpha transparency 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
plsdrawmode: Set drawing mode (depends on device support!)
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
plslabelfunc: Assign a function to use for generating custom axis labels
plsmaj: Set length of major ticks
plsmem: Set the memory area to be plotted (RGB)
plsmema: Set the memory area to be plotted (RGBA)
plsmin: Set length of minor ticks
plsori: Set orientation
plspage: Set page parameters
plspal0: Set the colors for color table 0 from a cmap0 file
plspal1: Set the palette for cmap1 using the specified cmap1*.pal format file
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
plstransform: Set a global coordinate transform function
plstring: Plot a glyph at the specified points
plstring3: Plot a glyph at the specified 3D points
plstripa: Add a point to a strip chart
plstripc: Create a 4-pen strip chart
plstripd: Deletes and releases memory used by a strip chart
plstyl: Set line style
plsurf3d: Plot shaded 3-d surface plot
plsurf3dl: Plot shaded 3-d surface plot for z[x][y] with y index limits
plfsurf3d: 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: Plot a glyph 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
plwidth: Set pen width
plwind: Specify world coordinates of viewport boundaries
plxormod: Enter or leave xor mode
19. 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 coordinate arrays
pltr2: Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (column dominant, as per normal C 2d arrays)
PLGraphicsIn: PLplot Graphics Input structure
PLOptionTable: PLplot command line options table structure
20. 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
21. API compatibility definition
What is in the API?
Regression test for backwards compatibility
22. 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
plwid: Set pen width
23. 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
24. Notes for each Operating System that We Support
Linux/Unix Notes
Linux/Unix Configure, Build, and Installation
Linux/Unix Building of C Programmes that Use the Installed PLplot Libraries
Windows Notes
Windows Configure and Build
25. The PLplot Libraries
Bindings Libraries
The PLplot Core Library
Enhancement Libraries
The CSIRO Cubic Spline Approximation Library
The CSIRO Natural Neighbours Interpolation Library
The QSAS Time Format Conversion Library
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
3.5. The word "peace" expressed in several different languages in example 24 using UTF-8
18.1. Examples of interpolation
18.2. Bounds on coordinates
25.1. Bindings Libraries