This is plplotdoc.info, produced by makeinfo version 7.3 from
plplotdoc.texi.

INFO-DIR-SECTION Scientific Visualization
START-INFO-DIR-ENTRY
* Documentation of the PLplot plotting software: (plplotdoc).
                                                  This reference contains
                                                  complete user documentation
                                                  for the PLplot plotting
                                                  software
END-INFO-DIR-ENTRY


File: plplotdoc.info,  Node: Building an Extended WISH,  Next: Embedding Plots in Graphical User Interfaces,  Prev: Using PLplot from Tcl,  Up: Supported computer languages

14 Building an Extended WISH
****************************

Beginning with PLplot 5.0, a new and powerful paradigm for interaction
with PLplot is introduced.  This new paradigm consists of an integration
of PLplot with a powerful scripting language (Tcl), and extensions to
that language to support X Windows interface development (Tk) and object
oriented programming ([incr Tcl]).  Taken together, these four software
systems (Tcl/Tk/itcl/PLplot) comprise a powerful environment for the
rapid prototyping and development of sophisticated, flexible, X Windows
applications with access to the PLplot API. Yet that is only the
beginning--Tcl was born to be extended.  The true power of this paradigm
is achieved when you add your own, powerful, application specific
extensions to the above quartet, thus creating an environment for the
development of wholly new applications with only a few keystrokes of
shell programming ...

* Menu:

* Introduction to Tcl::
* Introduction to Tk::
* Introduction to [incr Tcl]::
* PLplot Extensions to Tcl::
* Custom Extensions to Tcl::


File: plplotdoc.info,  Node: Introduction to Tcl,  Next: Introduction to Tk,  Up: Building an Extended WISH

14.1 Introduction to Tcl
========================

The Tool Command Language, or just Tcl (pronounced ‘tickle’) is an
embeddable script language which can be used to control a wide variety
of applications.  Designed by John Ousterhout of UC Berkeley, Tcl is
freely available under the standard Berkeley copyright.  Tcl and Tk
(described below) are extensively documented in a new book published by
Addison Wesley, entitled ‘Tcl and the Tk toolkit’ by John Ousterhout.
This book is a must have for those interested in developing powerful
extensible applications with high quality X Windows user interfaces.
The discussion in this chapter cannot hope to approach the level of
introduction provided by that book.  Rather we will concentrate on
trying to convey some of the excitement, and show the nuts and bolts of
using Tcl and some extensions to provide a powerful and flexible
interface to the PLplot library within your application.

* Menu:

* Motivation for Tcl::
* Capabilities of Tcl::
* Acquiring Tcl::


File: plplotdoc.info,  Node: Motivation for Tcl,  Next: Capabilities of Tcl,  Up: Introduction to Tcl

14.1.1 Motivation for Tcl
-------------------------

The central observation which led Ousterhout to create Tcl was the
realization that many applications require the use of some sort of a
special purpose, application specific, embedded ‘macro language’.
Application programmers cobble these ‘tiny languages’ into their codes
in order to provide flexibility and some modicum of high level control.
But the end result is frequently a quirky and fragile language.  And
each application has a different ‘tiny language’ associated with it.
The idea behind Tcl, then, was to create a single ‘core language’ which
could be easily embedded into a wide variety of applications.  Further,
it should be easily extensible so that individual applications can
easily provide application specific capabilities available in the macro
language itself, while still providing a robust, uniform syntax across a
variety of applications.  To say that Tcl satisfies these requirements
would be a spectacular understatement.


File: plplotdoc.info,  Node: Capabilities of Tcl,  Next: Acquiring Tcl,  Prev: Motivation for Tcl,  Up: Introduction to Tcl

14.1.2 Capabilities of Tcl
--------------------------

The mechanics of using Tcl are very straightforward.  Basically you just
have to include the file ‘tcl.h’, issue some API calls to create a Tcl
interpreter, and then evaluate a script file or perform other operations
supported by the Tcl API. Then just link against ‘libtcl.a’ and off you
go.

   Having done this, you have essentially created a shell.  That is,
your program can now execute shell scripts in the Tcl language.  Tcl
provides support for basic control flow, variable substitution file i/o
and subroutines.  In addition to the built in Tcl commands, you can
define your own subroutines as Tcl procedures which effectively become
new keywords.

   But the real power of this approach is to add new commands to the
interpreter which are realized by compiled C code in your application.
Tcl provides a straightforward API call which allows you to register a
function in your code to be called whenever the interpreter comes across
a specific keyword of your choosing in the shell scripts it executes.

   This facility allows you with tremendous ease, to endow your
application with a powerful, robust and full featured macro language,
trivially extend that macro language with new keywords which trigger
execution of compiled application specific commands, and thereby raise
the level of interaction with your code to one of essentially shell
programming via script editing.


File: plplotdoc.info,  Node: Acquiring Tcl,  Prev: Capabilities of Tcl,  Up: Introduction to Tcl

14.1.3 Acquiring Tcl
--------------------

There are several important sources of info and code for Tcl.
Definitely get the book mentioned above, and the source code for the Tcl
and Tk toolkits can be downloaded from The Tcl developer Xchange
(http://www.tcl.tk/software/tcltk/download.html).

   Additionally there is a newsgroup, ‘comp.lang.tcl’ which is well
read, and an excellent place for people to get oriented, find help, etc.
Highly recommended.

   In any event, in order to use the Tk driver in PLplot, you will need
Tcl-8.2 and Tk-8.2 (or higher versions).  Additionally, in order to use
the extended WISH paradigm (described below) you will need iTcl-3.1 (or
a higher version).

   However, you will quite likely find Tcl/Tk to be very addictive, and
the great plethora of add-ons available at ‘harbor’ will undoubtedly
attract no small amount of your attention.  It has been our experience
that all of these extensions fit together very well.  You will find that
there are large sectors of the Tcl user community which create so-called
‘MegaWishes’ which combine many of the available extensions into a
single, heavily embellished, shell interpreter.  The benefits of this
approach will become apparent as you gain experience with Tcl and Tk.


File: plplotdoc.info,  Node: Introduction to Tk,  Next: Introduction to [incr Tcl],  Prev: Introduction to Tcl,  Up: Building an Extended WISH

14.2 Introduction to Tk
=======================

As mentioned above, Tcl is designed to be extensible.  The first and
most basic Tcl extension is Tk, an X11 toolkit.  Tk provides the same
basic facilities that you may be familiar with from other X11 toolkits
such as Athena and Motif, except that they are provided in the context
of the Tcl language.  There are C bindings too, but these are seldom
needed--the vast majority of useful Tk applications can be coded using
Tcl scripts.

   If it has not become obvious already, it is worth noting at this
point that Tcl is one example of a family of languages known generally
as ‘Very High Level Languages’, or VHLL's.  Essentially a VHLL raises
the level of programming to a very high level, allowing very short token
streams to accomplish as much as would be required by many scores of the
more primitive actions available in a basic HLL. Consider, for example,
the basic ‘Hello World!’ application written in Tcl/Tk.


     	#!/usr/local/bin/wish -f

     	button .hello -text "Hello World!"  -command "destroy ."
     	pack .hello

   That's it!  That's all there is to it.  If you have ever programmed X
using a traditional toolkit such as Athena or Motif, you can appreciate
how amazingly much more convenient this is.  If not, you can either take
our word for it that this is 20 times less code than you would need to
use a standard toolkit, or you can go write the same program in one of
the usual toolkits and see for yourself...

   We cannot hope to provide a thorough introduction to Tk programming
in this section.  Instead, we will just say that immensely complex
applications can be constructed merely by programming in exactly the way
shown in the above script.  By writing more complex scripts, and by
utilizing the additional widgets provided by Tk, one can create
beautiful, extensive user interfaces.  Moreover, this can be done in a
tiny fraction of the time it takes to do the same work in a conventional
toolkit.  Literally minutes versus days.

   Tk provides widgets for labels, buttons, radio buttons, frames with
or without borders, menubars, pull downs, toplevels, canvases, edit
boxes, scroll bars, etc.

   A look at the interface provided by the PLplot Tk driver should help
give you a better idea of what you can do with this paradigm.  Also
check out some of the contributed Tcl/Tk packages available at harbor.
There are high quality Tk interfaces to a great many familiar Unix
utilities ranging from mail to info, to SQL, to news, etc.  The list is
endless and growing fast...


File: plplotdoc.info,  Node: Introduction to [incr Tcl],  Next: PLplot Extensions to Tcl,  Prev: Introduction to Tk,  Up: Building an Extended WISH

14.3 Introduction to [incr Tcl]
===============================

Another extremely powerful and popular extension to Tcl is [incr Tcl].
[incr Tcl] is to Tcl what C++ is to C. The analogy is very extensive.
Itcl provides an object oriented extension to Tcl supporting clustering
of procedures and data into what is called an ‘itcl_class’.  An
‘itcl_class’ can have methods as well as instance data.  And they
support inheritance.  Essentially if you know how C++ relates to C, and
if you know Tcl, then you understand the programming model provided by
Itcl.

   In particular, you can use Itcl to implement new widgets which are
composed of more basic Tk widgets.  A file selector is an example.
Using Tk, one can build up a very nice file selector comprised of more
basic Tk widgets such as entries, listboxes, scrollbars, etc.

   But what if you need two file selectors?  You have to do it all
again.  Or what if you need two different kinds of file selectors, you
get to do it again and add some incremental code.

   This is exactly the sort of thing object orientation is intended to
assist.  Using Itcl you can create an ‘itcl_class FileSelector’ and then
you can instantiate them freely as easily as:


     	FileSelector .fs1
     	.fs1 -dir . -find "*.cc"

   and so forth.

   These high level widgets composed of smaller Tk widgets, are known as
‘megawidgets’.  There is a developing subculture of the Tcl/Tk community
for designing and implementing megawidgets, and [incr Tcl] is the most
popular enabling technology.

   In particular, it is the enabling technology which is employed for
the construction of the PLplot Tcl extensions, described below.


File: plplotdoc.info,  Node: PLplot Extensions to Tcl,  Next: Custom Extensions to Tcl,  Prev: Introduction to [incr Tcl],  Up: Building an Extended WISH

14.4 PLplot Extensions to Tcl
=============================

Following the paradigm described above, PLplot provides extensions to
Tcl as well, designed to allow the use of PLplot from Tcl/Tk programs.
Essentially the idea here is to allow PLplot programmers to achieve two
goals:

   • To access PLplot facilities from their own extended WISH and/or
     Tcl/Tk user interface scripts.

   • To have PLplot display its output in a window integrated directly
     into the rest of their Tcl/Tk interface.

   For instance, prior to PLplot 5.0, if a programmer wanted to use
PLplot in a Tcl/Tk application, the best he could manage was to call the
PLplot C API from compiled C code, and get the output via the Xwin
driver, which would display in it's own toplevel window.  In other
words, there was no integration, and the result was pretty sloppy.

   With PLplot 5.0, there is now a supported Tcl interface to PLplot
functionality.  This is provided through a ‘family’ of PLplot
megawidgets implemented in [incr Tcl].  Using this interface, a
programmer can get a PLplot window/widget into a Tk interface as easily
as:


     	PLWin .plw
     	pack .plw

   Actually, there's the update/init business--need to clear that up.

   The ‘PLWin’ class then mirrors much of the PLplot C API, so that a
user can generate plots in the PLplot widget entirely from Tcl.  This is
demonstrated in the ‘tk02’ demo,


File: plplotdoc.info,  Node: Custom Extensions to Tcl,  Prev: PLplot Extensions to Tcl,  Up: Building an Extended WISH

14.5 Custom Extensions to Tcl
=============================

By this point, you should have a pretty decent understanding of the
underlying philosophy of Tcl and Tk, and the whole concept of
extensions, of which [incr Tcl] and PLplot are examples.  These alone
are enough to allow the rapid prototyping and development of powerful,
flexible graphical applications.  Normally the programmer simply writes
a shell script to be executed by the Tk windowing shell, ‘wish’.  It is
in vogue for each Tcl/Tk extension package to build it's own ‘extended
WISH’.  There are many examples of this, and indeed even PLplot's
‘plserver’ program, described in an earlier chapter, could just as
easily have been called ‘plwish’.

   In any event, as exciting and useful as these standalone, extended
windowing shells may be, they are ultimately only the beginning of what
you can do.  The real benefit of this approach is realized when you make
your own ‘extended WISH’, comprised of Tcl, Tk, any of the standard
extensions you like, and finally embellished with a smattering of
application specific extensions designed to support your own application
domain.  In this section we give a detailed introduction to the process
of constructing your own WISH. After that, you're on your own...

* Menu:

* WISH Construction::
* WISH Linking::
* WISH Programming::


File: plplotdoc.info,  Node: WISH Construction,  Next: WISH Linking,  Up: Custom Extensions to Tcl

14.5.1 WISH Construction
------------------------

The standard way to make your own WISH, as supported by the Tcl/Tk
system, is to take a boilerplate file, ‘tkAppInit.c’, edit to reflect
the Tcl/Tk extensions you will be requiring, add some commands to the
interpreter, and link it all together.

   Here for example is the important part of the ‘tk02’ demo, extracted
from the file ‘xtk02.c’, which is effectively the extended WISH
definition file for the ‘tk02’ demo.  Comments and other miscellany are
omitted.


     	  #include "tk.h"
     	  #include "itcl.h"

     	  /* ... */

     	  int   myplotCmd        (ClientData, Tcl_Interp *, int, char **);

     	  int
     	  Tcl_AppInit(interp)
     	  Tcl_Interp *interp;		/* Interpreter for application. */
     	  {
     	  int   plFrameCmd        (ClientData, Tcl_Interp *, int, char **);

     	  Tk_Window main;

     	  main = Tk_MainWindow(interp);

     	  /*
     	  * Call the init procedures for included packages.  Each call should
     	  * look like this:
     	  *
     	  * if (Mod_Init(interp) == TCL_ERROR) {
     	  *     return TCL_ERROR;
     	  * }
     	  *
     	  * where "Mod" is the name of the module.
     	  */

     	  if (Tcl_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Tk_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Itcl_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }
     	  if (Pltk_Init(interp) == TCL_ERROR) {
     	  return TCL_ERROR;
     	  }

     	  /*
     	  * Call Tcl_CreateCommand for application-specific commands, if
     	  * they weren't already created by the init procedures called above.
     	  */

     	  Tcl_CreateCommand(interp, "myplot", myplotCmd,
     	  (ClientData) main, (void (*)(ClientData)) NULL);


     	  /*
     	  * Specify a user-specific start up file to invoke if the
     	  * application is run interactively.  Typically the start up
     	  * file is "~/.apprc" where "app" is the name of the application.
     	  * If this line is deleted then no user-specific start up file
     	  * will be run under any conditions.
     	  */

     	  tcl_RcFileName = "~/.wishrc";
     	  return TCL_OK;
     	  }

     	  /* ... myPlotCmd, etc ... */

   The calls to ‘Tcl_Init()’ and ‘Tk_Init()’ are in every WISH. To make
an extended WISH, you add calls to the initialization routines for any
extension packages you want to use, in this [incr Tcl] (‘Itcl_Init()’)
and PLplot (‘Pltk_Init()’).  Finally you add keywords to the
interpreter, associating them with functions in your code using
‘Tcl_CreateCommand()’ as shown.

   In particular, PLplot has a number of [incr Tcl] classes in its Tcl
library.  If you want to be able to use those in your WISH, you need to
include the initialization of [incr Tcl].


File: plplotdoc.info,  Node: WISH Linking,  Next: WISH Programming,  Prev: WISH Construction,  Up: Custom Extensions to Tcl

14.5.2 WISH Linking
-------------------

Having constructed your ‘Tcl_AppInit()’ function, you now merely need to
link this file with your own private files to provide the code for any
functions you registered via ‘Tcl_CreateCommand()’ (and any they depend
on), against the Tcl, Tk and extension libraries you are using.


     	  cc -c tkAppInit.c
     	  cc -c mycommands.c
     	  cc -o my_wish tkAppInit.o mycommands.o
     	  -lplplotftk -ltcl -ltk -litcl -lX11 -lm

   Add any needed ‘-L’ options as needed.

   Voila!  You have made a wish.


File: plplotdoc.info,  Node: WISH Programming,  Prev: WISH Linking,  Up: Custom Extensions to Tcl

14.5.3 WISH Programming
-----------------------

Now you are ready to put the genie to work.  The basic plan here is to
write shell scripts which use your new application specific windowing
shell as their interpreter, to implement X Windows user interfaces to
control and utilize the facilities made available in your extensions.

   Effectively this just comes down to writing Tcl/Tk code, embellished
as appropriate with calls to the extension commands you registered.
Additionally, since this wish includes the PLplot extensions, you can
instantiate any of the PLplot family of [incr Tcl] classes, and invoke
methods on those objects to effect the drawing of graphs.  Similarly,
you may have your extension commands (which are coded in C) call the
PLplot C programmers API to draw into the widget.  In this way you can
have the best of both worlds.  Use compiled C code when the
computational demands require the speed of compiled code, or use Tcl
when your programming convenience is more important than raw speed.


File: plplotdoc.info,  Node: Embedding Plots in Graphical User Interfaces,  Prev: Building an Extended WISH,  Up: Supported computer languages

15 Embedding Plots in Graphical User Interfaces
***********************************************

This chapter should describe how to embed plots in graphical user
interfaces.  *note Building an Extended WISH:: does that for Tk, but
embedding plots in GTK+ and Qt GUI's NEEDS DOCUMENTATION. Until that
GTK+ and QT4 documentation is prepared, look at examples/c/README.cairo
and examples/c++/README.qt_example for some proof-of-concept examples.


File: plplotdoc.info,  Node: Reference,  Prev: Supported computer languages,  Up: Top

Reference
*********

* Menu:

* Bibliography::
* The Common API for PLplot::
* The Specialized C/C++ API for PLplot::
* The Specialized Fortran API for PLplot::
* API compatibility definition::
* Obsolete/Deprecated API for PLplot::
* Internal C functions in PLplot::
* The PLplot Libraries::


File: plplotdoc.info,  Node: Bibliography,  Next: The Common API for PLplot,  Up: Reference

16 Bibliography
***************

These articles are descriptions of PLplot itself or else scientific
publications whose figures were generated with PLplot.

* Menu:

* References::


File: plplotdoc.info,  Node: References,  Up: Bibliography

16.1 References
===============

Furnish G., Das Graphikpaket PLplot (in German)
(http://www.linux-magazin.de/ausgabe/1996/12/Plplot/plplot.html), Linux
Magazin, 1996 December

   Furnish G., Horton W., Kishimoto Y., LeBrun M., Tajima T., Global
Gyrokinetic Simulation of Tokamak Transport, Physics of Plasmas, 6, 1,
1999

   Irwin A.W., Fukushima T., A Numerical Time Ephemeris of the Earth,
Astronomy and Astrophysics, 348, 642, 1999

   LeBrun M.J., Tajima T., Gray M., Furnish G., Horton W., Toroidal
Effects on Drift-Wave Turbulence, Physics of Fluids, B5, 752, 1993


File: plplotdoc.info,  Node: The Common API for PLplot,  Next: The Specialized C/C++ API for PLplot,  Prev: Bibliography,  Up: Reference

17 The Common API for PLplot
****************************

The purpose of this chapter is to document the common API for every
PLplot function that should be available across all PLplot language
bindings.  Therefore, this chapter excludes obsolete/deprecated API
functions which are listed in *note Obsolete/Deprecated API for PLplot::
and also excludes API specialized for each language binding that is
documented in *note The Specialized C/C++ API for PLplot:: and
subsequent chapters.

   The common API constitutes the most important part of the PLplot API
that programmers need to know.

   For the C case, these common API routines have prototypes defined in
‘plplot.h’ using PLplot C types for arguments (*note plplot-types::).
The names for these types have been chosen to be self-documenting.  So
‘PLINT’ refers to the PLplot integer type, and ‘PLFLT’ refers to the
PLplot floating-point type.  If the name has a ‘_VECTOR’ or ‘_MATRIX’
suffix the type corresponds to the one-dimensional or two-dimensional
array argument type native to the language being supported by PLplot.
If the name does not have either of those two suffixes or if it has a
suffix of ‘_SCALAR’, then it refers to a scalar quantity.  Finally, note
that most of our common API arguments are input only and are guaranteed
not to be changed by the PLplot routine.  However, in some cases the
argument is used for output quantities which _are_ changed by the PLplot
routine, and in this case we include ‘_NC’ (standing for "non-constant")
in the argument type name.

   We document our common API below for the C case, but it should be
fairly straightforward to infer the corresponding API for any of our
supported languages from these results because of the self-documenting
names we use for the PLplot C types for arguments (*note
plplot-types::).  Of course, the best way to learn how to use our common
API for the language of your choice is to look at our standard set of
examples (http://plplot.sourceforge.net/examples.php).  For additional
language documentation you should consult the various chapters in *note
Supported computer languages: Supported computer languages. as well.

   What follows is a list of all common API functions of the latest
PLplot version.  The following information is provided for each
function:

  1. The function name and a brief description.

  2. The function as it would be called from C.

  3. A complete description of the function.

  4. A description of each argument that the function takes.

  5. The redacted argument form of the function as well as any language
     specific variations that might occur on the general calling scheme
     described in the following paragraph.

  6. A list of PLplot examples that demonstrate how to use the function.

   The general calling scheme for the other languages supported by
PLplot is as follows, using the function ‘plline’ (*note plline; Draw a
line::) as an example.

   • C: ‘plline( n, x, y );’

   • Ada/standard: ‘Draw_Curve( x, y );’

   • Ada/traditional: ‘plline( x, y );’

   • C++: ‘pls->line(n, x, y );’

   • D: ‘plline( x, y );’

   • Fortran: ‘plline( x, y )’

   • Java: ‘pls.line( x, y );’

   • Lua: ‘pl.line( x, y )’

   • OCaml: ‘plline x y;’

   • Octave: ‘plline( x', y' );’

   • Python: ‘plline( x, y )’

   • Tcl/Tk: ‘$w cmd plline x y’

Note that in all our supported languages other than C and C++, the
argument ‘‘n’’ (which specifies the length of the input vectors ‘‘x’’
and ‘‘y’’) is not used in the argument list since that information is
already available from the vector (and matrix in the general case)
arguments themselves.  This is what we refer to above as the ‘redacted
argument form’ of the function.

* Menu:

* 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: pladv; Advance the [sub-]page.
* plarc; Draw a circular or elliptical arc : plarc; Draw a circular or elliptical arc.
* plaxes; Draw a box with axes, etc. with arbitrary origin : plaxes; Draw a box with axes; etc_ with arbitrary origin.
* plbin; Plot a histogram from binned data : plbin; Plot a histogram from binned data.
* plbop; Begin a new page::
* plbox; Draw a box with axes, etc: plbox; Draw a box with axes; etc.
* plbox3; Draw a box with axes, etc, in 3-d : plbox3; Draw a box with axes; etc; in 3-d.
* plbtime; Calculate broken-down time from continuous time for the current stream : 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 : plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates.
* plclear; Clear current (sub)page : plclear; Clear current [sub]page.
* plcol0; Set color, cmap0 : plcol0; Set color; cmap0.
* plcol1; Set color, cmap1 : plcol1; Set color; cmap1.
* plcolorbar; Plot color bar for image, shade or gradient plots : plcolorbar; Plot color bar for image; shade or gradient plots.
* plconfigtime; Configure the transformation between continuous and broken-down time for the current stream : plconfigtime; Configure the transformation between continuous and broken-down time for the current stream.
* plcont; Contour plot : plcont; Contour plot.
* plcpstrm; Copy state parameters from the reference stream to the current stream : plcpstrm; Copy state parameters from the reference stream to the current stream.
* plctime; Calculate continuous time from broken-down time for the current stream : plctime; Calculate continuous time from broken-down time for the current stream.
* plend; End plotting session : plend; End plotting session.
* plend1; End plotting session for current stream : plend1; End plotting session for current stream.
* plenv0; Same as plenv but if in multiplot mode does not advance the subpage, instead clears it : 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 : plenv; Set up standard window and draw box.
* pleop; Eject current page : pleop; Eject current page.
* plerrx; Draw error bars in x direction : plerrx; Draw error bars in x direction.
* plerry; Draw error bars in the y direction : plerry; Draw error bars in the y direction.
* plfamadv; Advance to the next family file on the next new page : plfamadv; Advance to the next family file on the next new page.
* plfill; Draw filled polygon : plfill; Draw filled polygon.
* plfill3; Draw filled polygon in 3D : plfill3; Draw filled polygon in 3D.
* plflush; Flushes the output stream : plflush; Flushes the output stream.
* plfont; Set font : plfont; Set font.
* plfontld; Load Hershey fonts : plfontld; Load Hershey fonts.
* plGetCursor; Wait for graphics input event and translate to world coordinates. : plGetCursor; Wait for graphics input event and translate to world coordinates_.
* plgchr; Get character default height and current (scaled) height : plgchr; Get character default height and current [scaled] height.
* plgcmap1_range; Get the cmap1 argument range for continuous color plots : plgcmap1_range; Get the cmap1 argument range for continuous color plots.
* plgcol0; Returns 8-bit RGB values for given color index from cmap0 : plgcol0; Returns 8-bit RGB values for given color index from cmap0.
* plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0 : plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0.
* plgcolbg; Returns the background color (cmap0[0]) by 8-bit RGB value : 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 PLFLT alpha transparency value : plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value.
* plgcompression; Get the current device-compression setting : plgcompression; Get the current device-compression setting.
* plgdev; Get the current device (keyword) name : plgdev; Get the current device [keyword] name.
* plgdidev; Get parameters that define current device-space window : plgdidev; Get parameters that define current device-space window.
* plgdiori; Get plot orientation : plgdiori; Get plot orientation.
* plgdiplt; Get parameters that define current plot-space window : plgdiplt; Get parameters that define current plot-space window.
* plgdrawmode; Get drawing mode (depends on device support!) : plgdrawmode; Get drawing mode [depends on device support!].
* plgfam; Get family file parameters : plgfam; Get family file parameters.
* plgfci; Get FCI (font characterization integer) : plgfci; Get FCI [font characterization integer].
* plgfnam; Get output file name : plgfnam; Get output file name.
* plgfont; Get family, style and weight of the current font : plgfont; Get family; style and weight of the current font.
* plglevel; Get the (current) run level : plglevel; Get the [current] run level.
* plgpage; Get page parameters : plgpage; Get page parameters.
* plgra; Switch to graphics screen : plgra; Switch to graphics screen.
* plgradient; Draw linear gradient inside polygon : plgradient; Draw linear gradient inside polygon.
* plgriddata; Grid data from irregularly sampled data : plgriddata; Grid data from irregularly sampled data.
* plgspa; Get current subpage parameters : plgspa; Get current subpage parameters.
* plgstrm; Get current stream number : plgstrm; Get current stream number.
* plgver; Get the current library version number : plgver; Get the current library version number.
* plgvpd; Get viewport limits in normalized device coordinates : plgvpd; Get viewport limits in normalized device coordinates.
* plgvpw; Get viewport limits in world coordinates : plgvpw; Get viewport limits in world coordinates.
* plgxax; Get x axis parameters : plgxax; Get x axis parameters.
* plgyax; Get y axis parameters : plgyax; Get y axis parameters.
* plgzax; Get z axis parameters : plgzax; Get z axis parameters.
* plhist; Plot a histogram from unbinned data : plhist; Plot a histogram from unbinned data.
* plhlsrgb; Convert HLS color to RGB : plhlsrgb; Convert HLS color to RGB.
* plimagefr; Plot a 2D matrix using cmap1 : plimagefr; Plot a 2D matrix using cmap1.
* plimage; Plot a 2D matrix using cmap1 with automatic color adjustment : plimage; Plot a 2D matrix using cmap1 with automatic color adjustment.
* plinit; Initialize PLplot : plinit; Initialize PLplot.
* pljoin; Draw a line between two points : pljoin; Draw a line between two points.
* pllab; Simple routine to write labels : pllab; Simple routine to write labels.
* pllegend; Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols : pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols.
* pllightsource; Sets the 3D position of the light source : pllightsource; Sets the 3D position of the light source.
* plline; Draw a line : plline; Draw a line.
* plline3; Draw a line in 3 space : plline3; Draw a line in 3 space.
* pllsty; Select line style : pllsty; Select line style.
* plmap; Plot continental outline or shapefile data in world coordinates : plmap; Plot continental outline or shapefile data in world coordinates.
* plmapfill; Plot all or a subset of Shapefile data, filling the polygons : plmapfill; Plot all or a subset of Shapefile data; filling the polygons.
* plmapline; Plot all or a subset of Shapefile data using lines in world coordinates : plmapline; Plot all or a subset of Shapefile data using lines in world coordinates.
* plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates : plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates.
* plmaptex; Draw text at points defined by Shapefile data in world coordinates : plmaptex; Draw text at points defined by Shapefile data in world coordinates.
* plmeridians; Plot latitude and longitude lines : plmeridians; Plot latitude and longitude lines.
* plmesh; Plot surface mesh : plmesh; Plot surface mesh.
* plmeshc; Magnitude colored plot surface mesh with contour : plmeshc; Magnitude colored plot surface mesh with contour.
* plmkstrm; Creates a new stream and makes it the default : plmkstrm; Creates a new stream and makes it the default.
* plmtex; Write text relative to viewport boundaries : plmtex; Write text relative to viewport boundaries.
* plmtex3; Write text relative to viewport boundaries in 3D plots : plmtex3; Write text relative to viewport boundaries in 3D plots.
* plot3d; Plot 3-d surface plot : plot3d; Plot 3-d surface plot.
* plot3dc; Magnitude colored plot surface with contour : plot3dc; Magnitude colored plot surface with contour.
* plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits : plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits.
* plparseopts; Parse command-line arguments : plparseopts; Parse command-line arguments.
* plpat; Set area line fill pattern : plpat; Set area line fill pattern.
* plpath; Draw a line between two points, accounting for coordinate transforms : plpath; Draw a line between two points; accounting for coordinate transforms.
* plpoin; Plot a glyph at the specified points : plpoin; Plot a glyph at the specified points.
* plpoin3; Plot a glyph at the specified 3D points : plpoin3; Plot a glyph at the specified 3D points.
* plpoly3; Draw a polygon in 3 space : plpoly3; Draw a polygon in 3 space.
* plprec; Set precision in numeric labels : plprec; Set precision in numeric labels.
* plpsty; Select area fill pattern : plpsty; Select area fill pattern.
* plptex; Write text inside the viewport : plptex; Write text inside the viewport.
* plptex3; Write text inside the viewport of a 3D plot : plptex3; Write text inside the viewport of a 3D plot.
* plrandd; Random number generator returning a real random number in the range [0,1] : plrandd; Random number generator returning a real random number in the range [0;1].
* plreplot; Replays contents of plot buffer to current device/file : plreplot; Replays contents of plot buffer to current device/file.
* plrgbhls; Convert RGB color to HLS : plrgbhls; Convert RGB color to HLS.
* plschr; Set character size : plschr; Set character size.
* plscmap0; Set cmap0 colors by 8-bit RGB values : plscmap0; Set cmap0 colors by 8-bit RGB values.
* plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value : plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value.
* plscmap0n; Set number of colors in cmap0 : plscmap0n; Set number of colors in cmap0.
* plscmap1_range; Set the cmap1 argument range for continuous color plots : plscmap1_range; Set the cmap1 argument range for continuous color plots.
* plscmap1; Set opaque RGB cmap1 colors values : plscmap1; Set opaque RGB cmap1 colors values.
* plscmap1a; Set semitransparent cmap1 RGBA colors. : plscmap1a; Set semitransparent cmap1 RGBA colors_.
* plscmap1l; Set cmap1 colors using a piece-wise linear relationship : plscmap1l; Set cmap1 colors using a piece-wise linear relationship.
* plscmap1la; Set cmap1 colors and alpha transparency 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 : plscmap1n; Set number of colors in cmap1.
* plscol0; Set 8-bit RGB values for given cmap0 color index : plscol0; Set 8-bit RGB values for given cmap0 color index.
* plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index : plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index.
* plscolbg; Set the background color by 8-bit RGB value : plscolbg; Set the background color by 8-bit RGB value.
* plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value. : plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_.
* plscolor; Used to globally turn color output on/off : plscolor; Used to globally turn color output on/off.
* plscompression; Set device-compression level : plscompression; Set device-compression level.
* plsdev; Set the device (keyword) name : plsdev; Set the device [keyword] name.
* plsdidev; Set parameters that define current device-space window : plsdidev; Set parameters that define current device-space window.
* plsdimap; Set up transformation from metafile coordinates : plsdimap; Set up transformation from metafile coordinates.
* plsdiori; Set plot orientation : plsdiori; Set plot orientation.
* plsdiplt; Set parameters that define current plot-space window : plsdiplt; Set parameters that define current plot-space window.
* plsdiplz; Set parameters incrementally (zoom mode) 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!) : plsdrawmode; Set drawing mode [depends on device support!].
* plseed; Set seed for internal random number generator. : plseed; Set seed for internal random number generator_.
* plsesc; Set the escape character for text strings : plsesc; Set the escape character for text strings.
* plsetopt; Set any command-line option : plsetopt; Set any command-line option.
* plsfam; Set family file parameters : plsfam; Set family file parameters.
* plsfci; Set FCI (font characterization integer) : plsfci; Set FCI [font characterization integer].
* plsfnam; Set output file name : plsfnam; Set output file name.
* plsfont; Set family, style and weight of the current font : plsfont; Set family; style and weight of the current font.
* plshades; Shade regions on the basis of value : plshades; Shade regions on the basis of value.
* plshade; Shade individual region on the basis of value : plshade; Shade individual region on the basis of value.
* plslabelfunc; Assign a function to use for generating custom axis labels : plslabelfunc; Assign a function to use for generating custom axis labels.
* plsmaj; Set length of major ticks : plsmaj; Set length of major ticks.
* plsmem; Set the memory area to be plotted (RGB) : plsmem; Set the memory area to be plotted [RGB].
* plsmema; Set the memory area to be plotted (RGBA) : plsmema; Set the memory area to be plotted [RGBA].
* plsmin; Set length of minor ticks : plsmin; Set length of minor ticks.
* plsori; Set orientation : plsori; Set orientation.
* plspage; Set page parameters : plspage; Set page parameters.
* plspal0; Set the cmap0 palette using the specified cmap0*.pal format file : plspal0; Set the cmap0 palette using the specified cmap0*_pal format file.
* plspal1; Set the cmap1 palette using the specified cmap1*.pal format file : plspal1; Set the cmap1 palette using the specified cmap1*_pal format file.
* plspause; Set the pause (on end-of-page) status : plspause; Set the pause [on end-of-page] status.
* plsstrm; Set current output stream : plsstrm; Set current output stream.
* plssub; Set the number of subpages in x and y : plssub; Set the number of subpages in x and y.
* plssym; Set symbol size : plssym; Set symbol size.
* plstar; Initialization : plstar; Initialization.
* plstart; Initialization : plstart; Initialization.
* plstransform; Set a global coordinate transform function : plstransform; Set a global coordinate transform function.
* plstring; Plot a glyph at the specified points : plstring; Plot a glyph at the specified points.
* plstring3; Plot a glyph at the specified 3D points : plstring3; Plot a glyph at the specified 3D points.
* plstripa; Add a point to a strip chart : plstripa; Add a point to a strip chart.
* plstripc; Create a 4-pen strip chart : plstripc; Create a 4-pen strip chart.
* plstripd; Deletes and releases memory used by a strip chart : plstripd; Deletes and releases memory used by a strip chart.
* plstyl; Set line style : plstyl; Set line style.
* plsurf3d; Plot shaded 3-d surface plot : plsurf3d; Plot shaded 3-d surface plot.
* plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits : plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits.
* plsvect; Set arrow style for vector plots : plsvect; Set arrow style for vector plots.
* plsvpa; Specify viewport in absolute coordinates : plsvpa; Specify viewport in absolute coordinates.
* plsxax; Set x axis parameters : plsxax; Set x axis parameters.
* plsyax; Set y axis parameters : plsyax; Set y axis parameters.
* plsym; Plot a glyph at the specified points : plsym; Plot a glyph at the specified points.
* plszax; Set z axis parameters : plszax; Set z axis parameters.
* pltext; Switch to text screen : pltext; Switch to text screen.
* pltimefmt; Set format for date / time labels : pltimefmt; Set format for date / time labels.
* plvasp; Specify viewport using aspect ratio only : plvasp; Specify viewport using aspect ratio only.
* plvect; Vector plot : plvect; Vector plot.
* plvpas; Specify viewport using coordinates and aspect ratio : plvpas; Specify viewport using coordinates and aspect ratio.
* plvpor; Specify viewport using normalized subpage coordinates : plvpor; Specify viewport using normalized subpage coordinates.
* plvsta; Select standard viewport : plvsta; Select standard viewport.
* plw3d; Configure the transformations required for projecting a 3D surface on a 2D window : plw3d; Configure the transformations required for projecting a 3D surface on a 2D window.
* plwidth; Set pen width : plwidth; Set pen width.
* plwind; Specify window : plwind; Specify window.
* plxormod; Enter or leave xor mode : plxormod; Enter or leave xor mode.


File: plplotdoc.info,  Node: pl_setcontlabelformat; Set format of numerical label for contours,  Next: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Up: The Common API for PLplot

17.1 pl_setcontlabelformat: Set format of numerical label for contours
======================================================================

     pl_setcontlabelformat (lexp, sigdig);

   Set format of numerical label for contours.

‘lexp’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     If the contour numerical label is greater than 10^(lexp) or less
     than 10^(-lexp), then the exponential format is used.  Default
     value of lexp is 4.

‘sigdig’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of significant digits.  Default value is 2.

   Redacted form: ‘pl_setcontlabelformat(lexp, sigdig)’

   This function is used example 9.


File: plplotdoc.info,  Node: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Next: pladv; Advance the [sub-]page,  Prev: pl_setcontlabelformat; Set format of numerical label for contours,  Up: The Common API for PLplot

17.2 pl_setcontlabelparam: Set parameters of contour labelling other than format of numerical label
===================================================================================================

     pl_setcontlabelparam (offset, size, spacing, active);

   Set parameters of contour labelling other than those handled by
‘pl_setcontlabelformat’ (*note pl_setcontlabelformat; Set format of
numerical label for contours::).

‘offset’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Offset of label from contour line (if set to 0.0, labels are
     printed on the lines).  Default value is 0.006.

‘size’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Font height for contour labels (normalized).  Default value is 0.3.

‘spacing’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Spacing parameter for contour labels.  Default value is 0.1.

‘active’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Activate labels.  Set to 1 if you want contour labels on.  Default
     is off (0).

   Redacted form: ‘pl_setcontlabelparam(offset, size, spacing, active)’

   This function is used in example 9.


File: plplotdoc.info,  Node: pladv; Advance the [sub-]page,  Next: plarc; Draw a circular or elliptical arc,  Prev: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label,  Up: The Common API for PLplot

17.3 pladv: Advance the (sub-)page
==================================

     pladv (page);

   Advances to the next subpage if ‘‘sub’=0’, performing a page advance
if there are no remaining subpages on the current page.  If subpages
aren't being used, ‘‘pladv’ (*note pladv; Advance the [sub-]page::)(0)’
will always advance the page.  If ‘‘page’>0’, PLplot switches to the
specified subpage.  Note that this allows you to overwrite a plot on the
specified subpage; if this is not what you intended, use ‘pleop’ (*note
pleop; Eject current page::) followed by ‘plbop’ (*note plbop; Begin a
new page::) to first advance the page.  This routine is called
automatically (with ‘‘page’=0’) by ‘plenv’ (*note plenv; Set up standard
window and draw box::), but if ‘plenv’ (*note plenv; Set up standard
window and draw box::) is not used, ‘pladv’ (*note pladv; Advance the
[sub-]page::) must be called after initializing PLplot but before
defining the viewport.

‘page’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Specifies the subpage number (starting from 1 in the top left
     corner and increasing along the rows) to which to advance.  Set to
     zero to advance to the next subpage (or to the next page if
     subpages are not being used).

   Redacted form: ‘pladv(page)’

   This function is used in examples 1, 2, 4, 6-12, 14-18, 20, 21,
23-27, 29, and 31.


File: plplotdoc.info,  Node: plarc; Draw a circular or elliptical arc,  Next: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Prev: pladv; Advance the [sub-]page,  Up: The Common API for PLplot

17.4 plarc: Draw a circular or elliptical arc
=============================================

     plarc (x, y, a, b, angle1, angle2, rotate, fill);

   Draw a possibly filled arc centered at ‘‘x’’, ‘‘y’’ with semimajor
axis ‘‘a’’ and semiminor axis ‘‘b’’, starting at ‘‘angle1’’ and ending
at ‘‘angle2’’.

‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     X coordinate of arc center.

‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Y coordinate of arc center.

‘a’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Length of the semimajor axis of the arc.

‘b’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Length of the semiminor axis of the arc.

‘angle1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Starting angle of the arc relative to the semimajor axis.

‘angle2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Ending angle of the arc relative to the semimajor axis.

‘rotate’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Angle of the semimajor axis relative to the X-axis.

‘fill’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     Draw a filled arc.

   Redacted form:

   • General: ‘plarc(x, y, a, b, angle1, angle2, rotate, fill)’

   This function is used in examples 3 and 27.


File: plplotdoc.info,  Node: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Next: plbin; Plot a histogram from binned data,  Prev: plarc; Draw a circular or elliptical arc,  Up: The Common API for PLplot

17.5 plaxes: Draw a box with axes, etc. with arbitrary origin
=============================================================

     plaxes (x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub);

   Draws a box around the currently defined viewport with arbitrary
world-coordinate origin specified by ‘‘x0’’ and ‘‘y0’’ and labels it
with world coordinate values appropriate to the window.  Thus ‘plaxes’
(*note plaxes; Draw a box with axes; etc_ with arbitrary origin::)
should only be called after defining both viewport and window.  The
ascii character strings ‘‘xopt’’ and ‘‘yopt’’ specify how the box should
be drawn as described below.  If ticks and/or subticks are to be drawn
for a particular axis, the tick intervals and number of subintervals may
be specified explicitly, or they may be defaulted by setting the
appropriate arguments to zero.

‘x0’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World X coordinate of origin.

‘y0’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World Y coordinate of origin.

‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the x axis.  The
     string can include any combination of the following letters (upper
     or lower case) in any order:

        • ‘a’: Draws axis, X-axis is horizontal line (‘y=0’), and Y-axis
          is vertical line (‘x=0’).

        • ‘b’: Draws bottom (X) or left (Y) edge of frame.

        • ‘c’: Draws top (X) or right (Y) edge of frame.

        • ‘d’: Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).

        • ‘f’: Always use fixed point numeric labels.

        • ‘g’: Draws a grid at the major tick interval.

        • ‘h’: Draws a grid at the minor tick interval.

        • ‘i’: Inverts tick marks, so they are drawn outwards, rather
          than inwards.

        • ‘l’: Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        • ‘m’: Writes numeric labels at major tick intervals in the
          unconventional location (above box for X, right of box for Y).

        • ‘n’: Writes numeric labels at major tick intervals in the
          conventional location (below box for X, left of box for Y).

        • ‘o’: Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        • ‘s’: Enables subticks between major ticks, only valid if ‘t’
          is also specified.

        • ‘t’: Draws major ticks.

        • ‘u’: Exactly like "b" except don't draw edge line.

        • ‘w’: Exactly like "c" except don't draw edge line.

        • ‘x’: Exactly like "t" (including the side effect of the
          numerical labels for the major ticks) except exclude drawing
          the major and minor tick marks.

‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the x axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the y axis.  The
     string can include any combination of the letters defined above for
     ‘‘xopt’’, and in addition may contain:

        • ‘v’: Write numeric labels for the y axis parallel to the base
          of the graph, rather than parallel to the axis.

‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the y axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   • General: ‘plaxes(x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub)’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plbin; Plot a histogram from binned data,  Next: plbop; Begin a new page,  Prev: plaxes; Draw a box with axes; etc_ with arbitrary origin,  Up: The Common API for PLplot

17.6 plbin: Plot a histogram from binned data
=============================================

     plbin (nbin, x, y, opt);

   Plots a histogram consisting of ‘‘nbin’’ bins.  The value associated
with the ‘i’'th bin is placed in ‘‘x’[i]’, and the number of points in
the bin is placed in ‘‘y’[i]’.  For proper operation, the values in
‘‘x’[i]’ must form a strictly increasing sequence.  By default, ‘‘x’[i]’
is the left-hand edge of the ‘i’'th bin.  If ‘‘opt’=PL_BIN_CENTRED’ is
used, the bin boundaries are placed midway between the values in the
‘‘x’’ vector.  Also see ‘plhist’ (*note plhist; Plot a histogram from
unbinned data::) for drawing histograms from unbinned data.

‘nbin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of bins (i.e., number of values in ‘‘x’’ and ‘‘y’’ vectors.)

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing values associated with bins.  These must form a
     strictly increasing sequence.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing a number which is proportional to the number of
     points in each bin.  This is a ‘PLFLT’ (instead of ‘PLINT’) vector
     so as to allow histograms of probabilities, etc.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Is a combination of several flags:

        • ‘‘opt’=PL_BIN_DEFAULT’: The ‘‘x’’ represent the lower bin
          boundaries, the outer bins are expanded to fill up the entire
          x-axis and bins of zero height are simply drawn.

        • ‘‘opt’=PL_BIN_CENTRED|...’: The bin boundaries are to be
          midway between the ‘‘x’’ values.  If the values in ‘‘x’’ are
          equally spaced, the values are the center values of the bins.

        • ‘‘opt’=PL_BIN_NOEXPAND|...’: The outer bins are drawn with
          equal size as the ones inside.

        • ‘‘opt’=PL_BIN_NOEMPTY|...’: Bins with zero height are not
          drawn (there is a gap for such bins).

   Redacted form:

   • General: ‘plbin(x, y, opt)’

   • Python: ‘plbin(nbin, x, y, opt)’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plbop; Begin a new page,  Next: plbox; Draw a box with axes; etc,  Prev: plbin; Plot a histogram from binned data,  Up: The Common API for PLplot

17.7 plbop: Begin a new page
============================

     plbop ();

   Begins a new page.  For a file driver, the output file is opened if
necessary.  Advancing the page via ‘pleop’ (*note pleop; Eject current
page::) and ‘plbop’ (*note plbop; Begin a new page::) is useful when a
page break is desired at a particular point when plotting to subpages.
Another use for ‘pleop’ (*note pleop; Eject current page::) and ‘plbop’
(*note plbop; Begin a new page::) is when plotting pages to different
files, since you can manually set the file name by calling ‘plsfnam’
(*note plsfnam; Set output file name::) after the call to ‘pleop’ (*note
pleop; Eject current page::).  (In fact some drivers may only support a
single page per file, making this a necessity.)  One way to handle this
case automatically is to page advance via ‘pladv’ (*note pladv; Advance
the [sub-]page::), but enable familying (see ‘plsfam’ (*note plsfam; Set
family file parameters::)) with a small limit on the file size so that a
new family member file will be created on each page break.

   Redacted form: ‘plbop()’

   This function is used in examples 2 and 20.


File: plplotdoc.info,  Node: plbox; Draw a box with axes; etc,  Next: plbox3; Draw a box with axes; etc; in 3-d,  Prev: plbop; Begin a new page,  Up: The Common API for PLplot

17.8 plbox: Draw a box with axes, etc
=====================================

     plbox (xopt, xtick, nxsub, yopt, ytick, nysub);

   Draws a box around the currently defined viewport, and labels it with
world coordinate values appropriate to the window.  Thus ‘plbox’ (*note
plbox; Draw a box with axes; etc::) should only be called after defining
both viewport and window.  The ascii character strings ‘‘xopt’’ and
‘‘yopt’’ specify how the box should be drawn as described below.  If
ticks and/or subticks are to be drawn for a particular axis, the tick
intervals and number of subintervals may be specified explicitly, or
they may be defaulted by setting the appropriate arguments to zero.

‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the x axis.  The
     string can include any combination of the following letters (upper
     or lower case) in any order:

        • ‘a’: Draws axis, X-axis is horizontal line (‘y=0’), and Y-axis
          is vertical line (‘x=0’).

        • ‘b’: Draws bottom (X) or left (Y) edge of frame.

        • ‘c’: Draws top (X) or right (Y) edge of frame.

        • ‘d’: Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).

        • ‘f’: Always use fixed point numeric labels.

        • ‘g’: Draws a grid at the major tick interval.

        • ‘h’: Draws a grid at the minor tick interval.

        • ‘i’: Inverts tick marks, so they are drawn outwards, rather
          than inwards.

        • ‘l’: Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        • ‘m’: Writes numeric labels at major tick intervals in the
          unconventional location (above box for X, right of box for Y).

        • ‘n’: Writes numeric labels at major tick intervals in the
          conventional location (below box for X, left of box for Y).

        • ‘o’: Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        • ‘s’: Enables subticks between major ticks, only valid if ‘t’
          is also specified.

        • ‘t’: Draws major ticks.

        • ‘u’: Exactly like "b" except don't draw edge line.

        • ‘w’: Exactly like "c" except don't draw edge line.

        • ‘x’: Exactly like "t" (including the side effect of the
          numerical labels for the major ticks) except exclude drawing
          the major and minor tick marks.

‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the x axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the y axis.  The
     string can include any combination of the letters defined above for
     ‘‘xopt’’, and in addition may contain:

        • ‘v’: Write numeric labels for the y axis parallel to the base
          of the graph, rather than parallel to the axis.

‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the y axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   • General: ‘plbox(xopt, xtick, nxsub, yopt, ytick, nysub)’

   This function is used in examples 1, 2, 4, 6, 6-12, 14-18, 21, 23-26,
and 29.


File: plplotdoc.info,  Node: plbox3; Draw a box with axes; etc; in 3-d,  Next: plbtime; Calculate broken-down time from continuous time for the current stream,  Prev: plbox; Draw a box with axes; etc,  Up: The Common API for PLplot

17.9 plbox3: Draw a box with axes, etc, in 3-d
==============================================

     plbox3 (xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick, nysub,
     zopt, zlabel, ztick, nzsub);

   Draws axes, numeric and text labels for a three-dimensional surface
plot.  For a more complete description of three-dimensional plotting see
*note Three-dimensional Plots::.

‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the x axis.  The
     string can include any combination of the following letters (upper
     or lower case) in any order:

        • ‘b’: Draws axis at base, at height ‘z=‘zmin’’ where ‘‘zmin’’
          is defined by call to ‘plw3d’ (*note plw3d; Configure the
          transformations required for projecting a 3D surface on a 2D
          window::).  This character must be specified in order to use
          any of the other options.

        • ‘d’: Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).

        • ‘f’: Always use fixed point numeric labels.

        • ‘i’: Inverts tick marks, so they are drawn downwards, rather
          than upwards.

        • ‘l’: Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        • ‘n’: Writes numeric labels at major tick intervals.

        • ‘o’: Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        • ‘s’: Enables subticks between major ticks, only valid if ‘t’
          is also specified.

        • ‘t’: Draws major ticks.

        • ‘u’: If this is specified, the text label for the axis is
          written under the axis.

‘xlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the text label for the x axis.
     It is only drawn if ‘u’ is in the ‘‘xopt’’ string.

‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the x axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major x axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the y axis.  The
     string is interpreted in the same way as ‘‘xopt’’.

‘ylabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the text label for the y axis.
     It is only drawn if ‘u’ is in the ‘‘yopt’’ string.

‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the y axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major y axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

‘zopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying options for the z axis.  The
     string can include any combination of the following letters (upper
     or lower case) in any order:

        • ‘b’: Draws z axis to the left of the surface plot.

        • ‘c’: Draws z axis to the right of the surface plot.

        • ‘d’: Draws grid lines parallel to the x-y plane behind the
          figure.  These lines are not drawn until after ‘plot3d’ (*note
          plot3d; Plot 3-d surface plot::) or ‘plmesh’ (*note plmesh;
          Plot surface mesh::) are called because of the need for hidden
          line removal.

        • ‘e’: Plot labels as date / time.  Values are assumed to be
          seconds since the epoch (as used by gmtime).  Note this
          suboption is interpreted the same as the ‘d’ suboption for
          ‘‘xopt’’ and ‘‘yopt’’, but it has to be identified as ‘e’ for
          ‘‘zopt’’ since ‘d’ has already been used for the different
          purpose above.

        • ‘f’: Always use fixed point numeric labels.

        • ‘i’: Inverts tick marks, so they are drawn away from the
          center.

        • ‘l’: Labels axis logarithmically.  This only affects the
          labels, not the data, and so it is necessary to compute the
          logarithms of data points before passing them to any of the
          drawing routines.

        • ‘m’: Writes numeric labels at major tick intervals on the
          right-hand z axis.

        • ‘n’: Writes numeric labels at major tick intervals on the
          left-hand z axis.

        • ‘o’: Use custom labelling function to generate axis label
          text.  The custom labelling function can be defined with the
          ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use
          for generating custom axis labels::) command.

        • ‘s’: Enables subticks between major ticks, only valid if ‘t’
          is also specified.

        • ‘t’: Draws major ticks.

        • ‘u’: If this is specified, the text label is written beside
          the left-hand axis.

        • ‘v’: If this is specified, the text label is written beside
          the right-hand axis.

‘zlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the text label for the z axis.
     It is only drawn if ‘u’ or ‘v’ are in the ‘‘zopt’’ string.

‘ztick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     World coordinate interval between major ticks on the z axis.  If it
     is set to zero, PLplot automatically generates a suitable tick
     interval.

‘nzsub’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of subintervals between major z axis ticks for minor ticks.
     If it is set to zero, PLplot automatically generates a suitable
     minor tick interval.

   Redacted form:

   • General: ‘plbox3(xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick,
     nysub, zopt, zlabel, ztick, nzsub)’

   This function is used in examples 8, 11, 18, and 21.


File: plplotdoc.info,  Node: plbtime; Calculate broken-down time from continuous time for the current stream,  Next: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Prev: plbox3; Draw a box with axes; etc; in 3-d,  Up: The Common API for PLplot

17.10 plbtime: Calculate broken-down time from continuous time for the current stream
=====================================================================================

     plbtime (year, month, day, hour, min, sec, ctime);

   Calculate broken-down time; ‘‘year’’, ‘‘month’’, ‘‘day’’, ‘‘hour’’,
‘‘min’’, ‘‘sec’’; from continuous time, ‘‘ctime’’ for the current
stream.  This function is the inverse of ‘plctime’ (*note plctime;
Calculate continuous time from broken-down time for the current
stream::).

   The PLplot definition of broken-down time is a calendar time that
completely ignores all time zone offsets, i.e., it is the user's
responsibility to apply those offsets (if so desired) before using the
PLplot time API. By default broken-down time is defined using the
proleptic Gregorian calendar without the insertion of leap seconds and
continuous time is defined as the number of seconds since the Unix epoch
of 1970-01-01T00:00:00Z. However, other definitions of broken-down and
continuous time are possible, see ‘plconfigtime’ (*note plconfigtime;
Configure the transformation between continuous and broken-down time for
the current stream::).

‘year’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of years with positive values corresponding to CE
     (i.e., 1 = 1 CE, etc.)  and non-negative values corresponding to
     BCE (e.g., 0 = 1 BCE, -1 = 2 BCE, etc.)

‘month’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of month within the year in the range from 0
     (January) to 11 (December).

‘day’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of day within the month in the range from 1 to 31.

‘hour’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of hour within the day in the range from 0 to 23.

‘min’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of minute within the hour in the range from 0 to 59

‘sec’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of second within the minute in range from 0.  to 60.

‘ctime’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Continuous time from which the broken-down time is calculated.

   Redacted form:

   • General: ‘plbtime(year, month, day, hour, min, sec, ctime)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Next: plclear; Clear current [sub]page,  Prev: plbtime; Calculate broken-down time from continuous time for the current stream,  Up: The Common API for PLplot

17.11 plcalc_world: Calculate world coordinates and corresponding window index from relative device coordinates
===============================================================================================================

     plcalc_world (rx, ry, wx, wy, window);

   Calculate world coordinates, ‘‘wx’’ and ‘‘wy’’, and corresponding
‘‘window’’ index from relative device coordinates, ‘‘rx’’ and ‘‘ry’’.

‘rx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Input relative device coordinate (0.0-1.0) for the x coordinate.

‘ry’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Input relative device coordinate (0.0-1.0) for the y coordinate.

‘wx’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the x world coordinate corresponding to the
     relative device coordinates ‘‘rx’’ and ‘‘ry’’.

‘wy’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the y world coordinate corresponding to the
     relative device coordinates ‘‘rx’’ and ‘‘ry’’.

‘window’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the last defined window index that corresponds to
     the input relative device coordinates (and the returned world
     coordinates).  To give some background on the window index, for
     each page the initial window index is set to zero, and each time
     ‘plwind’ (*note plwind; Specify window::) is called within the
     page, world and device coordinates are stored for the window and
     the window index is incremented.  Thus, for a simple page layout
     with non-overlapping viewports and one window per viewport,
     ‘‘window’’ corresponds to the viewport index (in the order which
     the viewport/windows were created) of the only viewport/window
     corresponding to ‘‘rx’’ and ‘‘ry’’.  However, for more complicated
     layouts with potentially overlapping viewports and possibly more
     than one window (set of world coordinates) per viewport, ‘‘window’’
     and the corresponding output world coordinates corresponds to the
     last window created that fulfills the criterion that the relative
     device coordinates are inside it.  Finally, in all cases where the
     input relative device coordinates are not inside any
     viewport/window, then the returned value of the last defined window
     index is set to -1.

   Redacted form:

   • General: ‘plcalc_world(rx, ry, wx, wy, window)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plclear; Clear current [sub]page,  Next: plcol0; Set color; cmap0,  Prev: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates,  Up: The Common API for PLplot

17.12 plclear: Clear current (sub)page
======================================

     plclear ();

   Clears the current page, effectively erasing everything that have
been drawn.  This command only works with interactive drivers; if the
driver does not support this, the page is filled with the background
color in use.  If the current page is divided into subpages, only the
current subpage is erased.  The nth subpage can be selected with ‘pladv’
(*note pladv; Advance the [sub-]page::)(n).

   Redacted form:

   • General: ‘plclear()’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plcol0; Set color; cmap0,  Next: plcol1; Set color; cmap1,  Prev: plclear; Clear current [sub]page,  Up: The Common API for PLplot

17.13 plcol0: Set color, cmap0
==============================

     plcol0 (icol0);

   Sets the color index for cmap0 (see *note Color Map0::).

‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Integer representing the color.  The defaults at present are (these
     may change):

     0 black (default background)
     1 red (default foreground)
     2 yellow
     3 green
     4 aquamarine
     5 pink
     6 wheat
     7 grey
     8 brown
     9 blue
     10 BlueViolet
     11 cyan
     12 turquoise
     13 magenta
     14 salmon
     15 white

     Use ‘plscmap0’ (*note plscmap0; Set cmap0 colors by 8-bit RGB
     values::) to change the entire cmap0 color palette and ‘plscol0’
     (*note plscol0; Set 8-bit RGB values for given cmap0 color index::)
     to change an individual color in the cmap0 color palette.

   Redacted form: ‘plcol0(icol0)’

   This function is used in examples 1-9, 11-16, 18-27, and 29.


File: plplotdoc.info,  Node: plcol1; Set color; cmap1,  Next: plcolorbar; Plot color bar for image; shade or gradient plots,  Prev: plcol0; Set color; cmap0,  Up: The Common API for PLplot

17.14 plcol1: Set color, cmap1
==============================

     plcol1 (col1);

   Sets the color for cmap1 (see *note Color Map1::).

‘col1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     This value must be in the range (0.0-1.0) and is mapped to color
     using the continuous cmap1 palette which by default ranges from
     blue to the background color to red.  The cmap1 palette can also be
     straightforwardly changed by the user with ‘plscmap1’ (*note
     plscmap1; Set opaque RGB cmap1 colors values::) or ‘plscmap1l’
     (*note plscmap1l; Set cmap1 colors using a piece-wise linear
     relationship::).

   Redacted form: ‘plcol1(col1)’

   This function is used in examples 12 and 21.


File: plplotdoc.info,  Node: plcolorbar; Plot color bar for image; shade or gradient plots,  Next: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Prev: plcol1; Set color; cmap1,  Up: The Common API for PLplot

17.15 plcolorbar: Plot color bar for image, shade or gradient plots
===================================================================

     plcolorbar (p_colorbar_width, p_colorbar_height, opt, position, x,
     y, x_length, y_length, bg_color, bb_color, bb_style, low_cap_color,
     high_cap_color, cont_color, cont_width, n_labels, label_opts,
     labels, naxes, axis_opts, ticks, sub_ticks, n_values, values);

   Routine for creating a continuous color bar for image, shade, or
gradient plots.  (See ‘pllegend’ (*note pllegend; Plot legend using
discretely annotated filled boxes; lines; and/or lines of symbols::) for
similar functionality for creating legends with discrete elements).  The
arguments of plcolorbar provide control over the location and size of
the color bar as well as the location and characteristics of the
elements (most of which are optional) within that color bar.  The
resulting color bar is clipped at the boundaries of the current subpage.
(N.B. the adopted coordinate system used for some of the parameters is
defined in the documentation of the ‘‘position’’ parameter.)

‘p_colorbar_width’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the labelled and decorated color bar width in
     adopted coordinates.

‘p_colorbar_height’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the labelled and decorated color bar height in
     adopted coordinates.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     ‘‘opt’’ contains bits controlling the overall color bar.  The
     orientation (direction of the maximum value) of the color bar is
     specified with ‘PL_ORIENT_RIGHT’, ‘PL_ORIENT_TOP’,
     ‘PL_ORIENT_LEFT’, or ‘PL_ORIENT_BOTTOM’.  If none of these bits are
     specified, the default orientation is toward the top if the
     colorbar is placed on the left or right of the viewport or toward
     the right if the colorbar is placed on the top or bottom of the
     viewport.  If the ‘PL_COLORBAR_BACKGROUND’ bit is set, plot a
     (semitransparent) background for the color bar.  If the
     ‘PL_COLORBAR_BOUNDING_BOX’ bit is set, plot a bounding box for the
     color bar.  The type of color bar must be specified with one of
     ‘PL_COLORBAR_IMAGE’, ‘PL_COLORBAR_SHADE’, or
     ‘PL_COLORBAR_GRADIENT’.  If more than one of those bits is set only
     the first one in the above list is honored.  The position of the
     (optional) label/title can be specified with ‘PL_LABEL_RIGHT’,
     ‘PL_LABEL_TOP’, ‘PL_LABEL_LEFT’, or ‘PL_LABEL_BOTTOM’.  If no label
     position bit is set then no label will be drawn.  If more than one
     of this list of bits is specified, only the first one on the list
     is honored.  End-caps for the color bar can added with
     ‘PL_COLORBAR_CAP_LOW’ and ‘PL_COLORBAR_CAP_HIGH’.  If a particular
     color bar cap option is not specified then no cap will be drawn for
     that end.  As a special case for ‘PL_COLORBAR_SHADE’, the option
     ‘PL_COLORBAR_SHADE_LABEL’ can be specified.  If this option is
     provided then any tick marks and tick labels will be placed at the
     breaks between shaded segments.  TODO: This should be expanded to
     support custom placement of tick marks and tick labels at custom
     value locations for any color bar type.

‘position’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     ‘‘position’’ contains bits which control the overall position of
     the color bar and the definition of the adopted coordinates used
     for positions just like what is done for the position argument for
     ‘pllegend’ (*note pllegend; Plot legend using discretely annotated
     filled boxes; lines; and/or lines of symbols::).  However, note
     that the defaults for the position bits (see below) are different
     than the ‘pllegend’ (*note pllegend; Plot legend using discretely
     annotated filled boxes; lines; and/or lines of symbols::) case.
     The combination of the ‘PL_POSITION_LEFT’, ‘PL_POSITION_RIGHT’,
     ‘PL_POSITION_TOP’, ‘PL_POSITION_BOTTOM’, ‘PL_POSITION_INSIDE’, and
     ‘PL_POSITION_OUTSIDE’ bits specifies one of the 16 possible
     standard positions (the 4 corners and centers of the 4 sides for
     both the inside and outside cases) of the color bar relative to the
     adopted coordinate system.  The corner positions are specified by
     the appropriate combination of two of the ‘PL_POSITION_LEFT’,
     ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, and ‘PL_POSITION_BOTTOM’
     bits while the sides are specified by a single value of one of
     those bits.  The adopted coordinates are normalized viewport
     coordinates if the ‘PL_POSITION_VIEWPORT’ bit is set or normalized
     subpage coordinates if the ‘PL_POSITION_SUBPAGE’ bit is set.
     Default position bits: If none of ‘PL_POSITION_LEFT’,
     ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, or ‘PL_POSITION_BOTTOM’ are
     set, then use ‘PL_POSITION_RIGHT’.  If neither of
     ‘PL_POSITION_INSIDE’ or ‘PL_POSITION_OUTSIDE’ is set, use
     ‘PL_POSITION_OUTSIDE’.  If neither of ‘PL_POSITION_VIEWPORT’ or
     ‘PL_POSITION_SUBPAGE’ is set, use ‘PL_POSITION_VIEWPORT’.

‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     X offset of the color bar position in adopted coordinates from the
     specified standard position of the color bar.  For positive x, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard left
     or right positions if the
     ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in
     ‘‘position’’.  For the standard top or bottom positions, the
     direction of motion is toward positive X.

‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Y offset of the color bar position in adopted coordinates from the
     specified standard position of the color bar.  For positive y, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard top
     or bottom positions if the
     ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in
     ‘‘position’’.  For the standard left or right positions, the
     direction of motion is toward positive Y.

‘x_length’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Length of the body of the color bar in the X direction in adopted
     coordinates.

‘y_length’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Length of the body of the color bar in the Y direction in adopted
     coordinates.

‘bg_color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The cmap0 color of the background for the color bar
     (‘PL_COLORBAR_BACKGROUND’).

‘bb_color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The cmap0 color of the bounding-box line for the color bar
     (‘PL_COLORBAR_BOUNDING_BOX’).

‘bb_style’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The ‘pllsty’ (*note pllsty; Select line style::) style number for
     the bounding-box line for the color bar (‘PL_COLORBAR_BACKGROUND’).

‘low_cap_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The cmap1 color of the low-end color bar cap, if it is drawn
     (‘PL_COLORBAR_CAP_LOW’).

‘high_cap_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The cmap1 color of the high-end color bar cap, if it is drawn
     (‘PL_COLORBAR_CAP_HIGH’).

‘cont_color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The cmap0 contour color for ‘PL_COLORBAR_SHADE’ plots.  This is
     passed directly to ‘plshades’ (*note plshades; Shade regions on the
     basis of value::), so it will be interpreted according to the
     design of ‘plshades’ (*note plshades; Shade regions on the basis of
     value::).

‘cont_width’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Contour width for ‘PL_COLORBAR_SHADE’ plots.  This is passed
     directly to ‘plshades’ (*note plshades; Shade regions on the basis
     of value::), so it will be interpreted according to the design of
     ‘plshades’ (*note plshades; Shade regions on the basis of value::).

‘n_labels’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of labels to place around the color bar.

‘label_opts’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector of options for each of ‘n_labels’ labels.

‘labels’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input)
     A vector of ‘n_labels’ UTF-8 character strings containing the
     labels for the color bar.  Ignored if no label position is
     specified with one of the ‘PL_COLORBAR_LABEL_RIGHT’,
     ‘PL_COLORBAR_LABEL_TOP’, ‘PL_COLORBAR_LABEL_LEFT’, or
     ‘PL_COLORBAR_LABEL_BOTTOM’ bits in the corresponding label_opts
     field.

‘n_axes’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of axis definitions provided.  This value must be greater
     than 0.  It is typically 1 (numerical axis labels are provided for
     one of the long edges of the color bar), but it can be larger if
     multiple numerical axis labels for the long edges of the color bar
     are desired.

‘axis_opts’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input)
     A vector of ‘n_axes’ ascii character strings containing options
     (interpreted as for ‘plbox’ (*note plbox; Draw a box with axes;
     etc::)) for the color bar's axis definitions.

‘ticks’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector of n_axes values of the spacing of the major tick marks
     (interpreted as for ‘plbox’ (*note plbox; Draw a box with axes;
     etc::)) for the color bar's axis definitions.

‘sub_ticks’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector of n_axes values of the number of subticks (interpreted as
     for ‘plbox’ (*note plbox; Draw a box with axes; etc::)) for the
     color bar's axis definitions.

‘n_values’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing the number of elements in each of the
     ‘‘n_axes’’ rows of the ‘‘values’’ matrix.

‘values’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing the numeric values for the data range
     represented by the color bar.  For a row index of ‘‘i_axis’’ (where
     0 < ‘‘i_axis’’ < ‘‘n_axes’’), the number of elements in the row is
     specified by ‘‘n_values’’[‘‘i_axis’’].  For ‘PL_COLORBAR_IMAGE’ and
     ‘PL_COLORBAR_GRADIENT’ the number of elements is 2, and the
     corresponding row elements of the ‘‘values’’ matrix are the minimum
     and maximum value represented by the colorbar.  For
     ‘PL_COLORBAR_SHADE’, the number and values of the elements of a row
     of the ‘‘values’’ matrix is interpreted the same as the ‘‘nlevel’’
     and ‘‘clevel’’ arguments of ‘plshades’ (*note plshades; Shade
     regions on the basis of value::).

   Redacted form: ‘plcolorbar(p_colorbar_width, p_colorbar_height, opt,
position, x, y, x_length, y_length, bg_color, bb_color, bb_style,
low_cap_color, high_cap_color, cont_color, cont_width, label_opts,
labels, axis_opts, ticks, sub_ticks, values)’

   This function is used in examples 16 and 33.


File: plplotdoc.info,  Node: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Next: plcont; Contour plot,  Prev: plcolorbar; Plot color bar for image; shade or gradient plots,  Up: The Common API for PLplot

17.16 plconfigtime: Configure the transformation between continuous and broken-down time for the current stream
===============================================================================================================

     plconfigtime (scale, offset1, offset2, ccontrol, ifbtime_offset,
     year, month, day, hour, min, sec);

   Configure the transformation between continuous and broken-down time
for the current stream.  This transformation is used by both ‘ plbtime’
(*note plbtime; Calculate broken-down time from continuous time for the
current stream::) and ‘plctime’ (*note plctime; Calculate continuous
time from broken-down time for the current stream::).

‘scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The number of days per continuous time unit.  As a special case, if
     ‘scale’ is 0., then all other arguments are ignored, and the result
     (the default used by PLplot) is the equivalent of a call to
     plconfigtime(1./86400., 0., 0., 0x0, 1, 1970, 0, 1, 0, 0, 0.).
     That is, for this special case broken-down time is calculated with
     the proleptic Gregorian calendar with no leap seconds inserted, and
     the continuous time is defined as the number of seconds since the
     Unix epoch of 1970-01-01T00:00:00Z.

‘offset1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     If ‘ifbtime_offset’ is true, the parameters ‘offset1’ and ‘offset2’
     are completely ignored.  Otherwise, the sum of these parameters
     (with units in days) specify the epoch of the continuous time
     relative to the MJD epoch corresponding to the Gregorian calendar
     date of 1858-11-17T00:00:00Z or JD = 2400000.5.  Two PLFLT numbers
     are used to specify the origin to allow users (by specifying
     ‘offset1’ as an integer that can be exactly represented by a
     floating-point variable and specifying ‘offset2’ as a number in the
     range from 0.  to 1) the chance to minimize the numerical errors of
     the continuous time representation.

‘offset2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     See documentation of ‘offset1’.

‘ccontrol’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     ‘ccontrol’ contains bits controlling the transformation.  If the
     0x1 bit is set, then the proleptic Julian calendar is used for
     broken-down time rather than the proleptic Gregorian calendar.  If
     the 0x2 bit is set, then leap seconds that have been historically
     used to define UTC are inserted into the broken-down time.  Other
     possibilities for additional control bits for ccontrol exist such
     as making the historical time corrections in the broken-down time
     corresponding to ET (ephemeris time) or making the (slightly
     non-constant) corrections from international atomic time (TAI) to
     what astronomers define as terrestrial time (TT). But those
     additional possibilities have not been implemented yet in the
     qsastime library (one of the PLplot utility libraries).

‘ifbtime_offset’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     ‘ifbtime_offset’ controls how the epoch of the continuous time
     scale is specified by the user.  If ‘ifbtime_offset’ is false, then
     ‘offset1’ and ‘offset2’ are used to specify the epoch, and the
     following broken-down time parameters are completely ignored.  If
     ‘ifbtime_offset’ is true, then ‘offset1’ and ‘offset2’ are
     completely ignored, and the following broken-down time parameters
     are used to specify the epoch.

‘year’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Year of epoch.

‘month’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Month of epoch in range from 0 (January) to 11 (December).

‘day’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Day of epoch in range from 1 to 31.

‘hour’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Hour of epoch in range from 0 to 23

‘min’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Minute of epoch in range from 0 to 59.

‘sec’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Second of epoch in range from 0.  to 60.

   Redacted form:

   • General: ‘plconfigtime(scale, offset1, offset2, ccontrol,
     ifbtime_offset, year, month, day, hour, min, sec)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plcont; Contour plot,  Next: plcpstrm; Copy state parameters from the reference stream to the current stream,  Prev: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream,  Up: The Common API for PLplot

17.17 plcont: Contour plot
==========================

     plcont (f, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr,
     pltr_data);

   Draws a contour plot of the data in ‘‘f’[‘nx’][‘ny’]’, using the
‘‘nlevel’’ contour levels specified by ‘‘clevel’’.  Only the region of
the matrix from ‘‘kx’’ to ‘‘lx’’ and from ‘‘ky’’ to ‘‘ly’’ is plotted
out where all these index ranges are interpreted as one-based for
historical reasons.  A transformation routine pointed to by ‘‘pltr’’
with a generic pointer ‘‘pltr_data’’ for additional data required by the
transformation routine is used to map indices within the matrix to the
world coordinates.

‘f’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing data to be contoured.

‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The dimensions of the matrix ‘‘f’’.

‘kx, lx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Range of ‘x’ indices to consider where ‘0 ≤ kx-1 < lx-1 < nx’.
     Values of ‘kx’ and ‘lx’ are one-based rather than zero-based for
     historical backwards-compatibility reasons.

‘ky, ly’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Range of ‘y’ indices to consider where ‘0 ≤ ky-1 < ly-1 < ny’.
     Values of ‘ky’ and ‘ly’ are one-based rather than zero-based for
     historical backwards-compatibility reasons.

‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector specifying the levels at which to draw contours.

‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of contour levels to draw.

‘pltr’ (‘‘PLTRANSFORM_callback’ (*note PLTRANSFORM_callback-type::)’, input)
     A callback function that defines the transformation between the
     zero-based indices of the matrix ‘‘f’’ and the world coordinates.

     For the C case, transformation functions are provided in the PLplot
     library: ‘pltr0’ (*note pltr0; Identity transformation for matrix
     index to world coordinate mapping::) for the identity mapping, and
     ‘pltr1’ (*note pltr1; Linear interpolation for matrix index to
     world coordinate mapping using singly dimensioned coordinate
     arrays::) and ‘pltr2’ (*note pltr2; Linear interpolation for grid
     to world mapping using doubly dimensioned coordinate arrays
     [row-major order as per normal C 2d arrays]::) for arbitrary
     mappings respectively defined by vectors and matrices.  In
     addition, C callback routines for the transformation can be
     supplied by the user such as the ‘mypltr’ function in
     ‘examples/c/x09c.c’ which provides a general linear transformation
     between index coordinates and world coordinates.

     For languages other than C you should consult *note Supported
     computer languages: Supported computer languages. for the details
     concerning how ‘PLTRANSFORM_callback’ (*note
     PLTRANSFORM_callback-type::) arguments are interfaced.  However, in
     general, a particular pattern of callback-associated arguments such
     as a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’ vectors; or ‘xg’
     and ‘yg’ matrices are respectively interfaced to a
     linear-transformation routine similar to the above ‘mypltr’
     function; ‘pltr1’ (*note pltr1; Linear interpolation for matrix
     index to world coordinate mapping using singly dimensioned
     coordinate arrays::); and ‘pltr2’ (*note pltr2; Linear
     interpolation for grid to world mapping using doubly dimensioned
     coordinate arrays [row-major order as per normal C 2d arrays]::).
     Furthermore, some of our more sophisticated bindings (see, e.g.,
     *note Fortran Language::) support native language callbacks for
     handling index to world-coordinate transformations.  Examples of
     these various approaches are given in ‘examples/<language>x09*’,
     ‘examples/<language>x16*’, ‘examples/<language>x20*’,
     ‘examples/<language>x21*’, and ‘examples/<language>x22*’, for all
     our supported languages.

‘pltr_data’ (‘‘PLPointer’ (*note PLPointer-type::)’, input)
     Extra parameter to help pass information to ‘pltr0’ (*note pltr0;
     Identity transformation for matrix index to world coordinate
     mapping::), ‘pltr1’ (*note pltr1; Linear interpolation for matrix
     index to world coordinate mapping using singly dimensioned
     coordinate arrays::), ‘pltr2’ (*note pltr2; Linear interpolation
     for grid to world mapping using doubly dimensioned coordinate
     arrays [row-major order as per normal C 2d arrays]::), or whatever
     callback routine that is externally supplied.

   Redacted form: ‘plcont(f, kx, lx, ky, ly, clevel, pltr, pltr_data)’
where (see above discussion) the ‘pltr, pltr_data’ callback arguments
are sometimes replaced by a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’
vectors; or ‘xg’ and ‘yg’ matrices.

   This function is used in examples 9, 14, 16, and 22.


File: plplotdoc.info,  Node: plcpstrm; Copy state parameters from the reference stream to the current stream,  Next: plctime; Calculate continuous time from broken-down time for the current stream,  Prev: plcont; Contour plot,  Up: The Common API for PLplot

17.18 plcpstrm: Copy state parameters from the reference stream to the current stream
=====================================================================================

     plcpstrm (iplsr, flags);

   Copies state parameters from the reference stream to the current
stream.  Tell driver interface to map device coordinates unless ‘‘flags’
== 1’.

   This function is used for making save files of selected plots (e.g.
from the TK driver).  After initializing, you can get a copy of the
current plot to the specified device by switching to this stream and
issuing a ‘plcpstrm’ (*note plcpstrm; Copy state parameters from the
reference stream to the current stream::) and a ‘plreplot’ (*note
plreplot; Replays contents of plot buffer to current device/file::),
with calls to ‘plbop’ (*note plbop; Begin a new page::) and ‘pleop’
(*note pleop; Eject current page::) as appropriate.  The plot buffer
must have previously been enabled (done automatically by some display
drivers, such as X).

‘iplsr’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of reference stream.

‘flags’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     If ‘‘flags’’ is set to true the device coordinates are _not_ copied
     from the reference to current stream.

   Redacted form: ‘plcpstrm(iplsr, flags)’

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plctime; Calculate continuous time from broken-down time for the current stream,  Next: plend; End plotting session,  Prev: plcpstrm; Copy state parameters from the reference stream to the current stream,  Up: The Common API for PLplot

17.19 plctime: Calculate continuous time from broken-down time for the current stream
=====================================================================================

     plctime (year, month, day, hour, min, sec, ctime);

   Calculate continuous time, ‘‘ctime’’, from broken-down time for the
current stream.  The broken-down time is specified by the following
parameters: ‘‘year’’, ‘‘month’’, ‘‘day’’, ‘‘hour’’, ‘‘min’’, and
‘‘sec’’.  This function is the inverse of ‘ plbtime’ (*note plbtime;
Calculate broken-down time from continuous time for the current
stream::).

   The PLplot definition of broken-down time is a calendar time that
completely ignores all time zone offsets, i.e., it is the user's
responsibility to apply those offsets (if so desired) before using the
PLplot time API. By default broken-down time is defined using the
proleptic Gregorian calendar without the insertion of leap seconds and
continuous time is defined as the number of seconds since the Unix epoch
of 1970-01-01T00:00:00Z. However, other definitions of broken-down and
continuous time are possible, see ‘plconfigtime’ (*note plconfigtime;
Configure the transformation between continuous and broken-down time for
the current stream::) which specifies that transformation for the
current stream.

‘year’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Input year.

‘month’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Input month in range from 0 (January) to 11 (December).

‘day’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Input day in range from 1 to 31.

‘hour’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Input hour in range from 0 to 23

‘min’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Input minute in range from 0 to 59.

‘sec’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Input second in range from 0.  to 60.

‘ctime’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the continuous time calculated from the
     broken-down time specified by the previous parameters.

   Redacted form:

   • General: ‘plctime(year, month, day, hour, min, sec, ctime)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plend; End plotting session,  Next: plend1; End plotting session for current stream,  Prev: plctime; Calculate continuous time from broken-down time for the current stream,  Up: The Common API for PLplot

17.20 plend: End plotting session
=================================

     plend ();

   Ends a plotting session, tidies up all the output files, switches
interactive devices back into text mode and frees up any memory that was
allocated.  Must be called before end of program.

   By default, PLplot's interactive devices (Xwin, TK, etc.)  go into a
wait state after a call to plend or other functions which trigger the
end of a plot page.  To avoid this, use the ‘plspause’ (*note plspause;
Set the pause [on end-of-page] status::) function.

   Redacted form: ‘plend()’

   This function is used in all of the examples.


File: plplotdoc.info,  Node: plend1; End plotting session for current stream,  Next: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Prev: plend; End plotting session,  Up: The Common API for PLplot

17.21 plend1: End plotting session for current stream
=====================================================

     plend1 ();

   Ends a plotting session for the current output stream only.  See
‘plsstrm’ (*note plsstrm; Set current output stream::) for more info.

   Redacted form: ‘plend1()’

   This function is used in examples 1 and 20.


File: plplotdoc.info,  Node: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Next: plenv; Set up standard window and draw box,  Prev: plend1; End plotting session for current stream,  Up: The Common API for PLplot

17.22 plenv0: Same as ‘plenv’ but if in multiplot mode does not advance the subpage, instead clears it
======================================================================================================

     plenv0 (xmin, xmax, ymin, ymax, just, axis);

   Sets up plotter environment for simple graphs by calling ‘pladv’
(*note pladv; Advance the [sub-]page::) and setting up viewport and
window to sensible default values.  ‘plenv0’ (*note plenv0; Same as
plenv but if in multiplot mode does not advance the subpage; instead
clears it::) leaves a standard margin (left-hand margin of eight
character heights, and a margin around the other three sides of five
character heights) around most graphs for axis labels and a title.  When
these defaults are not suitable, use the individual routines ‘plvpas’
(*note plvpas; Specify viewport using coordinates and aspect ratio::),
‘plvpor’ (*note plvpor; Specify viewport using normalized subpage
coordinates::), or ‘plvasp’ (*note plvasp; Specify viewport using aspect
ratio only::) for setting up the viewport, ‘plwind’ (*note plwind;
Specify window::) for defining the window, and ‘plbox’ (*note plbox;
Draw a box with axes; etc::) for drawing the box.

‘xmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of x at left-hand edge of window (in world coordinates).

‘xmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of x at right-hand edge of window (in world coordinates).

‘ymin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of y at bottom edge of window (in world coordinates).

‘ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of y at top edge of window (in world coordinates).

‘just’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Controls how the axes will be scaled:

        • ‘-1’: the scales will not be set, the user must set up the
          scale before calling ‘plenv0’ (*note plenv0; Same as plenv but
          if in multiplot mode does not advance the subpage; instead
          clears it::) using ‘plsvpa’ (*note plsvpa; Specify viewport in
          absolute coordinates::), ‘plvasp’ (*note plvasp; Specify
          viewport using aspect ratio only::) or other.

        • ‘0’: the x and y axes are scaled independently to use as much
          of the screen as possible.

        • ‘1’: the scales of the x and y axes are made equal.

        • ‘2’: the axis of the x and y axes are made equal, and the plot
          box will be square.

‘axis’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Controls drawing of the box around the plot:

        • ‘-2’: draw no box, no tick marks, no numeric tick labels, no
          axes.

        • ‘-1’: draw box only.

        • ‘0’: draw box, ticks, and numeric tick labels.

        • ‘1’: also draw coordinate axes at ‘x=0’ and ‘y=0’.

        • ‘2’: also draw a grid at major tick positions in both
          coordinates.

        • ‘3’: also draw a grid at minor tick positions in both
          coordinates.

        • ‘10’: same as 0 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘11’: same as 1 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘12’: same as 2 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘13’: same as 3 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘20’: same as 0 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘21’: same as 1 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘22’: same as 2 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘23’: same as 3 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘30’: same as 0 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘31’: same as 1 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘32’: same as 2 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘33’: same as 3 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘40’: same as 0 except date / time ‘x’ labels.

        • ‘41’: same as 1 except date / time ‘x’ labels.

        • ‘42’: same as 2 except date / time ‘x’ labels.

        • ‘43’: same as 3 except date / time ‘x’ labels.

        • ‘50’: same as 0 except date / time ‘y’ labels.

        • ‘51’: same as 1 except date / time ‘y’ labels.

        • ‘52’: same as 2 except date / time ‘y’ labels.

        • ‘53’: same as 3 except date / time ‘y’ labels.

        • ‘60’: same as 0 except date / time ‘x’ and ‘y’ labels.

        • ‘61’: same as 1 except date / time ‘x’ and ‘y’ labels.

        • ‘62’: same as 2 except date / time ‘x’ and ‘y’ labels.

        • ‘63’: same as 3 except date / time ‘x’ and ‘y’ labels.

        • ‘70’: same as 0 except custom ‘x’ and ‘y’ labels.

        • ‘71’: same as 1 except custom ‘x’ and ‘y’ labels.

        • ‘72’: same as 2 except custom ‘x’ and ‘y’ labels.

        • ‘73’: same as 3 except custom ‘x’ and ‘y’ labels.

   Redacted form: ‘plenv0(xmin, xmax, ymin, ymax, just, axis)’

   This function is used in example 21.


File: plplotdoc.info,  Node: plenv; Set up standard window and draw box,  Next: pleop; Eject current page,  Prev: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it,  Up: The Common API for PLplot

17.23 plenv: Set up standard window and draw box
================================================

     plenv (xmin, xmax, ymin, ymax, just, axis);

   Sets up plotter environment for simple graphs by calling ‘pladv’
(*note pladv; Advance the [sub-]page::) and setting up viewport and
window to sensible default values.  ‘plenv’ (*note plenv; Set up
standard window and draw box::) leaves a standard margin (left-hand
margin of eight character heights, and a margin around the other three
sides of five character heights) around most graphs for axis labels and
a title.  When these defaults are not suitable, use the individual
routines ‘plvpas’ (*note plvpas; Specify viewport using coordinates and
aspect ratio::), ‘plvpor’ (*note plvpor; Specify viewport using
normalized subpage coordinates::), or ‘plvasp’ (*note plvasp; Specify
viewport using aspect ratio only::) for setting up the viewport,
‘plwind’ (*note plwind; Specify window::) for defining the window, and
‘plbox’ (*note plbox; Draw a box with axes; etc::) for drawing the box.

‘xmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of x at left-hand edge of window (in world coordinates).

‘xmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of x at right-hand edge of window (in world coordinates).

‘ymin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of y at bottom edge of window (in world coordinates).

‘ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of y at top edge of window (in world coordinates).

‘just’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Controls how the axes will be scaled:

        • ‘-1’: the scales will not be set, the user must set up the
          scale before calling ‘plenv’ (*note plenv; Set up standard
          window and draw box::) using ‘plsvpa’ (*note plsvpa; Specify
          viewport in absolute coordinates::), ‘plvasp’ (*note plvasp;
          Specify viewport using aspect ratio only::) or other.

        • ‘0’: the x and y axes are scaled independently to use as much
          of the screen as possible.

        • ‘1’: the scales of the x and y axes are made equal.

        • ‘2’: the axis of the x and y axes are made equal, and the plot
          box will be square.

‘axis’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Controls drawing of the box around the plot:

        • ‘-2’: draw no box, no tick marks, no numeric tick labels, no
          axes.

        • ‘-1’: draw box only.

        • ‘0’: draw box, ticks, and numeric tick labels.

        • ‘1’: also draw coordinate axes at ‘x=0’ and ‘y=0’.

        • ‘2’: also draw a grid at major tick positions in both
          coordinates.

        • ‘3’: also draw a grid at minor tick positions in both
          coordinates.

        • ‘10’: same as 0 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘11’: same as 1 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘12’: same as 2 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘13’: same as 3 except logarithmic ‘x’ tick marks.  (The ‘x’
          data have to be converted to logarithms separately.)

        • ‘20’: same as 0 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘21’: same as 1 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘22’: same as 2 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘23’: same as 3 except logarithmic ‘y’ tick marks.  (The ‘y’
          data have to be converted to logarithms separately.)

        • ‘30’: same as 0 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘31’: same as 1 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘32’: same as 2 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘33’: same as 3 except logarithmic ‘x’ and ‘y’ tick marks.
          (The ‘x’ and ‘y’ data have to be converted to logarithms
          separately.)

        • ‘40’: same as 0 except date / time ‘x’ labels.

        • ‘41’: same as 1 except date / time ‘x’ labels.

        • ‘42’: same as 2 except date / time ‘x’ labels.

        • ‘43’: same as 3 except date / time ‘x’ labels.

        • ‘50’: same as 0 except date / time ‘y’ labels.

        • ‘51’: same as 1 except date / time ‘y’ labels.

        • ‘52’: same as 2 except date / time ‘y’ labels.

        • ‘53’: same as 3 except date / time ‘y’ labels.

        • ‘60’: same as 0 except date / time ‘x’ and ‘y’ labels.

        • ‘61’: same as 1 except date / time ‘x’ and ‘y’ labels.

        • ‘62’: same as 2 except date / time ‘x’ and ‘y’ labels.

        • ‘63’: same as 3 except date / time ‘x’ and ‘y’ labels.

        • ‘70’: same as 0 except custom ‘x’ and ‘y’ labels.

        • ‘71’: same as 1 except custom ‘x’ and ‘y’ labels.

        • ‘72’: same as 2 except custom ‘x’ and ‘y’ labels.

        • ‘73’: same as 3 except custom ‘x’ and ‘y’ labels.

   Redacted form: ‘plenv(xmin, xmax, ymin, ymax, just, axis)’

   This function is used in example 1,3,9,13,14,19-22,29.


File: plplotdoc.info,  Node: pleop; Eject current page,  Next: plerrx; Draw error bars in x direction,  Prev: plenv; Set up standard window and draw box,  Up: The Common API for PLplot

17.24 pleop: Eject current page
===============================

     pleop ();

   Clears the graphics screen of an interactive device, or ejects a page
on a plotter.  See ‘plbop’ (*note plbop; Begin a new page::) for more
information.

   Redacted form: ‘pleop()’

   This function is used in example 2,14.


File: plplotdoc.info,  Node: plerrx; Draw error bars in x direction,  Next: plerry; Draw error bars in the y direction,  Prev: pleop; Eject current page,  Up: The Common API for PLplot

17.25 plerrx: Draw error bars in x direction
============================================

     plerrx (n, xmin, xmax, y);

   Draws a set of ‘‘n’’ error bars in x direction, the ‘i’'th error bar
extending from ‘‘xmin’[i]’ to ‘‘xmax’[i]’ at y coordinate ‘‘y’[i]’.  The
terminals of the error bars are of length equal to the minor tick length
(settable using ‘plsmin’ (*note plsmin; Set length of minor ticks::)).

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of error bars to draw.

‘xmin’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of the left-hand endpoints of
     the error bars.

‘xmax’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of the right-hand endpoints
     of the error bars.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of the error bars.

   Redacted form:

   • General: ‘plerrx(xmin, ymax, y)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plerry; Draw error bars in the y direction,  Next: plfamadv; Advance to the next family file on the next new page,  Prev: plerrx; Draw error bars in x direction,  Up: The Common API for PLplot

17.26 plerry: Draw error bars in the y direction
================================================

     plerry (n, x, ymin, ymax);

   Draws a set of ‘‘n’’ error bars in the y direction, the ‘i’'th error
bar extending from ‘‘ymin’[i]’ to ‘‘ymax’[i]’ at x coordinate ‘‘x’[i]’.
The terminals of the error bars are of length equal to the minor tick
length (settable using ‘plsmin’ (*note plsmin; Set length of minor
ticks::)).

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of error bars to draw.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of the error bars.

‘ymin’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of the lower endpoints of the
     error bars.

‘ymax’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of the upper endpoints of the
     error bars.

   Redacted form:

   • General: ‘plerry(x, ymin, ymax)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plfamadv; Advance to the next family file on the next new page,  Next: plfill; Draw filled polygon,  Prev: plerry; Draw error bars in the y direction,  Up: The Common API for PLplot

17.27 plfamadv: Advance to the next family file on the next new page
====================================================================

     plfamadv ();

   Advance to the next family file on the next new page.

   Redacted form: ‘plfamadv()’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plfill; Draw filled polygon,  Next: plfill3; Draw filled polygon in 3D,  Prev: plfamadv; Advance to the next family file on the next new page,  Up: The Common API for PLplot

17.28 plfill: Draw filled polygon
=================================

     plfill (n, x, y);

   Fills the polygon defined by the ‘‘n’’ points ‘(‘x’[i], ‘y’[i])’
using the pattern defined by ‘plpsty’ (*note plpsty; Select area fill
pattern::) or ‘plpat’ (*note plpat; Set area line fill pattern::).  The
default fill style is a solid fill.  The routine will automatically
close the polygon between the last and first vertices.  If multiple
closed polygons are passed in ‘‘x’’ and ‘‘y’’ then ‘plfill’ (*note
plfill; Draw filled polygon::) will fill in between them.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of vertices in polygon.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of vertices.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of vertices.

   Redacted form: ‘plfill(x,y)’

   This function is used in examples 12, 13, 15, 16, 21, 24, and 25.


File: plplotdoc.info,  Node: plfill3; Draw filled polygon in 3D,  Next: plflush; Flushes the output stream,  Prev: plfill; Draw filled polygon,  Up: The Common API for PLplot

17.29 plfill3: Draw filled polygon in 3D
========================================

     plfill3 (n, x, y, z);

   Fills the 3D polygon defined by the ‘‘n’’ points in the ‘‘x’’, ‘‘y’’,
and ‘‘z’’ vectors using the pattern defined by ‘plpsty’ (*note plpsty;
Select area fill pattern::) or ‘plpat’ (*note plpat; Set area line fill
pattern::).  The routine will automatically close the polygon between
the last and first vertices.  If multiple closed polygons are passed in
‘‘x’’, ‘‘y’’, and ‘‘z’’ then ‘plfill3’ (*note plfill3; Draw filled
polygon in 3D::) will fill in between them.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of vertices in polygon.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of vertices.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of vertices.

‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the z coordinates of vertices.

   Redacted form:

   • General: ‘plfill3(x, y, z)’

   This function is used in example 15.


File: plplotdoc.info,  Node: plflush; Flushes the output stream,  Next: plfont; Set font,  Prev: plfill3; Draw filled polygon in 3D,  Up: The Common API for PLplot

17.30 plflush: Flushes the output stream
========================================

     plflush ();

   Flushes the output stream.  Use sparingly, if at all.

   Redacted form: ‘plflush()’

   This function is used in examples 1 and 14.


File: plplotdoc.info,  Node: plfont; Set font,  Next: plfontld; Load Hershey fonts,  Prev: plflush; Flushes the output stream,  Up: The Common API for PLplot

17.31 plfont: Set font
======================

     plfont (ifont);

   Sets the font used for subsequent text and symbols.  For devices that
still use Hershey fonts this routine has no effect unless the Hershey
fonts with extended character set are loaded (see ‘plfontld’ (*note
plfontld; Load Hershey fonts::)).  For unicode-aware devices that use
system fonts instead of Hershey fonts, this routine calls the ‘plsfci’
(*note plsfci; Set FCI [font characterization integer]::) routine with
argument set up appropriately for the various cases below.  However,
this method of specifying the font for unicode-aware devices is
deprecated, and the much more flexible method of calling ‘plsfont’
(*note plsfont; Set family; style and weight of the current font::)
directly is recommended instead (where ‘plsfont’ (*note plsfont; Set
family; style and weight of the current font::) provides a user-friendly
interface to ‘plsfci’ (*note plsfci; Set FCI [font characterization
integer]::)),

‘ifont’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Specifies the font:

        • ‘1’: Sans serif font (simplest and fastest)

        • ‘2’: Serif font

        • ‘3’: Italic font

        • ‘4’: Script font

   Redacted form: ‘plfont(ifont)’

   This function is used in examples 1, 2, 4, 7, 13, 24, and 26.


File: plplotdoc.info,  Node: plfontld; Load Hershey fonts,  Next: plGetCursor; Wait for graphics input event and translate to world coordinates_,  Prev: plfont; Set font,  Up: The Common API for PLplot

17.32 plfontld: Load Hershey fonts
==================================

     plfontld (fnt);

   Loads the Hershey fonts used for text and symbols.  This routine may
be called before or after initializing PLplot.  If not explicitly called
before PLplot initialization, then by default that initialization loads
Hershey fonts with the extended character set.  This routine only has a
practical effect for devices that still use Hershey fonts (as opposed to
modern devices that use unicode-aware system fonts instead of Hershey
fonts).

‘fnt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Specifies the type of Hershey fonts to load.  A zero value
     specifies Hershey fonts with the standard character set and a
     non-zero value (the default assumed if ‘plfontld’ (*note plfontld;
     Load Hershey fonts::) is never called) specifies Hershey fonts with
     the extended character set.

   Redacted form: ‘plfontld(fnt)’

   This function is used in examples 1 and 7.


File: plplotdoc.info,  Node: plGetCursor; Wait for graphics input event and translate to world coordinates_,  Next: plgchr; Get character default height and current [scaled] height,  Prev: plfontld; Load Hershey fonts,  Up: The Common API for PLplot

17.33 plGetCursor: Wait for graphics input event and translate to world coordinates.
====================================================================================

     PLINT plGetCursor (gin);

   Wait for graphics input event and translate to world coordinates.
Returns 0 if no translation to world coordinates is possible.

‘gin’ (‘‘PLGraphicsIn’ (*note PLGraphicsIn; PLplot Graphics Input structure::) *’, output)
     Pointer to ‘PLGraphicsIn’ (*note PLGraphicsIn; PLplot Graphics
     Input structure::) structure which will contain the output.  The
     structure is not allocated by the routine and must exist before the
     function is called.

   This function returns 1 on success and 0 if no translation to world
coordinates is possible.

   Redacted form: ‘plGetCursor(gin)’

   This function is used in examples 1 and 20.


File: plplotdoc.info,  Node: plgchr; Get character default height and current [scaled] height,  Next: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Prev: plGetCursor; Wait for graphics input event and translate to world coordinates_,  Up: The Common API for PLplot

17.34 plgchr: Get character default height and current (scaled) height
======================================================================

     plgchr (p_def, p_ht);

   Get character default height and current (scaled) height.

‘p_def’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the default character height (mm).

‘p_ht’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the scaled character height (mm).

   Redacted form: ‘plgchr(p_def, p_ht)’

   This function is used in example 23.


File: plplotdoc.info,  Node: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Next: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Prev: plgchr; Get character default height and current [scaled] height,  Up: The Common API for PLplot

17.35 plgcmap1_range: Get the cmap1 argument range for continuous color plots
=============================================================================

     plgcmap1_range (min_color, max_color);

   Get the cmap1 argument range for continuous color plots.  (Use
‘plscmap1_range’ (*note plscmap1_range; Set the cmap1 argument range for
continuous color plots::) to set the cmap1 argument range.)

‘min_color’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the current minimum cmap1 argument.

‘max_color’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the current maximum cmap1 argument.

   Redacted form: ‘plgcmap1_range(min_color, max_color)’

   This function is currently not used in any example.


File: plplotdoc.info,  Node: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Next: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0,  Prev: plgcmap1_range; Get the cmap1 argument range for continuous color plots,  Up: The Common API for PLplot

17.36 plgcol0: Returns 8-bit RGB values for given color index from cmap0
========================================================================

     plgcol0 (icol0, r, g, b);

   Returns 8-bit RGB values (0-255) for given color from cmap0 (see
*note Color Map0::).  Values are negative if an invalid color id is
given.

‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Index of desired cmap0 color.

‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the 8-bit red value.

‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the 8-bit green value.

‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the 8-bit blue value.

   Redacted form: ‘plgcol0(icol0, r, g, b)’

   This function is used in example 2.


File: plplotdoc.info,  Node: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0,  Next: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Prev: plgcol0; Returns 8-bit RGB values for given color index from cmap0,  Up: The Common API for PLplot

17.37 plgcol0a: Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0
============================================================================================================

     plgcol0a (icol0, r, g, b, alpha);

   Returns 8-bit RGB values (0-255) and PLFLT alpha transparency value
(0.0-1.0) for given color from cmap0 (see *note Color Map0::).  Values
are negative if an invalid color id is given.

‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Index of desired cmap0 color.

‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the red intensity in the range from 0 to 255.

‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the green intensity in the range from 0 to 255.

‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the blue intensity in the range from 0 to 255.

‘alpha’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the alpha transparency in the range from
     (0.0-1.0).

   Redacted form: ‘plgcola(r, g, b)’

   This function is used in example 30.


File: plplotdoc.info,  Node: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Next: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value,  Prev: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0,  Up: The Common API for PLplot

17.38 plgcolbg: Returns the background color (cmap0[0]) by 8-bit RGB value
==========================================================================

     plgcolbg (r, g, b);

   Returns the background color (cmap0[0]) by 8-bit RGB value.

‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the red intensity in the range from 0 to 255.

‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the green intensity in the range from 0 to 255.

‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the blue intensity in the range from 0 to 255.

   Redacted form: ‘plgcolbg(r, g, b)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value,  Next: plgcompression; Get the current device-compression setting,  Prev: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value,  Up: The Common API for PLplot

17.39 plgcolbga: Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT alpha transparency value
==============================================================================================================

     plgcolbga (r, g, b, alpha);

   Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT
alpha transparency value.

‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the red intensity in the range from 0 to 255.

‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the green intensity in the range from 0 to 255.

‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the blue intensity in the range from 0 to 255.

‘alpha’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the alpha transparency in the range (0.0-1.0).

   This function is used in example 31.


File: plplotdoc.info,  Node: plgcompression; Get the current device-compression setting,  Next: plgdev; Get the current device [keyword] name,  Prev: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value,  Up: The Common API for PLplot

17.40 plgcompression: Get the current device-compression setting
================================================================

     plgcompression (compression);

   Get the current device-compression setting.  This parameter is only
used for drivers that provide compression.

‘compression’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the compression setting for the current device.

   Redacted form: ‘plgcompression(compression)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdev; Get the current device [keyword] name,  Next: plgdidev; Get parameters that define current device-space window,  Prev: plgcompression; Get the current device-compression setting,  Up: The Common API for PLplot

17.41 plgdev: Get the current device (keyword) name
===================================================

     plgdev (p_dev);

   Get the current device (keyword) name.  Note: you _must_ have
allocated space for this (80 characters is safe).

‘p_dev’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output)
     Returned ascii character string (with preallocated length of 80
     characters or more) containing the device (keyword) name.

   Redacted form: ‘plgdev(p_dev)’

   This function is used in example 14.


File: plplotdoc.info,  Node: plgdidev; Get parameters that define current device-space window,  Next: plgdiori; Get plot orientation,  Prev: plgdev; Get the current device [keyword] name,  Up: The Common API for PLplot

17.42 plgdidev: Get parameters that define current device-space window
======================================================================

     plgdidev (p_mar, p_aspect, p_jx, p_jy);

   Get relative margin width, aspect ratio, and relative justification
that define current device-space window.  If ‘plsdidev’ (*note plsdidev;
Set parameters that define current device-space window::) has not been
called the default values pointed to by ‘‘p_mar’’, ‘‘p_aspect’’,
‘‘p_jx’’, and ‘‘p_jy’’ will all be 0.

‘p_mar’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative margin width.

‘p_aspect’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the aspect ratio.

‘p_jx’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative justification in x.

‘p_jy’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative justification in y.

   Redacted form: ‘plgdidev(p_mar, p_aspect, p_jx, p_jy)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdiori; Get plot orientation,  Next: plgdiplt; Get parameters that define current plot-space window,  Prev: plgdidev; Get parameters that define current device-space window,  Up: The Common API for PLplot

17.43 plgdiori: Get plot orientation
====================================

     plgdiori (p_rot);

   Get plot orientation parameter which is multiplied by 90 degrees to
obtain the angle of rotation.  Note, arbitrary rotation parameters such
as 0.2 (corresponding to 18 degrees) are possible, but the usual values
for the rotation parameter are 0., 1., 2., and 3.  corresponding to 0
degrees (landscape mode), 90 degrees (portrait mode), 180 degrees
(seascape mode), and 270 degrees (upside-down mode).  If ‘plsdiori’
(*note plsdiori; Set plot orientation::) has not been called the default
value pointed to by ‘‘p_rot’’ will be 0.

‘p_rot’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the orientation parameter.

   Redacted form: ‘plgdiori(p_rot)’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plgdiplt; Get parameters that define current plot-space window,  Next: plgdrawmode; Get drawing mode [depends on device support!],  Prev: plgdiori; Get plot orientation,  Up: The Common API for PLplot

17.44 plgdiplt: Get parameters that define current plot-space window
====================================================================

     plgdiplt (p_xmin, p_ymin, p_xmax, p_ymax);

   Get relative minima and maxima that define current plot-space window.
If ‘plsdiplt’ (*note plsdiplt; Set parameters that define current
plot-space window::) has not been called the default values pointed to
by ‘‘p_xmin’’, ‘‘p_ymin’’, ‘‘p_xmax’’, and ‘‘p_ymax’’ will be 0., 0.,
1., and 1.

‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative minimum in x.

‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative minimum in y.

‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative maximum in x.

‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the relative maximum in y.

   Redacted form: ‘plgdiplt(p_xmin, p_ymin, p_xmax, p_ymax)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgdrawmode; Get drawing mode [depends on device support!],  Next: plgfam; Get family file parameters,  Prev: plgdiplt; Get parameters that define current plot-space window,  Up: The Common API for PLplot

17.45 plgdrawmode: Get drawing mode (depends on device support!)
================================================================

     plgdrawmode ();

   Get drawing mode.  Note only one device driver (cairo) currently
supports this at the moment, and for that case the PLINT value returned
by this function is one of ‘PL_DRAWMODE_DEFAULT’, ‘PL_DRAWMODE_REPLACE’,
‘PL_DRAWMODE_XOR’, or ‘PL_DRAWMODE_UNKNOWN’.  This function returns
‘PL_DRAWMODE_UNKNOWN’ for the rest of the device drivers.  See also
‘plsdrawmode’ (*note plsdrawmode; Set drawing mode [depends on device
support!]::).

   Redacted form: ‘plgdrawmode()’

   This function is used in example 34.


File: plplotdoc.info,  Node: plgfam; Get family file parameters,  Next: plgfci; Get FCI [font characterization integer],  Prev: plgdrawmode; Get drawing mode [depends on device support!],  Up: The Common API for PLplot

17.46 plgfam: Get family file parameters
========================================

     plgfam (p_fam, p_num, p_bmax);

   Gets information about current family file, if familying is enabled.
See *note Family File Output:: for more information.

‘p_fam’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current family flag value.  If nonzero,
     familying is enabled for the current device.

‘p_num’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current family file number.

‘p_bmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the maximum file size (in bytes) for a family
     file.

   Redacted form: ‘plgfam(p_fam, p_num, p_bmax)’

   This function is used in examples 14 and 31.


File: plplotdoc.info,  Node: plgfci; Get FCI [font characterization integer],  Next: plgfnam; Get output file name,  Prev: plgfam; Get family file parameters,  Up: The Common API for PLplot

17.47 plgfci: Get FCI (font characterization integer)
=====================================================

     plgfci (p_fci);

   Gets information about the current font using the FCI approach.  See
*note FCI:: for more information.

‘p_fci’ (‘‘PLUNICODE_NC_SCALAR’ (*note PLUNICODE_NC_SCALAR-type::)’, output)
     Returned value of the current FCI value.

   Redacted form: ‘plgfci(p_fci)’

   This function is used in example 23.


File: plplotdoc.info,  Node: plgfnam; Get output file name,  Next: plgfont; Get family; style and weight of the current font,  Prev: plgfci; Get FCI [font characterization integer],  Up: The Common API for PLplot

17.48 plgfnam: Get output file name
===================================

     plgfnam (fnam);

   Gets the current output file name, if applicable.

‘fnam’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output)
     Returned ascii character string (with preallocated length of 80
     characters or more) containing the file name.

   Redacted form: ‘plgfnam(fnam)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgfont; Get family; style and weight of the current font,  Next: plglevel; Get the [current] run level,  Prev: plgfnam; Get output file name,  Up: The Common API for PLplot

17.49 plgfont: Get family, style and weight of the current font
===============================================================

     plgfont (p_family, p_style, p_weight);

   Gets information about current font.  See *note FCI:: for more
information on font selection.

‘p_family’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current font family.  The available values
     are given by the PL_FCI_* constants in ‘plplot.h’.  Current options
     are PL_FCI_SANS, PL_FCI_SERIF, PL_FCI_MONO, PL_FCI_SCRIPT and
     PL_FCI_SYMBOL.  If p_family is NULL then the font family is not
     returned.

‘p_style’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current font style.  The available values are
     given by the PL_FCI_* constants in ‘plplot.h’.  Current options are
     PL_FCI_UPRIGHT, PL_FCI_ITALIC and PL_FCI_OBLIQUE. If p_style is
     NULL then the font style is not returned.

‘p_weight’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current font weight.  The available values
     are given by the PL_FCI_* constants in ‘plplot.h’.  Current options
     are PL_FCI_MEDIUM and PL_FCI_BOLD. If p_weight is NULL then the
     font weight is not returned.

   Redacted form: ‘plgfont(p_family, p_style, p_weight)’

   This function is used in example 23.


File: plplotdoc.info,  Node: plglevel; Get the [current] run level,  Next: plgpage; Get page parameters,  Prev: plgfont; Get family; style and weight of the current font,  Up: The Common API for PLplot

17.50 plglevel: Get the (current) run level
===========================================

     plglevel (p_level);

   Get the (current) run level.  Valid settings are:

   • 0, uninitialized

   • 1, initialized

   • 2, viewport defined

   • 3, world coordinates defined

‘p_level’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the run level.

   Redacted form: ‘plglevel(p_level)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgpage; Get page parameters,  Next: plgra; Switch to graphics screen,  Prev: plglevel; Get the [current] run level,  Up: The Common API for PLplot

17.51 plgpage: Get page parameters
==================================

     plgpage (p_xp, p_yp, p_xleng, p_yleng, p_xoff, p_yoff);

   Gets the current page configuration.  The length and offset values
are expressed in units that are specific to the current driver.  For
instance: screen drivers will usually interpret them as number of
pixels, whereas printer drivers will usually use mm.

‘p_xp’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the number of pixels/inch (DPI) in x.

‘p_yp’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the number of pixels/inch (DPI) in y.

‘p_xleng’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the x page length.

‘p_yleng’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the y page length.

‘p_xoff’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the x page offset.

‘p_yoff’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the y page offset.

   Redacted form: ‘plgpage(p_xp, p_yp, p_xleng, p_yleng, p_xoff,
p_yoff)’

   This function is used in examples 14 and 31.


File: plplotdoc.info,  Node: plgra; Switch to graphics screen,  Next: plgradient; Draw linear gradient inside polygon,  Prev: plgpage; Get page parameters,  Up: The Common API for PLplot

17.52 plgra: Switch to graphics screen
======================================

     plgra ();

   Sets an interactive device to graphics mode, used in conjunction with
‘pltext’ (*note pltext; Switch to text screen::) to allow graphics and
text to be interspersed.  On a device which supports separate text and
graphics windows, this command causes control to be switched to the
graphics window.  If already in graphics mode, this command is ignored.
It is also ignored on devices which only support a single window or use
a different method for shifting focus.  See also ‘pltext’ (*note pltext;
Switch to text screen::).

   Redacted form: ‘plgra()’

   This function is used in example 1.


File: plplotdoc.info,  Node: plgradient; Draw linear gradient inside polygon,  Next: plgriddata; Grid data from irregularly sampled data,  Prev: plgra; Switch to graphics screen,  Up: The Common API for PLplot

17.53 plgradient: Draw linear gradient inside polygon
=====================================================

     plgradient (n, x, y, angle);

   Draw a linear gradient using cmap1 inside the polygon defined by the
‘‘n’’ points ‘(‘x’[i], ‘y’[i])’.  Interpretation of the polygon is the
same as for ‘plfill’ (*note plfill; Draw filled polygon::).  The polygon
coordinates and the gradient angle are all expressed in world
coordinates.  The angle from the ‘‘x’’ axis for both the rotated
coordinate system and the gradient vector is specified by ‘‘angle’’.
The magnitude of the gradient vector is the difference between the
maximum and minimum values of ‘‘x’’ for the vertices in the rotated
coordinate system.  The origin of the gradient vector can be interpreted
as being anywhere on the line corresponding to the minimum ‘‘x’’ value
for the vertices in the rotated coordinate system.  The distance along
the gradient vector is linearly transformed to the independent variable
of color map 1 which ranges from 0.  at the tail of the gradient vector
to 1.  at the head of the gradient vector.  What is drawn is the RGBA
color corresponding to the independent variable of cmap1.  For more
information about cmap1 (see *note Color Map1::).

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of vertices in polygon.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of vertices.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of vertices.

‘angle’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Angle (degrees) of gradient vector from x axis.

   Redacted form: ‘plgradient(x,y,angle)’

   This function is used in examples 25 and 30.


File: plplotdoc.info,  Node: plgriddata; Grid data from irregularly sampled data,  Next: plgspa; Get current subpage parameters,  Prev: plgradient; Draw linear gradient inside polygon,  Up: The Common API for PLplot

17.54 plgriddata: Grid data from irregularly sampled data
=========================================================

     plgriddata (x, y, z, npts, xg, nptsx, yg, nptsy, zg, type, data);

   Real world data is frequently irregularly sampled, but PLplot 3D
plots require data organized as a grid, i.e., with x sample point values
independent of y coordinate and vice versa.  This function takes
irregularly sampled data from the ‘x[npts]’, ‘y[npts]’, and ‘z[npts]’
vectors; reads the desired grid location from the input vectors
‘xg[nptsx]’ and ‘yg[nptsy]’; and returns the interpolated result on that
grid using the output matrix ‘zg[nptsx][nptsy]’.  The algorithm used to
interpolate the data to the grid is specified with the argument ‘type’
which can have one parameter specified in argument ‘data’.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     The input ‘x’ vector.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     The input ‘y’ vector.

‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     The input ‘z’ vector.  Each triple ‘x[i]’, ‘y[i]’, ‘z[i]’
     represents one data sample coordinate.

‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of data samples in the ‘x’, ‘y’ and ‘z’ vectors.

‘xg’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector that specifies the grid spacing in the x direction.
     Usually ‘xg’ has ‘nptsx’ equally spaced values from the minimum to
     the maximum values of the ‘x’ input vector.

‘nptsx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of points in the ‘xg’ vector.

‘yg’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector that specifies the grid spacing in the y direction.
     Similar to the ‘xg’ parameter.

‘nptsy’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of points in the ‘yg’ vector.

‘zg’ (‘‘PLFLT_NC_MATRIX’ (*note PLFLT_NC_MATRIX-type::)’, output)
     The matrix of interpolated results where data lies in the grid
     specified by ‘xg’ and ‘yg’.  Therefore the ‘zg’ matrix must be
     dimensioned ‘nptsx’ by ‘nptsy’.

‘type’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The type of grid interpolation algorithm to use, which can be:

        • ‘GRID_CSA’: Bivariate Cubic Spline approximation

        • ‘GRID_DTLI’: Delaunay Triangulation Linear Interpolation

        • ‘GRID_NNI’: Natural Neighbors Interpolation

        • ‘GRID_NNIDW’: Nearest Neighbors Inverse Distance Weighted

        • ‘GRID_NNLI’: Nearest Neighbors Linear Interpolation

        • ‘GRID_NNAIDW’: Nearest Neighbors Around Inverse Distance
          Weighted

     For details of the algorithms read the source file ‘plgridd.c’.

‘data’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Some gridding algorithms require extra data, which can be specified
     through this argument.  Currently, for algorithm:

        • ‘GRID_NNIDW’, ‘data’ specifies the number of neighbors to use,
          the lower the value, the noisier (more local) the
          approximation is.

        • ‘GRID_NNLI’, ‘data’ specifies what a thin triangle is, in the
          range [1.  ..  2.].  High values enable the usage of very thin
          triangles for interpolation, possibly resulting in error in
          the approximation.

        • ‘GRID_NNI’, only weights greater than ‘data’ will be accepted.
          If 0, all weights will be accepted.

   Redacted form:

   • General: ‘plgriddata(x, y, z, xg, yg, zg, type, data)’

   • Python: ‘‘zg’=‘plgriddata(x, y, z, xg, yg, type, data)’’

   This function is used in example 21.


File: plplotdoc.info,  Node: plgspa; Get current subpage parameters,  Next: plgstrm; Get current stream number,  Prev: plgriddata; Grid data from irregularly sampled data,  Up: The Common API for PLplot

17.55 plgspa: Get current subpage parameters
============================================

     plgspa (xmin, xmax, ymin, ymax);

   Gets the size of the current subpage in millimeters measured from the
bottom left hand corner of the output device page or screen.  Can be
used in conjunction with ‘plsvpa’ (*note plsvpa; Specify viewport in
absolute coordinates::) for setting the size of a viewport in absolute
coordinates (millimeters).

‘xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the position of the left hand edge of the subpage
     in millimeters.

‘xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the position of the right hand edge of the
     subpage in millimeters.

‘ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the position of the bottom edge of the subpage in
     millimeters.

‘ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the position of the top edge of the subpage in
     millimeters.

   Redacted form: ‘plgspa(xmin, xmax, ymin, ymax)’

   This function is used in example 23.


File: plplotdoc.info,  Node: plgstrm; Get current stream number,  Next: plgver; Get the current library version number,  Prev: plgspa; Get current subpage parameters,  Up: The Common API for PLplot

17.56 plgstrm: Get current stream number
========================================

     plgstrm (p_strm);

   Gets the number of the current output stream.  See also ‘plsstrm’
(*note plsstrm; Set current output stream::).

‘p_strm’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the current stream value.

   Redacted form: ‘plgstrm(p_strm)’

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plgver; Get the current library version number,  Next: plgvpd; Get viewport limits in normalized device coordinates,  Prev: plgstrm; Get current stream number,  Up: The Common API for PLplot

17.57 plgver: Get the current library version number
====================================================

     plgver (p_ver);

   Get the current library version number.  Note: you _must_ have
allocated space for this (80 characters is safe).

‘p_ver’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output)
     Returned ascii character string (with preallocated length of 80
     characters or more) containing the PLplot version number.

   Redacted form: ‘plgver(p_ver)’

   This function is used in example 1.


File: plplotdoc.info,  Node: plgvpd; Get viewport limits in normalized device coordinates,  Next: plgvpw; Get viewport limits in world coordinates,  Prev: plgver; Get the current library version number,  Up: The Common API for PLplot

17.58 plgvpd: Get viewport limits in normalized device coordinates
==================================================================

     plgvpd (p_xmin, p_xmax, p_ymin, p_ymax);

   Get viewport limits in normalized device coordinates.

‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the lower viewport limit of the normalized device
     coordinate in x.

‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the upper viewport limit of the normalized device
     coordinate in x.

‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the lower viewport limit of the normalized device
     coordinate in y.

‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the upper viewport limit of the normalized device
     coordinate in y.

   Redacted form:

   • General: ‘plgvpd(p_xmin, p_xmax, p_ymin, p_ymax)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgvpw; Get viewport limits in world coordinates,  Next: plgxax; Get x axis parameters,  Prev: plgvpd; Get viewport limits in normalized device coordinates,  Up: The Common API for PLplot

17.59 plgvpw: Get viewport limits in world coordinates
======================================================

     plgvpw (p_xmin, p_xmax, p_ymin, p_ymax);

   Get viewport limits in world coordinates.

‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the lower viewport limit of the world coordinate
     in x.

‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the upper viewport limit of the world coordinate
     in x.

‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the lower viewport limit of the world coordinate
     in y.

‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the upper viewport limit of the world coordinate
     in y.

   Redacted form:

   • General: ‘plgvpw(p_xmin, p_xmax, p_ymin, p_ymax)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgxax; Get x axis parameters,  Next: plgyax; Get y axis parameters,  Prev: plgvpw; Get viewport limits in world coordinates,  Up: The Common API for PLplot

17.60 plgxax: Get x axis parameters
===================================

     plgxax (p_digmax, p_digits);

   Returns current values of the ‘‘p_digmax’’ and ‘‘p_digits’’ flags for
the x axis.  ‘‘p_digits’’ is updated after the plot is drawn, so this
routine should only be called _after_ the call to ‘plbox’ (*note plbox;
Draw a box with axes; etc::) (or ‘ plbox3’ (*note plbox3; Draw a box
with axes; etc; in 3-d::)) is complete.  See *note Annotating the
Viewport:: for more information.

‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the maximum number of digits for the x axis.  If
     nonzero, the printed label has been switched to a floating-point
     representation when the number of digits exceeds this value.

‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the actual number of digits for the numeric
     labels (x axis) from the last plot.

   Redacted form: ‘plgxax(p_digmax, p_digits)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgyax; Get y axis parameters,  Next: plgzax; Get z axis parameters,  Prev: plgxax; Get x axis parameters,  Up: The Common API for PLplot

17.61 plgyax: Get y axis parameters
===================================

     plgyax (p_digmax, p_digits);

   Identical to ‘plgxax’ (*note plgxax; Get x axis parameters::), except
that arguments are flags for y axis.  See the description of ‘plgxax’
(*note plgxax; Get x axis parameters::) for more detail.

‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the maximum number of digits for the y axis.  If
     nonzero, the printed label has been switched to a floating-point
     representation when the number of digits exceeds this value.

‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the actual number of digits for the numeric
     labels (y axis) from the last plot.

   Redacted form: ‘plgyax(p_digmax, p_digits)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plgzax; Get z axis parameters,  Next: plhist; Plot a histogram from unbinned data,  Prev: plgyax; Get y axis parameters,  Up: The Common API for PLplot

17.62 plgzax: Get z axis parameters
===================================

     plgzax (p_digmax, p_digits);

   Identical to ‘plgxax’ (*note plgxax; Get x axis parameters::), except
that arguments are flags for z axis.  See the description of ‘plgxax’
(*note plgxax; Get x axis parameters::) for more detail.

‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the maximum number of digits for the z axis.  If
     nonzero, the printed label has been switched to a floating-point
     representation when the number of digits exceeds this value.

‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the actual number of digits for the numeric
     labels (z axis) from the last plot.

   Redacted form: ‘plgzax(p_digmax, p_digits)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plhist; Plot a histogram from unbinned data,  Next: plhlsrgb; Convert HLS color to RGB,  Prev: plgzax; Get z axis parameters,  Up: The Common API for PLplot

17.63 plhist: Plot a histogram from unbinned data
=================================================

     plhist (n, data, datmin, datmax, nbin, opt);

   Plots a histogram from ‘‘n’’ data points stored in the ‘‘data’’
vector.  This routine bins the data into ‘‘nbin’’ bins equally spaced
between ‘‘datmin’’ and ‘‘datmax’’, and calls ‘plbin’ (*note plbin; Plot
a histogram from binned data::) to draw the resulting histogram.
Parameter ‘‘opt’’ allows, among other things, the histogram either to be
plotted in an existing window or causes ‘plhist’ (*note plhist; Plot a
histogram from unbinned data::) to call ‘plenv’ (*note plenv; Set up
standard window and draw box::) with suitable limits before plotting the
histogram.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of data points.

‘data’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the values of the ‘‘n’’ data points.

‘datmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Left-hand edge of lowest-valued bin.

‘datmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Right-hand edge of highest-valued bin.

‘nbin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of (equal-sized) bins into which to divide the interval
     ‘‘xmin’’ to ‘‘xmax’’.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Is a combination of several flags:

        • ‘‘opt’=PL_HIST_DEFAULT’: The axes are automatically rescaled
          to fit the histogram data, the outer bins are expanded to fill
          up the entire x-axis, data outside the given extremes are
          assigned to the outer bins and bins of zero height are simply
          drawn.

        • ‘‘opt’=PL_HIST_NOSCALING|...’: The existing axes are not
          rescaled to fit the histogram data, without this flag, ‘plenv’
          (*note plenv; Set up standard window and draw box::) is called
          to set the world coordinates.

        • ‘‘opt’=PL_HIST_IGNORE_OUTLIERS|...’: Data outside the given
          extremes are not taken into account.  This option should
          probably be combined with ‘‘opt’=PL_HIST_NOEXPAND|...’, so as
          to properly present the data.

        • ‘‘opt’=PL_HIST_NOEXPAND|...’: The outer bins are drawn with
          equal size as the ones inside.

        • ‘‘opt’=PL_HIST_NOEMPTY|...’: Bins with zero height are not
          drawn (there is a gap for such bins).

   Redacted form: ‘plhist(data, datmin, datmax, nbin, opt)’

   This function is used in example 5.


File: plplotdoc.info,  Node: plhlsrgb; Convert HLS color to RGB,  Next: plimagefr; Plot a 2D matrix using cmap1,  Prev: plhist; Plot a histogram from unbinned data,  Up: The Common API for PLplot

17.64 plhlsrgb: Convert HLS color to RGB
========================================

     plhlsrgb (h, l, s, p_r, p_g, p_b);

   Convert HLS color coordinates to RGB.

‘h’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Hue in degrees (0.0-360.0) on the color cylinder.

‘l’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Lightness expressed as a fraction (0.0-1.0) of the axis of the
     color cylinder.

‘s’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Saturation expressed as a fraction (0.0-1.0) of the radius of the
     color cylinder.

‘p_r’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the red intensity (0.0-1.0) of the color.

‘p_g’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the green intensity (0.0-1.0) of the color.

‘p_b’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the blue intensity (0.0-1.0) of the color.

   Redacted form:

   • General: ‘plhlsrgb(h, l, s, p_r, p_g, p_b)’

   This function is used in example 2.


File: plplotdoc.info,  Node: plimagefr; Plot a 2D matrix using cmap1,  Next: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment,  Prev: plhlsrgb; Convert HLS color to RGB,  Up: The Common API for PLplot

17.65 plimagefr: Plot a 2D matrix using cmap1
=============================================

     plimagefr (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax,
     valuemin, valuemax, pltr, pltr_data);

   Plot a 2D matrix using cmap1.

‘idata’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix of values (intensities) to plot.  Should have dimensions
     of ‘nx’ by ‘ny’.

‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Dimensions of idata

‘xmin, xmax, ymin, ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     See the discussion of ‘pltr’ below for how these arguments are used
     (only for the special case when the callback function ‘pltr’ is not
     supplied).

‘zmin, zmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Only data between zmin and zmax (inclusive) will be plotted.

‘valuemin, valuemax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum and maximum data values to use for value to color
     mappings.  A datum equal to or less than valuemin will be plotted
     with color 0.0, while a datum equal to or greater than valuemax
     will be plotted with color 1.0.  Data between valuemin and valuemax
     map linearly to colors in the range (0.0-1.0).

‘pltr’ (‘‘PLTRANSFORM_callback’ (*note PLTRANSFORM_callback-type::)’, input)
     A callback function that defines the transformation between the
     zero-based indices of the matrix ‘‘idata’’ and world coordinates.
     If ‘pltr’ is not supplied (e.g., is set to NULL in the C case),
     then the x indices of ‘‘idata’’ are mapped to the range ‘xmin’
     through ‘xmax’ and the y indices of ‘‘idata’’ are mapped to the
     range ‘ymin’ through ‘ymax’.

     For the C case, transformation functions are provided in the PLplot
     library: ‘pltr0’ (*note pltr0; Identity transformation for matrix
     index to world coordinate mapping::) for the identity mapping, and
     ‘pltr1’ (*note pltr1; Linear interpolation for matrix index to
     world coordinate mapping using singly dimensioned coordinate
     arrays::) and ‘pltr2’ (*note pltr2; Linear interpolation for grid
     to world mapping using doubly dimensioned coordinate arrays
     [row-major order as per normal C 2d arrays]::) for arbitrary
     mappings respectively defined by vectors and matrices.  In
     addition, C callback routines for the transformation can be
     supplied by the user such as the ‘mypltr’ function in
     ‘examples/c/x09c.c’ which provides a general linear transformation
     between index coordinates and world coordinates.

     For languages other than C you should consult *note Supported
     computer languages: Supported computer languages. for the details
     concerning how ‘PLTRANSFORM_callback’ (*note
     PLTRANSFORM_callback-type::) arguments are interfaced.  However, in
     general, a particular pattern of callback-associated arguments such
     as a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’ vectors; or ‘xg’
     and ‘yg’ matrices are respectively interfaced to a
     linear-transformation routine similar to the above ‘mypltr’
     function; ‘pltr1’ (*note pltr1; Linear interpolation for matrix
     index to world coordinate mapping using singly dimensioned
     coordinate arrays::); and ‘pltr2’ (*note pltr2; Linear
     interpolation for grid to world mapping using doubly dimensioned
     coordinate arrays [row-major order as per normal C 2d arrays]::).
     Furthermore, some of our more sophisticated bindings (see, e.g.,
     *note Fortran Language::) support native language callbacks for
     handling index to world-coordinate transformations.  Examples of
     these various approaches are given in ‘examples/<language>x09*’,
     ‘examples/<language>x16*’, ‘examples/<language>x20*’,
     ‘examples/<language>x21*’, and ‘examples/<language>x22*’, for all
     our supported languages.

‘pltr_data’ (‘‘PLPointer’ (*note PLPointer-type::)’, input)
     Extra parameter to help pass information to ‘pltr0’ (*note pltr0;
     Identity transformation for matrix index to world coordinate
     mapping::), ‘pltr1’ (*note pltr1; Linear interpolation for matrix
     index to world coordinate mapping using singly dimensioned
     coordinate arrays::), ‘pltr2’ (*note pltr2; Linear interpolation
     for grid to world mapping using doubly dimensioned coordinate
     arrays [row-major order as per normal C 2d arrays]::), or whatever
     routine is externally supplied.

   Redacted form:

   • General: ‘ plimagefr(idata, xmin, xmax, ymin, ymax, zmin, zmax,
     valuemin, valuemax, pltr, pltr_data) ’

   This function is used in example 20.


File: plplotdoc.info,  Node: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment,  Next: plinit; Initialize PLplot,  Prev: plimagefr; Plot a 2D matrix using cmap1,  Up: The Common API for PLplot

17.66 plimage: Plot a 2D matrix using cmap1 with automatic color adjustment
===========================================================================

     plimage (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax, Dxmin,
     Dxmax, Dymin, Dymax);

   Plot a 2D matrix using the cmap1 palette.  The color scale is
automatically adjusted to use the maximum and minimum values in idata as
valuemin and valuemax in a call to ‘plimagefr’ (*note plimagefr; Plot a
2D matrix using cmap1::).

‘idata’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Dimensions of idata

‘xmin, xmax, ymin, ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The ‘x’ and ‘y’ index ranges are linearly transformed to these
     world coordinate ranges such that ‘idata[0][0]’ corresponds to
     ‘(xmin, ymin)’ and ‘idata[nx - 1][ny - 1]’ corresponds to ‘(xmax,
     ymax)’.

‘zmin, zmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Only data between zmin and zmax (inclusive) will be plotted.

‘Dxmin, Dxmax, Dymin, Dymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Plot only the window of points whose plot coordinates fall inside
     the window of (Dxmin, Dymin) to (Dxmax, Dymax).

   Redacted form:

   • General: ‘ plimage(idata, xmin, xmax, ymin, ymax, zmin, zmax,
     Dxmin, Dxmax, Dymin, Dymax) ’

   This function is used in example 20.


File: plplotdoc.info,  Node: plinit; Initialize PLplot,  Next: pljoin; Draw a line between two points,  Prev: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment,  Up: The Common API for PLplot

17.67 plinit: Initialize PLplot
===============================

     plinit ();

   Initializing the plotting package.  The program prompts for the
device keyword or number of the desired output device.  Hitting a RETURN
in response to the prompt is the same as selecting the first device.
‘plinit’ (*note plinit; Initialize PLplot::) will issue no prompt if
either the device was specified previously (via command line flag, the
‘plsetopt’ (*note plsetopt; Set any command-line option::) function, or
the ‘plsdev’ (*note plsdev; Set the device [keyword] name::) function),
or if only one device is enabled when PLplot is installed.  If subpages
have been specified, the output device is divided into ‘nx’ by ‘ny’
subpages, each of which may be used independently.  If ‘plinit’ (*note
plinit; Initialize PLplot::) is called again during a program, the
previously opened file will be closed.  The subroutine ‘pladv’ (*note
pladv; Advance the [sub-]page::) is used to advance from one subpage to
the next.

   Redacted form: ‘plinit()’

   This function is used in all of the examples.


File: plplotdoc.info,  Node: pljoin; Draw a line between two points,  Next: pllab; Simple routine to write labels,  Prev: plinit; Initialize PLplot,  Up: The Common API for PLplot

17.68 pljoin: Draw a line between two points
============================================

     pljoin (x1, y1, x2, y2);

   Joins the point ‘(‘x1’, ‘y1’)’ to ‘(‘x2’, ‘y2’)’.

‘x1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x coordinate of first point.

‘y1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y coordinate of first point.

‘x2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x coordinate of second point.

‘y2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y coordinate of second point.

   Redacted form: ‘pljoin(x1,y1,x2,y2)’

   This function is used in examples 3 and 14.


File: plplotdoc.info,  Node: pllab; Simple routine to write labels,  Next: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Prev: pljoin; Draw a line between two points,  Up: The Common API for PLplot

17.69 pllab: Simple routine to write labels
===========================================

     pllab (xlabel, ylabel, tlabel);

   Routine for writing simple labels.  Use ‘plmtex’ (*note plmtex; Write
text relative to viewport boundaries::) for more complex labels.

‘xlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the label for the x axis.

‘ylabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the label for the y axis.

‘tlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string specifying the title of the plot.

   Redacted form: ‘pllab(xlabel, ylabel, tlabel)’

   This function is used in examples 1, 5, 9, 12, 14-16, 20-22, and 29.


File: plplotdoc.info,  Node: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Next: pllightsource; Sets the 3D position of the light source,  Prev: pllab; Simple routine to write labels,  Up: The Common API for PLplot

17.70 pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols
===================================================================================================

     pllegend (p_legend_width, p_legend_height, opt, position, x, y,
     plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, nlegend,
     opt_array, text_offset, text_scale, text_spacing,
     test_justification, text_colors, text, box_colors, box_patterns,
     box_scales, box_line_widths, line_colors, line_styles, line_widths,
     symbol_colors, symbol_scales, symbol_numbers, symbols);

   Routine for creating a discrete plot legend with a plotted filled
box, line, and/or line of symbols for each annotated legend entry.  (See
‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or
gradient plots::) for similar functionality for creating continuous
color bars.)  The arguments of pllegend provide control over the
location and size of the legend as well as the location and
characteristics of the elements (most of which are optional) within that
legend.  The resulting legend is clipped at the boundaries of the
current subpage.  (N.B. the adopted coordinate system used for some of
the parameters is defined in the documentation of the ‘‘position’’
parameter.)

‘p_legend_width’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the legend width in adopted coordinates.  This
     quantity is calculated from ‘‘plot_width’’, ‘‘text_offset’’,
     ‘‘ncolumn’’ (possibly modified inside the routine depending on
     ‘‘nlegend’’ and ‘‘nrow’’), and the length (calculated internally)
     of the longest text string.

‘p_legend_height’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the legend height in adopted coordinates.  This
     quantity is calculated from ‘‘text_scale’’, ‘‘text_spacing’’, and
     ‘‘nrow’’ (possibly modified inside the routine depending on
     ‘‘nlegend’’ and ‘‘nrow’’).

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     ‘‘opt’’ contains bits controlling the overall legend.  If the
     ‘PL_LEGEND_TEXT_LEFT’ bit is set, put the text area on the left of
     the legend and the plotted area on the right.  Otherwise, put the
     text area on the right of the legend and the plotted area on the
     left.  If the ‘PL_LEGEND_BACKGROUND’ bit is set, plot a
     (semitransparent) background for the legend.  If the
     ‘PL_LEGEND_BOUNDING_BOX’ bit is set, plot a bounding box for the
     legend.  If the ‘PL_LEGEND_ROW_MAJOR’ bit is set and (both of the
     possibly internally transformed) ‘‘nrow’’ > 1 and ‘‘ncolumn’’ > 1,
     then plot the resulting array of legend entries in row-major order.
     Otherwise, plot the legend entries in column-major order.

‘position’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     ‘‘position’’ contains bits which control the overall position of
     the legend and the definition of the adopted coordinates used for
     positions just like what is done for the position argument for
     ‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or
     gradient plots::).  However, note that the defaults for the
     position bits (see below) are different than the ‘plcolorbar’
     (*note plcolorbar; Plot color bar for image; shade or gradient
     plots::) case.  The combination of the ‘PL_POSITION_LEFT’,
     ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, ‘PL_POSITION_BOTTOM’,
     ‘PL_POSITION_INSIDE’, and ‘PL_POSITION_OUTSIDE’ bits specifies one
     of the 16 possible standard positions (the 4 corners and centers of
     the 4 sides for both the inside and outside cases) of the legend
     relative to the adopted coordinate system.  The corner positions
     are specified by the appropriate combination of two of the
     ‘PL_POSITION_LEFT’, ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, and
     ‘PL_POSITION_BOTTOM’ bits while the sides are specified by a single
     value of one of those bits.  The adopted coordinates are normalized
     viewport coordinates if the ‘PL_POSITION_VIEWPORT’ bit is set or
     normalized subpage coordinates if the ‘PL_POSITION_SUBPAGE’ bit is
     set.  Default position bits: If none of ‘PL_POSITION_LEFT’,
     ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, or ‘PL_POSITION_BOTTOM’ are
     set, then use the combination of ‘PL_POSITION_RIGHT’ and
     ‘PL_POSITION_TOP’.  If neither of ‘PL_POSITION_INSIDE’ or
     ‘PL_POSITION_OUTSIDE’ is set, use ‘PL_POSITION_INSIDE’.  If neither
     of ‘PL_POSITION_VIEWPORT’ or ‘PL_POSITION_SUBPAGE’ is set, use
     ‘PL_POSITION_VIEWPORT’.

‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     X offset of the legend position in adopted coordinates from the
     specified standard position of the legend.  For positive x, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard left
     or right positions if the
     ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in
     ‘‘position’’.  For the standard top or bottom positions, the
     direction of motion is toward positive X.

‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Y offset of the legend position in adopted coordinates from the
     specified standard position of the legend.  For positive y, the
     direction of motion away from the standard position is
     inward/outward from the standard corner positions or standard top
     or bottom positions if the
     ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in
     ‘‘position’’.  For the standard left or right positions, the
     direction of motion is toward positive Y.

‘plot_width’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Horizontal width in adopted coordinates of the plot area (where the
     colored boxes, lines, and/or lines of symbols are drawn) of the
     legend.

‘bg_color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The cmap0 color of the background for the legend
     (‘PL_LEGEND_BACKGROUND’).

‘bb_color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The cmap0 color of the bounding-box line for the legend
     (‘PL_LEGEND_BOUNDING_BOX’).

‘bb_style’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The pllsty style number for the bounding-box line for the legend
     (‘PL_LEGEND_BACKGROUND’).

‘nrow’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of rows in the matrix used to render the ‘nlegend’
     legend entries.  For internal transformations of ‘nrow’, see
     further remarks under ‘nlegend’.

‘ncolumn’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of columns in the matrix used to render the ‘nlegend’
     legend entries.  For internal transformations of ‘ncolumn’, see
     further remarks under ‘nlegend’.

‘nlegend’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of legend entries.  The above ‘nrow’ and ‘ncolumn’ values
     are transformed internally to be consistent with ‘nlegend’.  If
     either ‘nrow’ or ‘ncolumn’ is non-positive it is replaced by 1.  If
     the resulting product of ‘nrow’ and ‘ncolumn’ is less than
     ‘nlegend’, the smaller of the two (or ‘nrow’, if ‘nrow’ ==
     ‘ncolumn’) is increased so the product is >= ‘nlegend’.  Thus, for
     example, the common ‘nrow’ = 0, ‘ncolumn’ = 0 case is transformed
     internally to ‘nrow’ = ‘nlegend’, ‘ncolumn’ = 1; i.e., the usual
     case of a legend rendered as a single column.

‘opt_array’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector of ‘nlegend’ values of options to control each individual
     plotted area corresponding to a legend entry.  If the
     ‘PL_LEGEND_NONE’ bit is set, then nothing is plotted in the plotted
     area.  If the ‘PL_LEGEND_COLOR_BOX’, ‘PL_LEGEND_LINE’, and/or
     ‘PL_LEGEND_SYMBOL’ bits are set, the area corresponding to a legend
     entry is plotted with a colored box; a line; and/or a line of
     symbols.

‘text_offset’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Offset of the text area from the plot area in units of character
     width.

‘text_scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Character height scale for text annotations.

‘text_spacing’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Vertical spacing in units of the character height from one legend
     entry to the next.

‘text_justification’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Justification parameter used for text justification.  The most
     common values of text_justification are 0., 0.5, or 1.
     corresponding to a text that is left justified, centred, or right
     justified within the text area, but other values are allowed as
     well.

‘text_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ cmap0 text colors.

‘text’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input)
     A vector of ‘nlegend’ UTF-8 character strings containing the legend
     annotations.

‘box_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ cmap0 colors for the discrete colored
     boxes (‘PL_LEGEND_COLOR_BOX’).

‘box_patterns’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ patterns (plpsty indices) for the
     discrete colored boxes (‘PL_LEGEND_COLOR_BOX’).

‘box_scales’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ scales (units of fraction of
     character height) for the height of the discrete colored boxes
     (‘PL_LEGEND_COLOR_BOX’).

‘box_line_widths’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ line widths for the patterns
     specified by box_patterns (‘PL_LEGEND_COLOR_BOX’).

‘line_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ cmap0 line colors (‘PL_LEGEND_LINE’).

‘line_styles’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ line styles (plsty indices)
     (‘PL_LEGEND_LINE’).

‘line_widths’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ line widths (‘PL_LEGEND_LINE’).

‘symbol_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ cmap0 symbol colors
     (‘PL_LEGEND_SYMBOL’).

‘symbol_scales’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ scale values for the symbol height
     (‘PL_LEGEND_SYMBOL’).

‘symbol_numbers’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘nlegend’ numbers of symbols to be drawn across
     the width of the plotted area (‘PL_LEGEND_SYMBOL’).

‘symbols’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input)
     A vector of ‘nlegend’ UTF-8 character strings containing the legend
     symbols.  (‘PL_LEGEND_SYMBOL’).

   Redacted form: ‘pllegend(p_legend_width, p_legend_height, opt,
position, x, y, plot_width, bg_color, bb_color, bb_style, nrow, ncolumn,
opt_array, text_offset, text_scale, text_spacing, test_justification,
text_colors, text, box_colors, box_patterns, box_scales,
box_line_widths, line_colors, line_styles, line_widths, symbol_colors,
symbol_scales, symbol_numbers, symbols)’

   This function is used in examples 4, 26, and 33.


File: plplotdoc.info,  Node: pllightsource; Sets the 3D position of the light source,  Next: plline; Draw a line,  Prev: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols,  Up: The Common API for PLplot

17.71 pllightsource: Sets the 3D position of the light source
=============================================================

     pllightsource (x, y, z);

   Sets the 3D position of the light source for use with ‘plsurf3d’
(*note plsurf3d; Plot shaded 3-d surface plot::) and ‘plsurf3dl’ (*note
plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index
limits::)

‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     X-coordinate of the light source.

‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Y-coordinate of the light source.

‘z’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Z-coordinate of the light source.

   Redacted form: ‘pllightsource(x, y, z)’

   This function is used in example 8.


File: plplotdoc.info,  Node: plline; Draw a line,  Next: plline3; Draw a line in 3 space,  Prev: pllightsource; Sets the 3D position of the light source,  Up: The Common API for PLplot

17.72 plline: Draw a line
=========================

     plline (n, x, y);

   Draws line defined by ‘‘n’’ points in ‘‘x’’ and ‘‘y’’.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of points defining line.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of points.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of points.

   Redacted form: ‘plline(x, y)’

   This function is used in examples 1, 3, 4, 9, 12-14, 16, 18, 20, 22,
25-27, and 29.


File: plplotdoc.info,  Node: plline3; Draw a line in 3 space,  Next: pllsty; Select line style,  Prev: plline; Draw a line,  Up: The Common API for PLplot

17.73 plline3: Draw a line in 3 space
=====================================

     plline3 (n, x, y, z);

   Draws line in 3 space defined by ‘‘n’’ points in ‘‘x’’, ‘‘y’’, and
‘‘z’’.  You must first set up the viewport, the 2d viewing window (in
world coordinates), and the 3d normalized coordinate box.  See ‘x18c.c’
for more info.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of points defining line.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of points.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of points.

‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the z coordinates of points.

   Redacted form: ‘plline3(x, y, z)’

   This function is used in example 18.


File: plplotdoc.info,  Node: pllsty; Select line style,  Next: plmap; Plot continental outline or shapefile data in world coordinates,  Prev: plline3; Draw a line in 3 space,  Up: The Common API for PLplot

17.74 pllsty: Select line style
===============================

     pllsty (lin);

   This sets the line style according to one of eight predefined
patterns (also see ‘plstyl’ (*note plstyl; Set line style::)).

‘lin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Integer value between 1 and 8.  Line style 1 is a continuous line,
     line style 2 is a line with short dashes and gaps, line style 3 is
     a line with long dashes and gaps, line style 4 has long dashes and
     short gaps and so on.

   Redacted form: ‘pllsty(lin)’

   This function is used in examples 9, 12, 22, and 25.


File: plplotdoc.info,  Node: plmap; Plot continental outline or shapefile data in world coordinates,  Next: plmapfill; Plot all or a subset of Shapefile data; filling the polygons,  Prev: pllsty; Select line style,  Up: The Common API for PLplot

17.75 plmap: Plot continental outline or shapefile data in world coordinates
============================================================================

     plmap ( mapform , name , minx , maxx , miny , maxy );

   Plots continental outlines or shapefile data in world coordinates.  A
demonstration of how to use this function to create different
projections can be found in examples/c/x19c.  PLplot is provided with
basic coastal outlines and USA state borders.  To use the map
functionality PLplot must be compiled with the shapelib library.
Shapefiles have become a popular standard for geographical data and data
in this format can be easily found from a number of online sources.
Shapefile data is actually provided as three or more files with the same
filename, but different extensions.  The .shp and .shx files are
required for plotting Shapefile data with PLplot.

   PLplot currently supports the point, multipoint, polyline and polygon
objects within shapefiles.  However holes in polygons are not supported.
When plmap is used the type of object is derived from the shapefile, if
you wish to override the type then use one of the other plmap variants.
The built in maps have line data only.

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the original map data
     coordinates to a new coordinate system.  The PLplot-supplied map
     data is provided as latitudes and longitudes; other Shapefile data
     may be provided in other coordinate systems as can be found in
     their .prj plain text files.  For example, by using this transform
     we can change from a longitude, latitude coordinate to a polar
     stereographic projection.  Initially, x[0]..[n-1] are the original
     x coordinates (longitudes for the PLplot-supplied data) and
     y[0]..y[n-1] are the corresponding y coordinates (latitudes for the
     PLplot supplied data).  After the call to mapform(), x[] and y[]
     should be replaced by the corresponding plot coordinates.  If no
     transform is desired, mapform can be replaced by NULL.

‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the type of map plotted.  This
     is either one of the PLplot built-in maps or the file name of a set
     of Shapefile files without the file extensions.  For the PLplot
     built-in maps the possible values are:

        • ‘"globe"’ - continental outlines

        • ‘"usa"’ - USA and state boundaries

        • ‘"cglobe"’ - continental outlines and countries

        • ‘"usaglobe"’ - USA, state boundaries and continental outlines

‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum x value of map elements to be drawn.  The units must
     match the shapefile (built in maps are degrees lat/lon).  Objects
     in the file which do not encroach on the box defined by minx, maxx,
     miny, maxy will not be rendered.  But note this is simply an
     optimisation, not a clipping so for objects with some points inside
     the box and some points outside the box all the points will be
     rendered.  These parameters also define latitude and longitude
     wrapping for shapefiles using these units.  Longitude points will
     be wrapped by integer multiples of 360 degrees to place them in the
     box.  This allows the same data to be used on plots from -180-180
     or 0-360 longitude ranges.  In fact if you plot from -180-540 you
     will get two cycles of data drawn.  The value of minx must be less
     than the value of maxx.  Passing in a nan, max/-max floating point
     number or +/-infinity will case the bounding box from the shapefile
     to be used.

‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum x value of map elements to be drawn - see minx.

‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum y value of map elements to be drawn - see minx.

‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum y value of map elements to be drawn - see minx.

   Redacted form: ‘plmap(mapform, name, minx, maxx, miny, maxy)’

   This function is used in example 19.


File: plplotdoc.info,  Node: plmapfill; Plot all or a subset of Shapefile data; filling the polygons,  Next: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates,  Prev: plmap; Plot continental outline or shapefile data in world coordinates,  Up: The Common API for PLplot

17.76 plmapfill: Plot all or a subset of Shapefile data, filling the polygons
=============================================================================

     plmapfill ( mapform , name , minx , maxx , miny , maxy ,
     plotentries , nplotentries );

   As per ‘plmapline’ (*note plmapline; Plot all or a subset of
Shapefile data using lines in world coordinates::), however the items
are filled in the same way as ‘plfill’ (*note plfill; Draw filled
polygon::).

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the coordinates given in the
     shapefile into a plot coordinate system.  By using this transform,
     we can change from a longitude, latitude coordinate to a polar
     stereographic project, for example.  Initially, x[0]..[n-1] are the
     longitudes and y[0]..y[n-1] are the corresponding latitudes.  After
     the call to mapform(), x[] and y[] should be replaced by the
     corresponding plot coordinates.  If no transform is desired,
     mapform can be replaced by NULL.

‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the file name of a set of
     Shapefile files without the file extension.

‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum x value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example longitude or
     distance.  The value of minx must be less than the value of maxx.

‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum x value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum y value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example latitude or
     distance.  The value of miny must be less than the value of maxy.

‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum y value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing the zero-based indices of the Shapefile
     elements which will be drawn.  Setting ‘plotentries’ to NULL will
     plot all elements of the Shapefile.

‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of items in ‘plotentries’.  Ignored if ‘plotentries’ is
     NULL.

   Redacted form: ‘plmapfill(mapform, name, minx, maxx, miny, maxy,
plotentries)’

   This function is used in example 19.


File: plplotdoc.info,  Node: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates,  Next: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates,  Prev: plmapfill; Plot all or a subset of Shapefile data; filling the polygons,  Up: The Common API for PLplot

17.77 plmapline: Plot all or a subset of Shapefile data using lines in world coordinates
========================================================================================

     plmapline ( mapform , name , minx , maxx , miny , maxy ,
     plotentries , nplotentries );

   Plot all or a subset of Shapefile data using lines in world
coordinates.  Our 19th standard example demonstrates how to use this
function.  This function plots data from a Shapefile using lines as in
‘plmap’ (*note plmap; Plot continental outline or shapefile data in
world coordinates::), however it also has the option of also only
drawing specified elements from the Shapefile.  The vector of indices of
the required elements are passed as a function argument.  The Shapefile
data should include a metadata file (extension.dbf) listing all items
within the Shapefile.  This file can be opened by most popular
spreadsheet programs and can be used to decide which indices to pass to
this function.

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the coordinates given in the
     shapefile into a plot coordinate system.  By using this transform,
     we can change from a longitude, latitude coordinate to a polar
     stereographic project, for example.  Initially, x[0]..[n-1] are the
     longitudes and y[0]..y[n-1] are the corresponding latitudes.  After
     the call to mapform(), x[] and y[] should be replaced by the
     corresponding plot coordinates.  If no transform is desired,
     mapform can be replaced by NULL.

‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the file name of a set of
     Shapefile files without the file extension.

‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum x value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example longitude or
     distance.  The value of minx must be less than the value of maxx.

‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum x value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum y value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example latitude or
     distance.  The value of miny must be less than the value of maxy.

‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum y value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing the zero-based indices of the Shapefile
     elements which will be drawn.  Setting ‘plotentries’ to NULL will
     plot all elements of the Shapefile.

‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of items in ‘plotentries’.  Ignored if ‘plotentries’ is
     NULL.

   Redacted form: ‘plmapline(mapform, name, minx, maxx, miny, maxy,
plotentries)’

   This function is used in example 19.


File: plplotdoc.info,  Node: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates,  Next: plmaptex; Draw text at points defined by Shapefile data in world coordinates,  Prev: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates,  Up: The Common API for PLplot

17.78 plmapstring: Plot all or a subset of Shapefile data using strings or points in world coordinates
======================================================================================================

     plmapstring ( mapform , name , string , minx , maxx , miny , maxy ,
     plotentries , nplotentries );

   As per ‘plmapline’ (*note plmapline; Plot all or a subset of
Shapefile data using lines in world coordinates::), however the items
are plotted as strings or points in the same way as ‘plstring’ (*note
plstring; Plot a glyph at the specified points::).

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the coordinates given in the
     shapefile into a plot coordinate system.  By using this transform,
     we can change from a longitude, latitude coordinate to a polar
     stereographic project, for example.  Initially, x[0]..[n-1] are the
     longitudes and y[0]..y[n-1] are the corresponding latitudes.  After
     the call to mapform(), x[] and y[] should be replaced by the
     corresponding plot coordinates.  If no transform is desired,
     mapform can be replaced by NULL.

‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the file name of a set of
     Shapefile files without the file extension.

‘string’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be drawn.

‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum x value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example longitude or
     distance.  The value of minx must be less than the value of maxx.

‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum x value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum y value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example latitude or
     distance.  The value of miny must be less than the value of maxy.

‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum y value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing the zero-based indices of the Shapefile
     elements which will be drawn.  Setting ‘plotentries’ to NULL will
     plot all elements of the Shapefile.

‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of items in ‘plotentries’.  Ignored if ‘plotentries’ is
     NULL.

   Redacted form: ‘plmapstring(mapform, name, string, minx, maxx, miny,
maxy, plotentries)’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plmaptex; Draw text at points defined by Shapefile data in world coordinates,  Next: plmeridians; Plot latitude and longitude lines,  Prev: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates,  Up: The Common API for PLplot

17.79 plmaptex: Draw text at points defined by Shapefile data in world coordinates
==================================================================================

     plmaptex ( mapform , name , dx , dy , just , text , minx , maxx ,
     miny , maxy , plotentry );

   As per ‘plmapline’ (*note plmapline; Plot all or a subset of
Shapefile data using lines in world coordinates::), however the items
are plotted as text in the same way as ‘plptex’ (*note plptex; Write
text inside the viewport::).

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the coordinates given in the
     shapefile into a plot coordinate system.  By using this transform,
     we can change from a longitude, latitude coordinate to a polar
     stereographic project, for example.  Initially, x[0]..[n-1] are the
     longitudes and y[0]..y[n-1] are the corresponding latitudes.  After
     the call to mapform(), x[] and y[] should be replaced by the
     corresponding plot coordinates.  If no transform is desired,
     mapform can be replaced by NULL.

‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the file name of a set of
     Shapefile files without the file extension.

‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Used to define the slope of the texts which is dy/dx.

‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Used to define the slope of the texts which is dy/dx.

‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Set the justification of the text.  The value given will be the
     fraction of the distance along the string that sits at the given
     point.  0.0 gives left aligned text, 0.5 gives centralized text and
     1.0 gives right aligned text.

‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be drawn.

‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum x value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example longitude or
     distance.  The value of minx must be less than the value of maxx.

‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum x value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum y value to be plotted.  This must be in the same units
     as used by the Shapefile.  You could use a very large negative
     number to plot everything, but you can improve performance by
     limiting the area drawn.  The units must match those of the
     Shapefile projection, which may be for example latitude or
     distance.  The value of miny must be less than the value of maxy.

‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum y value to be plotted.  You could use a very large
     number to plot everything, but you can improve performance by
     limiting the area drawn.

‘plotentry’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     An integer indicating which text string of the Shapefile (zero
     indexed) will be drawn.

   Redacted form: ‘plmaptex(mapform, name, dx, dy, just, text, minx,
maxx, miny, maxy, plotentry)’

   This function is used in example 19.


File: plplotdoc.info,  Node: plmeridians; Plot latitude and longitude lines,  Next: plmesh; Plot surface mesh,  Prev: plmaptex; Draw text at points defined by Shapefile data in world coordinates,  Up: The Common API for PLplot

17.80 plmeridians: Plot latitude and longitude lines
====================================================

     plmeridians ( mapform , dlong , dlat , minlong , maxlong , minlat ,
     maxlat );

   Displays latitude and longitude on the current plot.  The lines are
plotted in the current color and line style.

‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input)
     A user supplied function to transform the coordinate longitudes and
     latitudes to a plot coordinate system.  By using this transform, we
     can change from a longitude, latitude coordinate to a polar
     stereographic project, for example.  Initially, x[0]..[n-1] are the
     longitudes and y[0]..y[n-1] are the corresponding latitudes.  After
     the call to mapform(), x[] and y[] should be replaced by the
     corresponding plot coordinates.  If no transform is desired,
     mapform can be replaced by NULL.

‘dlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The interval in degrees at which the longitude lines are to be
     plotted.

‘dlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The interval in degrees at which the latitude lines are to be
     plotted.

‘minlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The value of the longitude on the left side of the plot.  The value
     of minlong must be less than the value of maxlong, and the quantity
     maxlong-minlong must be less than or equal to 360.

‘maxlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The value of the longitude on the right side of the plot.

‘minlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum latitude to be plotted on the background.  One can
     always use -90.0 as the boundary outside the plot window will be
     automatically eliminated.  However, the program will be faster if
     one can reduce the size of the background plotted.

‘maxlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum latitudes to be plotted on the background.  One can
     always use 90.0 as the boundary outside the plot window will be
     automatically eliminated.

   Redacted form: ‘plmeridians(mapform, dlong, dlat, minlong, maxlong,
minlat, maxlat)’

   This function is used in example 19.


File: plplotdoc.info,  Node: plmesh; Plot surface mesh,  Next: plmeshc; Magnitude colored plot surface mesh with contour,  Prev: plmeridians; Plot latitude and longitude lines,  Up: The Common API for PLplot

17.81 plmesh: Plot surface mesh
===============================

     plmesh ( x , y , z , nx , ny , opt );

   Plots a surface mesh within the environment set up by ‘plw3d’ (*note
plw3d; Configure the transformations required for projecting a 3D
surface on a 2D window::).  The surface is defined by the matrix ‘
‘z’[‘nx’][‘ny’] ’, the point ‘‘z’[i][j]’ being the value of the function
at ‘(‘x’[i], ‘y’[j])’.  Note that the points in vectors ‘‘x’’ and ‘‘y’’
do not need to be equally spaced, but must be stored in ascending order.
The parameter ‘‘opt’’ controls the way in which the surface is
displayed.  For further details see *note Three-dimensional Plots::.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates at which the function is
     evaluated.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates at which the function is
     evaluated.

‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘x’’ values at which function has been evaluated.

‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘y’’ values at which function has been evaluated.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Determines the way in which the surface is represented:

        • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’.

        • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’.

        • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting
          points at which function is defined.

   Redacted form: ‘plmesh(x, y, z, opt)’

   This function is used in example 11.


File: plplotdoc.info,  Node: plmeshc; Magnitude colored plot surface mesh with contour,  Next: plmkstrm; Creates a new stream and makes it the default,  Prev: plmesh; Plot surface mesh,  Up: The Common API for PLplot

17.82 plmeshc: Magnitude colored plot surface mesh with contour
===============================================================

     plmeshc ( x , y , z , nx , ny , opt , clevel , nlevel );

   A more powerful form of ‘plmesh (*note plmesh; Plot surface mesh::)’:
the surface mesh can be colored accordingly to the current z value being
plotted, a contour plot can be drawn at the base XY plane, and a curtain
can be drawn between the plotted function border and the base XY plane.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates at which the function is
     evaluated.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates at which the function is
     evaluated.

‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘x’’ values at which function is evaluated.

‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘y’’ values at which function is evaluated.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Determines the way in which the surface is represented.  To specify
     more than one option just add the options, e.g.  DRAW_LINEXY +
     MAG_COLOR

        • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’.

        • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’.

        • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting
          points at which function is defined.

        • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored
          according to the z value being plotted.  The color is used
          from the current cmap1.

        • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY
          plane using parameters ‘nlevel’ and ‘clevel’.

        • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY
          plane and the borders of the plotted function.

‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the contour levels.

‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of elements in the ‘clevel’ vector.

   Redacted form: ‘plmeshc(x, y, z, opt, clevel)’

   This function is used in example 11.


File: plplotdoc.info,  Node: plmkstrm; Creates a new stream and makes it the default,  Next: plmtex; Write text relative to viewport boundaries,  Prev: plmeshc; Magnitude colored plot surface mesh with contour,  Up: The Common API for PLplot

17.83 plmkstrm: Creates a new stream and makes it the default
=============================================================

     plmkstrm ( p_strm );

   Creates a new stream and makes it the default.  Differs from using
‘plsstrm’ (*note plsstrm; Set current output stream::), in that a free
stream number is found, and returned.  Unfortunately, I _have_ to start
at stream 1 and work upward, since stream 0 is preallocated.  One of the
_big_ flaws in the PLplot API is that no initial, library-opening call
is required.  So stream 0 must be preallocated, and there is no simple
way of determining whether it is already in use or not.

‘p_strm’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output)
     Returned value of the stream number of the created stream.

   Redacted form: ‘plmkstrm(p_strm)’

   This function is used in examples 1 and 20.


File: plplotdoc.info,  Node: plmtex; Write text relative to viewport boundaries,  Next: plmtex3; Write text relative to viewport boundaries in 3D plots,  Prev: plmkstrm; Creates a new stream and makes it the default,  Up: The Common API for PLplot

17.84 plmtex: Write text relative to viewport boundaries
========================================================

     plmtex ( side , disp , pos , just , text );

   Writes text at a specified position relative to the viewport
boundaries.  Text may be written inside or outside the viewport, but is
clipped at the subpage boundaries.  The reference point of a string lies
along a line passing through the string at half the height of a capital
letter.  The position of the reference point along this line is
determined by ‘ ‘just’ ’, and the position of the reference point
relative to the viewport is set by ‘ ‘disp’ ’ and ‘ ‘pos’ ’.

‘side’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the side of the viewport along
     which the text is to be written.  The string must be one of:

        • ‘b’: Bottom of viewport, text written parallel to edge.

        • ‘bv’: Bottom of viewport, text written at right angles to
          edge.

        • ‘l’: Left of viewport, text written parallel to edge.

        • ‘lv’: Left of viewport, text written at right angles to edge.

        • ‘r’: Right of viewport, text written parallel to edge.

        • ‘rv’: Right of viewport, text written at right angles to edge.

        • ‘t’: Top of viewport, text written parallel to edge.

        • ‘tv’: Top of viewport, text written at right angles to edge.

‘disp’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Position of the reference point of string, measured outwards from
     the specified viewport edge in units of the current character
     height.  Use negative ‘‘disp’’ to write within the viewport.

‘pos’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Position of the reference point of string along the specified edge,
     expressed as a fraction of the length of the edge.

‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Specifies the position of the string relative to its reference
     point.  If ‘ ‘just’=0. ’, the reference point is at the left and if
     ‘ ‘just’=1. ’, it is at the right of the string.  Other values of ‘
     ‘just’ ’ give intermediate justifications.

‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be written out.

   Redacted form:

   • General: ‘plmtex(side, disp, pos, just, text)’

   This function is used in examples 3, 4, 6-8, 11, 12, 14, 18, 23, and
26.


File: plplotdoc.info,  Node: plmtex3; Write text relative to viewport boundaries in 3D plots,  Next: plot3d; Plot 3-d surface plot,  Prev: plmtex; Write text relative to viewport boundaries,  Up: The Common API for PLplot

17.85 plmtex3: Write text relative to viewport boundaries in 3D plots
=====================================================================

     plmtex3 ( side , disp , pos , just , text );

   Writes text at a specified position relative to the viewport
boundaries.  Text may be written inside or outside the viewport, but is
clipped at the subpage boundaries.  The reference point of a string lies
along a line passing through the string at half the height of a capital
letter.  The position of the reference point along this line is
determined by ‘ ‘just’ ’, and the position of the reference point
relative to the viewport is set by ‘ ‘disp’ ’ and ‘ ‘pos’ ’.

‘side’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string specifying the side of the viewport along
     which the text is to be written.  The string should contain one or
     more of the following characters: ‘[xyz][ps][v]’.  Only one label
     is drawn at a time, i.e.  ‘xyp’ will only label the X axis, not
     both the X and Y axes.

        • ‘x’: Label the X axis.

        • ‘y’: Label the Y axis.

        • ‘z’: Label the Z axis.

        • ‘p’: Label the ‘primary’ axis.  For Z this is the leftmost Z
          axis.  For X it is the axis that starts at y-min.  For Y it is
          the axis that starts at x-min.

        • ‘s’: Label the ‘secondary’ axis.

        • ‘v’: Draw the text perpendicular to the axis.

‘disp’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Position of the reference point of string, measured outwards from
     the specified viewport edge in units of the current character
     height.  Use negative ‘‘disp’’ to write within the viewport.

‘pos’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Position of the reference point of string along the specified edge,
     expressed as a fraction of the length of the edge.

‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Specifies the position of the string relative to its reference
     point.  If ‘ ‘just’=0. ’, the reference point is at the left and if
     ‘ ‘just’=1. ’, it is at the right of the string.  Other values of ‘
     ‘just’ ’ give intermediate justifications.

‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be written out.

   Redacted form: ‘plmtex3(side, disp, pos, just, text)’

   This function is used in example 28.


File: plplotdoc.info,  Node: plot3d; Plot 3-d surface plot,  Next: plot3dc; Magnitude colored plot surface with contour,  Prev: plmtex3; Write text relative to viewport boundaries in 3D plots,  Up: The Common API for PLplot

17.86 plot3d: Plot 3-d surface plot
===================================

     plot3d ( x , y , z , nx , ny , opt , side );

   Plots a three-dimensional surface plot within the environment set up
by ‘plw3d’ (*note plw3d; Configure the transformations required for
projecting a 3D surface on a 2D window::).  The surface is defined by
the matrix ‘ ‘z’[‘nx’][‘ny’] ’, the point ‘‘z’[i][j]’ being the value of
the function at ‘(‘x’[i],‘y’[j])’.  Note that the points in vectors
‘‘x’’ and ‘‘y’’ do not need to be equally spaced, but must be stored in
ascending order.  The parameter ‘‘opt’’ controls the way in which the
surface is displayed.  For further details see *note Three-dimensional
Plots::.  The only difference between ‘plmesh’ (*note plmesh; Plot
surface mesh::) and ‘plot3d’ (*note plot3d; Plot 3-d surface plot::) is
that ‘plmesh’ (*note plmesh; Plot surface mesh::) draws the bottom side
of the surface, while ‘plot3d’ (*note plot3d; Plot 3-d surface plot::)
only draws the surface as viewed from the top.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates at which the function is
     evaluated.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates at which the function is
     evaluated.

‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘x’’ values at which function is evaluated.

‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘y’’ values at which function is evaluated.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Determines the way in which the surface is represented:

        • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’.

        • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’.

        • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting
          points at which function is defined.

‘side’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     Flag to indicate whether or not "sides" should be draw on the
     figure.  If ‘ ‘side’ ’ is true sides are drawn, otherwise no sides
     are drawn.

   Redacted form: ‘plot3d(x, y, z, opt, side)’

   This function is used in examples 11 and 21.


File: plplotdoc.info,  Node: plot3dc; Magnitude colored plot surface with contour,  Next: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Prev: plot3d; Plot 3-d surface plot,  Up: The Common API for PLplot

17.87 plot3dc: Magnitude colored plot surface with contour
==========================================================

     plot3dc ( x , y , z , nx , ny , opt , clevel , nlevel );

   Aside from dropping the ‘side’ functionality this is a more powerful
form of ‘plot3d (*note plot3d; Plot 3-d surface plot::)’: the surface
mesh can be colored accordingly to the current z value being plotted, a
contour plot can be drawn at the base XY plane, and a curtain can be
drawn between the plotted function border and the base XY plane.  The
arguments are identical to those of ‘plmeshc (*note plmeshc; Magnitude
colored plot surface mesh with contour::)’.  The only difference between
‘plmeshc’ (*note plmeshc; Magnitude colored plot surface mesh with
contour::) and ‘plot3dc’ (*note plot3dc; Magnitude colored plot surface
with contour::) is that ‘plmeshc’ (*note plmeshc; Magnitude colored plot
surface mesh with contour::) draws the bottom side of the surface, while
‘plot3dc’ (*note plot3dc; Magnitude colored plot surface with contour::)
only draws the surface as viewed from the top.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates at which the function is
     evaluated.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates at which the function is
     evaluated.

‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘x’’ values at which function is evaluated.

‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘ ‘y’ ’ values at which function is evaluated.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Determines the way in which the surface is represented.  To specify
     more than one option just add the options, e.g.  DRAW_LINEXY +
     MAG_COLOR

        • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’.

        • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’.

        • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting
          points at which function is defined.

        • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored
          according to the z value being plotted.  The color is used
          from the current cmap1.

        • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY
          plane using parameters ‘nlevel’ and ‘clevel’.

        • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY
          plane and the borders of the plotted function.

‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the contour levels.

‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of elements in the ‘clevel’ vector.

   Redacted form:

   • General: ‘plot3dc(x, y, z, opt, clevel)’

   This function is used in example 21.


File: plplotdoc.info,  Node: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Next: plparseopts; Parse command-line arguments,  Prev: plot3dc; Magnitude colored plot surface with contour,  Up: The Common API for PLplot

17.88 plot3dcl: Magnitude colored plot surface with contour for z[x][y] with y index limits
===========================================================================================

     plot3dcl ( x , y , z , nx , ny , opt , clevel , nlevel , indexxmin
     , indexxmax , indexymin , indexymax );

   When the implementation is completed this variant of ‘plot3dc’ (*note
plot3dc; Magnitude colored plot surface with contour::) (see that
function's documentation for more details) should be suitable for the
case where the area of the ‘‘x’’, ‘‘y’’ coordinate grid where ‘‘z’’ is
defined can be non-rectangular.  The implementation is incomplete so the
last 4 parameters of plot3dcl; ‘ ‘indexxmin’ ’, ‘ ‘indexxmax’ ’, ‘
‘indexymin’ ’, and ‘ ‘indexymax’ ’; are currently ignored and the
functionality is otherwise identical to that of ‘plot3dc’ (*note
plot3dc; Magnitude colored plot surface with contour::).

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates at which the function is
     evaluated.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates at which the function is
     evaluated.

‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input)
     A matrix containing function values to plot.  Should have
     dimensions of ‘nx’ by ‘ny’.

‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘‘x’’ values at which the function is evaluated.

‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of ‘ ‘y’ ’ values at which the function is evaluated.

‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Determines the way in which the surface is represented.  To specify
     more than one option just add the options, e.g.  DRAW_LINEXY +
     MAG_COLOR

        • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’.

        • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a
          function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’.

        • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting
          points at which function is defined.

        • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored
          according to the z value being plotted.  The color is used
          from the current cmap1.

        • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY
          plane using parameters ‘nlevel’ and ‘clevel’.

        • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY
          plane and the borders of the plotted function.

‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the contour levels.

‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of elements in the ‘clevel’ vector.

‘indexxmin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The index value (which must be ≥ 0) that corresponds to the first ‘
     ‘x’ ’ index where ‘ ‘z’ ’ is defined.

‘indexxmax’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The index value (which must be ≤ ‘ ‘nx’ ’) which corresponds (by
     convention) to one more than the last ‘ ‘x’ ’ index value where ‘
     ‘z’ ’ is defined.

‘indexymin’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘‘y’’ index values which all must be ≥ 0.
     These values are the first ‘‘y’’ index where ‘‘z’’ is defined for a
     particular ‘‘x’ ’ index in the range from ‘‘indexxmin’ ’ to
     ‘‘indexxmax - 1’’.  The dimension of ‘‘indexymin’’ is
     ‘‘indexxmax’’.

‘indexymax’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘‘y’’ index values which all must be ≤ ‘‘ny’’.
     These values correspond (by convention) to one more than the last
     ‘‘y’’ index where ‘‘z’’ is defined for a particular ‘‘x’’ index in
     the range from ‘‘indexxmin’’ to ‘‘indexxmax - 1’’.  The dimension
     of ‘‘indexymax’’ is ‘‘indexxmax’’.

   Redacted form:

   • General: ‘ plot3dcl(x, y, z, opt, clevel, indexxmin, indexymin,
     indexymax) ’

   This function is not used in any example.


File: plplotdoc.info,  Node: plparseopts; Parse command-line arguments,  Next: plpat; Set area line fill pattern,  Prev: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits,  Up: The Common API for PLplot

17.89 plparseopts: Parse command-line arguments
===============================================

     PLINT plparseopts ( p_argc , argv , mode );

   Parse command-line arguments.

   ‘plparseopts’ (*note plparseopts; Parse command-line arguments::)
removes all recognized flags (decreasing argc accordingly), so that
invalid input may be readily detected.  It can also be used to process
user command line flags.  The user can merge an option table of type
PLOptionTable into the internal option table info structure using
‘plMergeOpts’ (*note plMergeOpts; Merge use option table into internal
info structure::).  Or, the user can specify that ONLY the external
table(s) be parsed by calling ‘plClearOpts’ (*note plClearOpts; Clear
internal option table info structure::) before ‘plMergeOpts’ (*note
plMergeOpts; Merge use option table into internal info structure::).

   The default action taken by ‘plparseopts’ (*note plparseopts; Parse
command-line arguments::) is as follows:

Returns with an error if an unrecognized option or badly formed
option-value pair are encountered.
Returns immediately (return code 0) when the first non-option command
line argument is found.
Returns with the return code of the option handler, if one was called.
Deletes command line arguments from argv list as they are found, and
decrements argc accordingly.
Does not show "invisible" options in usage or help messages.
Assumes the program name is contained in argv[0].

   These behaviors may be controlled through the ‘mode’ argument.

‘p_argc’ (‘int *’, input/output)
     Number of arguments.

‘argv’ (‘‘PLCHAR_NC_MATRIX’ (*note PLCHAR_NC_MATRIX-type::)’, input/output)
     A vector of character strings containing ‘‘*p_argc’’ command-line
     arguments.

‘mode’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Parsing mode with the following possibilities:

        • PL_PARSE_FULL (1) - Full parsing of command line and all error
          messages enabled, including program exit when an error occurs.
          Anything on the command line that isn't recognized as a valid
          option or option argument is flagged as an error.

        • PL_PARSE_QUIET (2) - Turns off all output except in the case
          of errors.

        • PL_PARSE_NODELETE (4) - Turns off deletion of processed
          arguments.

        • PL_PARSE_SHOWALL (8) - Show invisible options

        • PL_PARSE_NOPROGRAM (32) - Specified if argv[0] is NOT a
          pointer to the program name.

        • PL_PARSE_NODASH (64) - Set if leading dash is NOT required.

        • PL_PARSE_SKIP (128) - Set to quietly skip over any
          unrecognized arguments.

   Redacted form:

   • General: ‘plparseopts(argv, mode)’

   This function is used in all of the examples.


File: plplotdoc.info,  Node: plpat; Set area line fill pattern,  Next: plpath; Draw a line between two points; accounting for coordinate transforms,  Prev: plparseopts; Parse command-line arguments,  Up: The Common API for PLplot

17.90 plpat: Set area line fill pattern
=======================================

     plpat ( nlin , inc , del );

   Sets the area line fill pattern to be used, e.g., for calls to
‘plfill’ (*note plfill; Draw filled polygon::).  The pattern consists of
1 or 2 sets of parallel lines with specified inclinations and spacings.
The arguments to this routine are the number of sets to use (1 or 2)
followed by two vectors (with 1 or 2 elements) specifying the
inclinations in tenths of a degree and the spacing in micrometers.  (See
also ‘plpsty’ (*note plpsty; Select area fill pattern::))

‘nlin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of sets of lines making up the pattern, either 1 or 2.

‘inc’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘‘nlin’’ values of the inclination in tenths of
     a degree.  (Should be between -900 and 900).

‘del’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing ‘‘nlin’’ values of the spacing in micrometers
     between the lines making up the pattern.

   Redacted form:

   • General: ‘plpat(inc, del)’

   This function is used in example 15.


File: plplotdoc.info,  Node: plpath; Draw a line between two points; accounting for coordinate transforms,  Next: plpoin; Plot a glyph at the specified points,  Prev: plpat; Set area line fill pattern,  Up: The Common API for PLplot

17.91 plpath: Draw a line between two points, accounting for coordinate transforms
==================================================================================

     plpath ( n , x1 , y1 , x2 , y2 );

   Joins the point ‘ (‘x1’, ‘y1’) ’ to ‘ (‘x2’, ‘y2’) ’.  If a global
coordinate transform is defined then the line is broken in to ‘ ‘n’ ’
segments to approximate the path.  If no transform is defined then this
simply acts like a call to ‘pljoin’ (*note pljoin; Draw a line between
two points::).

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     number of points to use to approximate the path.

‘x1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x coordinate of first point.

‘y1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y coordinate of first point.

‘x2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x coordinate of second point.

‘y2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y coordinate of second point.

   Redacted form: ‘plpath(n,x1,y1,x2,y2)’

   This function is used in example 22.


File: plplotdoc.info,  Node: plpoin; Plot a glyph at the specified points,  Next: plpoin3; Plot a glyph at the specified 3D points,  Prev: plpath; Draw a line between two points; accounting for coordinate transforms,  Up: The Common API for PLplot

17.92 plpoin: Plot a glyph at the specified points
==================================================

     plpoin ( n , x , y , code );

   Plot a glyph at the specified points.  (This function is largely
superseded by ‘plstring’ (*note plstring; Plot a glyph at the specified
points::) which gives access to many[!]  more glyphs.)  ‘ ‘code’=-1 ’
means try to just draw a point.  Right now it's just a move and a draw
at the same place.  Not ideal, since a sufficiently intelligent output
device may optimize it away, or there may be faster ways of doing it.
This is OK for now, though, and offers a 4X speedup over drawing a
Hershey font "point" (which is actually diamond shaped and therefore
takes 4 strokes to draw).  If 0 < code < 32, then a useful (but small
subset) of Hershey symbols is plotted.  If 32 <= code <= 127 the
corresponding printable ASCII character is plotted.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of points in the ‘ ‘x’ ’ and ‘ ‘y’ ’ vectors.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of points.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of points.

‘code’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Hershey symbol code (in "ascii-indexed" form with -1 <= code <=
     127) corresponding to a glyph to be plotted at each of the ‘ ‘n’ ’
     points.

   Redacted form: ‘plpoin(x, y, code)’

   This function is used in examples 1, 6, 14, and 29.


File: plplotdoc.info,  Node: plpoin3; Plot a glyph at the specified 3D points,  Next: plpoly3; Draw a polygon in 3 space,  Prev: plpoin; Plot a glyph at the specified points,  Up: The Common API for PLplot

17.93 plpoin3: Plot a glyph at the specified 3D points
======================================================

     plpoin3 ( n , x , y , z , code );

   Plot a glyph at the specified 3D points.  (This function is largely
superseded by ‘plstring3’ (*note plstring3; Plot a glyph at the
specified 3D points::) which gives access to many[!]  more glyphs.)  Set
up the call to this function similar to what is done for ‘plline3’
(*note plline3; Draw a line in 3 space::).  ‘ ‘code’=-1 ’ means try to
just draw a point.  Right now it's just a move and a draw at the same
place.  Not ideal, since a sufficiently intelligent output device may
optimize it away, or there may be faster ways of doing it.  This is OK
for now, though, and offers a 4X speedup over drawing a Hershey font
"point" (which is actually diamond shaped and therefore takes 4 strokes
to draw).  If 0 < code < 32, then a useful (but small subset) of Hershey
symbols is plotted.  If 32 <= code <= 127 the corresponding printable
ASCII character is plotted.

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of points in the ‘ ‘x’ ’ and ‘ ‘y’ ’ vectors.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the x coordinates of points.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the y coordinates of points.

‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the z coordinates of points.

‘code’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Hershey symbol code (in "ascii-indexed" form with -1 <= code <=
     127) corresponding to a glyph to be plotted at each of the ‘ ‘n’ ’
     points.

   Redacted form: ‘plpoin3(x, y, z, code)’

   This function is not used in any example.


File: plplotdoc.info,  Node: plpoly3; Draw a polygon in 3 space,  Next: plprec; Set precision in numeric labels,  Prev: plpoin3; Plot a glyph at the specified 3D points,  Up: The Common API for PLplot

17.94 plpoly3: Draw a polygon in 3 space
========================================

     plpoly3 ( n , x , y , z , draw , ifcc );

   Draws a polygon in 3 space defined by ‘ ‘n’ ’ points in ‘ ‘x’ ’, ‘
‘y’ ’, and ‘ ‘z’ ’.  Setup like ‘plline3’ (*note plline3; Draw a line in
3 space::), but differs from that function in that ‘plpoly3’ (*note
plpoly3; Draw a polygon in 3 space::) attempts to determine if the
polygon is viewable depending on the order of the points within the
vector and the value of ‘‘ifcc’’.  If the back of polygon is facing the
viewer, then it isn't drawn.  If this isn't what you want, then use
‘plline3’ (*note plline3; Draw a line in 3 space::) instead.

   The points are assumed to be in a plane, and the directionality of
the plane is determined from the first three points.  Additional points
do not _have_ to lie on the plane defined by the first three, but if
they do not, then the determination of visibility obviously can't be
100% accurate...  So if you're 3 space polygons are too far from planar,
consider breaking them into smaller polygons.  ‘3 points define a plane’
:-).

   _Bugs_: If one of the first two segments is of zero length, or if
they are co-linear, the calculation of visibility has a 50/50 chance of
being correct.  Avoid such situations :-).  See ‘x18c.c’ for an example
of this problem.  (Search for ‘20.1’).

‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of points defining line.

‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘n’ x coordinates of points.

‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘n’ y coordinates of points.

‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing ‘n’ z coordinates of points.

‘draw’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input)
     A vector containing ‘n-1’ Boolean values which control drawing the
     segments of the polygon.  If ‘‘draw[i]’’ is true, then the polygon
     segment from index ‘‘[i]’’ to ‘‘[i+1]’’ is drawn, otherwise, not.

‘ifcc’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     If ‘ ‘ifcc’ ’ is true the directionality of the polygon is
     determined by assuming the points are laid out in a
     counter-clockwise order.  Otherwise, the directionality of the
     polygon is determined by assuming the points are laid out in a
     clockwise order.

   Redacted form: ‘plpoly3(x, y, z, code)’

   This function is used in example 18.


File: plplotdoc.info,  Node: plprec; Set precision in numeric labels,  Next: plpsty; Select area fill pattern,  Prev: plpoly3; Draw a polygon in 3 space,  Up: The Common API for PLplot

17.95 plprec: Set precision in numeric labels
=============================================

     plprec ( setp , prec );

   Sets the number of places after the decimal point in numeric labels.

‘setp’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     If ‘ ‘setp’ ’ is equal to 0 then PLplot automatically determines
     the number of places to use after the decimal point in numeric
     labels (like those used to label axes).  If ‘ ‘setp’ ’ is 1 then ‘
     ‘prec’ ’ sets the number of places.

‘prec’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The number of characters to draw after the decimal point in numeric
     labels.

   Redacted form: ‘plprec(setp, prec)’

   This function is used in example 29.


File: plplotdoc.info,  Node: plpsty; Select area fill pattern,  Next: plptex; Write text inside the viewport,  Prev: plprec; Set precision in numeric labels,  Up: The Common API for PLplot

17.96 plpsty: Select area fill pattern
======================================

     plpsty ( patt );

   If ‘patt’ is zero or less use either a hardware solid fill if the
drivers have that capability (virtually all do) or fall back to a
software emulation of a solid fill using the eighth area line fill
pattern.  If 0 < ‘patt’ ≤ 8, then select one of eight predefined area
line fill patterns to use (see ‘plpat’ (*note plpat; Set area line fill
pattern::) if you desire other patterns).

‘patt’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The desired pattern index.  If ‘patt’ is zero or less, then a solid
     fill is (normally, see qualifiers above) used.  For ‘patt’ in the
     range from 1 to 8 and assuming the driver has not supplied line
     fill capability itself (most deliberately do not so that line fill
     patterns look identical for those drivers), the patterns consist of
     (1) horizontal lines, (2) vertical lines, (3) lines at 45 degrees,
     (4) lines at -45 degrees, (5) lines at 30 degrees, (6) lines at -30
     degrees, (7) both vertical and horizontal lines, and (8) lines at
     both 45 degrees and -45 degrees.

   Redacted form: ‘plpsty(patt)’

   This function is used in examples 12, 13, 15, 16, and 25.


File: plplotdoc.info,  Node: plptex; Write text inside the viewport,  Next: plptex3; Write text inside the viewport of a 3D plot,  Prev: plpsty; Select area fill pattern,  Up: The Common API for PLplot

17.97 plptex: Write text inside the viewport
============================================

     plptex ( x , y , dx , dy , just , text );

   Writes text at a specified position and inclination within the
viewport.  Text is clipped at the viewport boundaries.  The reference
point of a string lies along a line passing through the string at half
the height of a capital letter.  The position of the reference point
along this line is determined by ‘ ‘just’ ’, the reference point is
placed at world coordinates ‘ (‘x’, ‘y’) ’ within the viewport.  The
inclination of the string is specified in terms of differences of world
coordinates making it easy to write text parallel to a line in a graph.

‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x coordinate of reference point of string.

‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y coordinate of reference point of string.

‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘dy’ ’, this specifies the inclination of the
     string.  The baseline of the string is parallel to a line joining ‘
     (‘x’, ‘y’) ’ to ‘ (‘x’+‘dx’, ‘y’+‘dy’) ’.

‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘dx’ ’, this specifies the inclination of the
     string.

‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Specifies the position of the string relative to its reference
     point.  If ‘ ‘just’=0. ’, the reference point is at the left and if
     ‘ ‘just’=1. ’, it is at the right of the string.  Other values of ‘
     ‘just’ ’ give intermediate justifications.

‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be written out.

   Redacted form: ‘plptex(x, y, dx, dy, just, text)’

   This function is used in example 2-4,10,12-14,20,23,24,26.


File: plplotdoc.info,  Node: plptex3; Write text inside the viewport of a 3D plot,  Next: plrandd; Random number generator returning a real random number in the range [0;1],  Prev: plptex; Write text inside the viewport,  Up: The Common API for PLplot

17.98 plptex3: Write text inside the viewport of a 3D plot
==========================================================

     plptex3 ( wx , wy , wz , dx , dy , dz , sx , sy , sz , just , text
     );

   Writes text at a specified position and inclination and with a
specified shear within the viewport.  Text is clipped at the viewport
boundaries.  The reference point of a string lies along a line passing
through the string at half the height of a capital letter.  The position
of the reference point along this line is determined by ‘ ‘just’ ’, and
the reference point is placed at world coordinates ‘ (‘wx’, ‘wy’, ‘wz’)
’ within the viewport.  The inclination and shear of the string is
specified in terms of differences of world coordinates making it easy to
write text parallel to a line in a graph.

‘wx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     x world coordinate of reference point of string.

‘wy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     y world coordinate of reference point of string.

‘wz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     z world coordinate of reference point of string.

‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘dy’ and ‘ dz ’ ’, this specifies the inclination
     of the string.  The baseline of the string is parallel to a line
     joining ‘ (‘x’, ‘y’, ‘z’) ’ to ‘ (‘x’+‘dx’, ‘y’+‘dy’, ‘z’+‘dz’) ’.

‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘dx’ and ‘dz’ ’, this specifies the inclination of
     the string.

‘dz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘dx’ and ‘dy’ ’, this specifies the inclination of
     the string.

‘sx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘sy’ and ‘ sz ’ ’, this specifies the shear of the
     string.  The string is sheared so that the characters are
     vertically parallel to a line joining ‘ (‘x’, ‘y’, ‘z’) ’ to ‘
     (‘x’+‘sx’, ‘y’+‘sy’, ‘z’+‘sz’) ’.  If ‘ ‘sx’ = ‘sy’ = ‘sz’ = 0.) ’
     then the text is not sheared.

‘sy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘sx’ and ‘sz’ ’, this specifies shear of the
     string.

‘sz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Together with ‘ ‘sx’ and ‘sy’ ’, this specifies shear of the
     string.

‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Specifies the position of the string relative to its reference
     point.  If ‘ ‘just’=0. ’, the reference point is at the left and if
     ‘ ‘just’=1. ’, it is at the right of the string.  Other values of ‘
     ‘just’ ’ give intermediate justifications.

‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     A UTF-8 character string to be written out.

   Redacted form: ‘ plptex3(x, y, z, dx, dy, dz, sx, sy, sz, just, text)
’

   This function is used in example 28.


File: plplotdoc.info,  Node: plrandd; Random number generator returning a real random number in the range [0;1],  Next: plreplot; Replays contents of plot buffer to current device/file,  Prev: plptex3; Write text inside the viewport of a 3D plot,  Up: The Common API for PLplot

17.99 plrandd: Random number generator returning a real random number in the range [0,1]
========================================================================================

     plrandd ();

   Random number generator returning a real random number in the range
[0,1].  The generator is based on the Mersenne Twister.  Most languages
/ compilers provide their own random number generator, and so this is
provided purely for convenience and to give a consistent random number
generator across all languages supported by PLplot.  This is
particularly useful for comparing results from the test suite of
examples.

   Redacted form: ‘plrandd()’

   This function is used in examples 17 and 21.


File: plplotdoc.info,  Node: plreplot; Replays contents of plot buffer to current device/file,  Next: plrgbhls; Convert RGB color to HLS,  Prev: plrandd; Random number generator returning a real random number in the range [0;1],  Up: The Common API for PLplot

17.100 plreplot: Replays contents of plot buffer to current device/file
=======================================================================

     plreplot ();

   Replays contents of plot buffer to current device/file.

   Redacted form: ‘plreplot()’

   This function is used in example 1,20.


File: plplotdoc.info,  Node: plrgbhls; Convert RGB color to HLS,  Next: plschr; Set character size,  Prev: plreplot; Replays contents of plot buffer to current device/file,  Up: The Common API for PLplot

17.101 plrgbhls: Convert RGB color to HLS
=========================================

     plrgbhls ( r , g , b , p_h , p_l , p_s );

   Convert RGB color coordinates to HLS

‘r’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Red intensity (0.0-1.0) of the color.

‘g’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Green intensity (0.0-1.0) of the color.

‘b’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Blue intensity (0.0-1.0) of the color.

‘p_h’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the hue in degrees (0.0-360.0) on the color
     cylinder.

‘p_l’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the lightness expressed as a fraction (0.0-1.0)
     of the axis of the color cylinder.

‘p_s’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output)
     Returned value of the saturation expressed as a fraction (0.0-1.0)
     of the radius of the color cylinder.

   Redacted form:

   • General: ‘plrgbhls(r, g, b, p_h, p_l, p_s)’

   This function is used in example 2.


File: plplotdoc.info,  Node: plschr; Set character size,  Next: plscmap0; Set cmap0 colors by 8-bit RGB values,  Prev: plrgbhls; Convert RGB color to HLS,  Up: The Common API for PLplot

17.102 plschr: Set character size
=================================

     plschr ( def , scale );

   This sets up the size of all subsequent characters drawn.  The actual
height of a character is the product of the default character size and a
scaling factor.

‘def’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The default height of a character in millimeters, should be set to
     zero if the default height is to remain unchanged.  For rasterized
     drivers the dx and dy values specified in ‘plspage’ (*note plspage;
     Set page parameters::) are used to convert from mm to pixels (note
     the different unit systems used).  This dpi aware scaling is not
     implemented for all drivers yet.

‘scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Scale factor to be applied to default to get actual character
     height.

   Redacted form: ‘plschr(def, scale)’

   This function is used in examples 2, 13, 23, and 24.


File: plplotdoc.info,  Node: plscmap0; Set cmap0 colors by 8-bit RGB values,  Next: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value,  Prev: plschr; Set character size,  Up: The Common API for PLplot

17.103 plscmap0: Set cmap0 colors by 8-bit RGB values
=====================================================

     plscmap0 ( r , g , b , ncol0 );

   Set cmap0 colors using 8-bit RGB values (see *note Color Map0::).
This sets the entire color map - only as many colors as specified will
be allocated.

‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of red in the color.

‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of green in the color.

‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of blue in the color.

‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, and ‘ ‘b’ ’ vectors.

   Redacted form: ‘plscmap0(r, g, b)’

   This function is used in examples 2 and 24.


File: plplotdoc.info,  Node: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value,  Next: plscmap0n; Set number of colors in cmap0,  Prev: plscmap0; Set cmap0 colors by 8-bit RGB values,  Up: The Common API for PLplot

17.104 plscmap0a: Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value
=========================================================================================

     plscmap0a ( r , g , b , alpha , ncol0 );

   Set cmap0 colors using 8-bit RGB values (see *note Color Map0::) and
PLFLT alpha transparency value.  This sets the entire color map - only
as many colors as specified will be allocated.

‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of red in the color.

‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of green in the color.

‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector containing unsigned 8-bit integers (0-255) representing
     the degree of blue in the color.

‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing values (0.0-1.0) representing the alpha
     transparency of the color.

‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, ‘ ‘b’ ’, and ‘ ‘alpha’ ’
     vectors.

   Redacted form: ‘plscmap0a(r, g, b, alpha)’

   This function is used in examples 30.


File: plplotdoc.info,  Node: plscmap0n; Set number of colors in cmap0,  Next: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Prev: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value,  Up: The Common API for PLplot

17.105 plscmap0n: Set number of colors in cmap0
===============================================

     plscmap0n ( ncol0 );

   Set number of colors in cmap0 (see *note Color Map0::).  Allocate (or
reallocate) cmap0, and fill with default values for those colors not
previously allocated.  The first 16 default colors are given in the
‘plcol0’ (*note plcol0; Set color; cmap0::) documentation.  For larger
indices the default color is red.

   The drivers are not guaranteed to support more than 16 colors.

‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of colors that will be allocated in the cmap0 palette.  If
     this number is zero or less, then the value from the previous call
     to ‘plscmap0n’ (*note plscmap0n; Set number of colors in cmap0::)
     is used and if there is no previous call, then a default value is
     used.

   Redacted form: ‘plscmap0n(ncol0)’

   This function is used in examples 15, 16, and 24.


File: plplotdoc.info,  Node: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Next: plscmap1; Set opaque RGB cmap1 colors values,  Prev: plscmap0n; Set number of colors in cmap0,  Up: The Common API for PLplot

17.106 plscmap1_range: Set the cmap1 argument range for continuous color plots
==============================================================================

     plscmap1_range ( min_color , max_color );

   Set the cmap1 argument range for continuous color plots that
corresponds to the range of data values.  The maximum range
corresponding to the entire cmap1 palette is 0.0-1.0, and the smaller
the cmap1 argument range that is specified with this routine, the
smaller the subset of the cmap1 color palette that is used to represent
the continuous data being plotted.  If ‘min_color’ is greater than
‘max_color’ or ‘max_color’ is greater than 1.0 or ‘min_color’ is less
than 0.0 then no change is made to the cmap1 argument range.  (Use
‘plgcmap1_range’ (*note plgcmap1_range; Get the cmap1 argument range for
continuous color plots::) to get the cmap1 argument range.)

‘min_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The minimum cmap1 argument.  If less than 0.0, then 0.0 is used
     instead.

‘max_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     The maximum cmap1 argument.  If greater than 1.0, then 1.0 is used
     instead.

   Redacted form: ‘plscmap1_range(min_color, max_color)’

   This function is currently used in example 33.


File: plplotdoc.info,  Node: plscmap1; Set opaque RGB cmap1 colors values,  Next: plscmap1a; Set semitransparent cmap1 RGBA colors_,  Prev: plscmap1_range; Set the cmap1 argument range for continuous color plots,  Up: The Common API for PLplot

17.107 plscmap1: Set opaque RGB cmap1 colors values
===================================================

     plscmap1 ( r , g , b , ncol1 );

   Set opaque cmap1 colors (see *note Color Map1::) using RGB vector
values.  This function also sets the number of cmap1 colors.  N.B.
Continuous cmap1 colors are indexed with a floating-point index in the
range from 0.0-1.0 which is linearly transformed (e.g., by ‘plcol1’
(*note plcol1; Set color; cmap1::)) to an integer index of these RGB
vectors in the range from 0 to ‘ncol1-1’.  So in order for this
continuous color model to work properly, it is the responsibility of the
user of ‘plscmap1’ (*note plscmap1; Set opaque RGB cmap1 colors
values::) to insure that these RGB vectors are continuous functions of
their integer indices.

‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of red in the color as a continuous
     function of the integer index of the vector.

‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of green in the color as a continuous
     function of the integer index of the vector.

‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of blue in the color as a continuous
     function of the integer index of the vector.

‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, and ‘ ‘b’ ’ vectors.

   Redacted form: ‘plscmap1(r, g, b)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plscmap1a; Set semitransparent cmap1 RGBA colors_,  Next: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Prev: plscmap1; Set opaque RGB cmap1 colors values,  Up: The Common API for PLplot

17.108 plscmap1a: Set semitransparent cmap1 RGBA colors.
========================================================

     plscmap1a ( r , g , b , alpha , ncol1 );

   Set semitransparent cmap1 colors (see *note Color Map1::) using RGBA
vector values.  This function also sets the number of cmap1 colors.
N.B.  Continuous cmap1 colors are indexed with a floating-point index in
the range from 0.0-1.0 which is linearly transformed (e.g., by ‘plcol1’
(*note plcol1; Set color; cmap1::)) to an integer index of these RGBA
vectors in the range from 0 to ‘ncol1-1’.  So in order for this
continuous color model to work properly, it is the responsibility of the
user of ‘plscmap1’ (*note plscmap1; Set opaque RGB cmap1 colors
values::) to insure that these RGBA vectors are continuous functions of
their integer indices.

‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of red in the color as a continuous
     function of the integer index of the vector.

‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of green in the color as a continuous
     function of the integer index of the vector.

‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input)
     A vector that represents (using unsigned 8-bit integers in the
     range from 0-255) the degree of blue in the color as a continuous
     function of the integer index of the vector.

‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector that represents (using PLFLT values in the range from
     0.0-1.0 where 0.0 corresponds to completely transparent and 1.0
     corresponds to completely opaque) the alpha transparency of the
     color as a continuous function of the integer index of the vector.

‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, ‘ ‘b’ ’, and ‘ ‘alpha’ ’
     vectors.

   Redacted form: ‘plscmap1a(r, g, b, alpha)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Next: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Prev: plscmap1a; Set semitransparent cmap1 RGBA colors_,  Up: The Common API for PLplot

17.109 plscmap1l: Set cmap1 colors using a piece-wise linear relationship
=========================================================================

     plscmap1l ( itype , npts , intensity , coord1 , coord2 , coord3 ,
     alt_hue_path );

   Set cmap1 colors using a piece-wise linear relationship between the
cmap1 intensity index (0.0-1.0) and position in HLS or RGB color space
(see *note Color Map1::).  May be called at any time.

   The idea here is to specify a number of control points that define
the mapping between input cmap1 intensity indices and HLS or RGB.
Between these points, linear interpolation is used which gives a smooth
variation of color with intensity index.  Any number of control points
may be specified, located at arbitrary positions, although typically 2 -
4 are enough.  Another way of stating this is that we are traversing a
given number of lines through HLS or RGB space as we move through cmap1
intensity indices.  The control points at the minimum and maximum
position (0 and 1) must always be specified.  By adding more control
points you can get more variation.  One good technique for plotting
functions that vary about some expected average is to use an additional
2 control points in the center (position ~= 0.5) that are the same
lightness as the background (typically white for paper output, black for
crt), and same hue as the boundary control points.  This allows the
highs and lows to be very easily distinguished.

   Each control point must specify the cmap1 intensity index and the
associated three coordinates in HLS or RGB space.  The first point
_must_ correspond to position = 0, and the last to position = 1.

   If RGB colors are provided then the interpolation takes place in RGB
space and is trivial.  However if HLS colors are provided then, because
of the circular nature of the color wheel for the hue coordinate, the
interpolation could be performed in either direction around the color
wheel.  The default behaviour is for the hue to be linearly interpolated
ignoring this circular property of hue.  So for example, the hues 0
(red) and 240 (blue) will get interpolated via yellow, green and cyan.
If instead you wish to interpolate the other way around the color wheel
you have two options.  You may provide hues outside the range [0, 360),
so by using a hue of -120 for blue or 360 for red the interpolation will
proceed via magenta.  Alternatively you can utilise the alt_hue_path
variable to reverse the direction of interpolation if you need to
provide hues within the [0-360) range.

   * Examples of interpolation *

Hue                      alt_hue_path             color scheme
[120 240]                false                    green-cyan-blue
[240 120]                false                    blue-cyan-green
[120 -120]               false                    green-yellow-red-magenta-blue
[240 480]                false                    blue-magenta-red-yellow-green
[120 240]                true                     green-yellow-red-magenta-blue
[240 120]                true                     blue-magenta-red-yellow-green

   * Bounds on coordinates*

RGB                R                  [0, 1]             magnitude
RGB                G                  [0, 1]             magnitude
RGB                B                  [0, 1]             magnitude
HLS                hue                [0, 360]           degrees
HLS                lightness          [0, 1]             magnitude
HLS                saturation         [0, 1]             magnitude

‘itype’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     true: RGB, false: HLS.

‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     number of control points

‘intensity’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the cmap1 intensity index (0.0-1.0) in
     ascending order for each control point.

‘coord1’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the first coordinate (H or R) for each control
     point.

‘coord2’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the second coordinate (L or G) for each control
     point.

‘coord3’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the third coordinate (S or B) for each control
     point.

‘alt_hue_path’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input)
     A vector (with ‘npts - 1’ elements), each containing either true to
     use the reversed HLS interpolation or false to use the regular HLS
     interpolation.  (‘alt_hue_path[i]’ refers to the interpolation
     interval between the ‘i’ and ‘i + 1’ control points).  This
     parameter is not used for RGB colors (‘itype = true’).

   Redacted form: ‘plscmap1l(itype, intensity, coord1, coord2, coord3,
alt_hue_path)’

   This function is used in examples 8, 11, 12, 15, 20, and 21.


File: plplotdoc.info,  Node: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Next: plscmap1n; Set number of colors in cmap1,  Prev: plscmap1l; Set cmap1 colors using a piece-wise linear relationship,  Up: The Common API for PLplot

17.110 plscmap1la: Set cmap1 colors and alpha transparency using a piece-wise linear relationship
=================================================================================================

     plscmap1la ( itype , npts , intensity , coord1 , coord2 , coord3 ,
     alpha , alt_hue_path );

   This is a variant of ‘plscmap1l’ (*note plscmap1l; Set cmap1 colors
using a piece-wise linear relationship::) that supports alpha channel
transparency.  It sets cmap1 colors using a piece-wise linear
relationship between cmap1 intensity index (0.0-1.0) and position in HLS
or RGB color space (see *note Color Map1::) with ‘‘alpha’’ transparency
value (0.0-1.0).  It may be called at any time.

‘itype’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input)
     true: RGB, false: HLS.

‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     number of control points.

‘intensity’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the cmap1 intensity index (0.0-1.0) in
     ascending order for each control point.

‘coord1’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the first coordinate (H or R) for each control
     point.

‘coord2’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the second coordinate (L or G) for each control
     point.

‘coord3’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the third coordinate (S or B) for each control
     point.

‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input)
     A vector containing the alpha transparency value (0.0-1.0) for each
     control point.

‘alt_hue_path’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input)
     A vector (with ‘npts - 1’ elements) containing the alternative
     interpolation method Boolean value for each control point interval.
     (‘alt_hue_path[i]’ refers to the interpolation interval between the
     ‘i’ and ‘i + 1’ control points).

   Redacted form: ‘ plscmap1la(itype, intensity, coord1, coord2, coord3,
alpha, alt_hue_path) ’

   This function is used in example 30.


File: plplotdoc.info,  Node: plscmap1n; Set number of colors in cmap1,  Next: plscol0; Set 8-bit RGB values for given cmap0 color index,  Prev: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship,  Up: The Common API for PLplot

17.111 plscmap1n: Set number of colors in cmap1
===============================================

     plscmap1n ( ncol1 );

   Set number of colors in cmap1, (re-)allocate cmap1, and set default
values if this is the first allocation (see *note Color Map1::).

‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Number of colors that will be allocated in the cmap1 palette.  If
     this number is zero or less, then the value from the previous call
     to ‘plscmap1n’ (*note plscmap1n; Set number of colors in cmap1::)
     is used and if there is no previous call, then a default value is
     used.

   Redacted form: ‘plscmap1n(ncol1)’

   This function is used in examples 8, 11, 20, and 21.


File: plplotdoc.info,  Node: plscol0; Set 8-bit RGB values for given cmap0 color index,  Next: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index,  Prev: plscmap1n; Set number of colors in cmap1,  Up: The Common API for PLplot

17.112 plscol0: Set 8-bit RGB values for given cmap0 color index
================================================================

     plscol0 ( icol0 , r , g , b );

   Set 8-bit RGB values for given cmap0 (see *note Color Map0::) index.
Overwrites the previous color value for the given index and, thus, does
not result in any additional allocation of space for colors.

‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Color index.  Must be less than the maximum number of colors (which
     is set by default, by ‘plscmap0n’ (*note plscmap0n; Set number of
     colors in cmap0::), or even by ‘plscmap0’ (*note plscmap0; Set
     cmap0 colors by 8-bit RGB values::)).

‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

   Redacted form: ‘plscol0(icol0, r, g, b)’

   This function is used in any example 31.


File: plplotdoc.info,  Node: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index,  Next: plscolbg; Set the background color by 8-bit RGB value,  Prev: plscol0; Set 8-bit RGB values for given cmap0 color index,  Up: The Common API for PLplot

17.113 plscol0a: Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index
====================================================================================================

     plscol0a ( icol0 , r , g , b , alpha );

   Set 8-bit RGB value and PLFLT alpha transparency value for given
cmap0 (see *note Color Map0::) index.  Overwrites the previous color
value for the given index and, thus, does not result in any additional
allocation of space for colors.

‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Color index.  Must be less than the maximum number of colors (which
     is set by default, by ‘plscmap0n’ (*note plscmap0n; Set number of
     colors in cmap0::), or even by ‘plscmap0’ (*note plscmap0; Set
     cmap0 colors by 8-bit RGB values::)).

‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

‘alpha’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of the alpha transparency in the range (0.0-1.0).

   This function is used in example 30.


File: plplotdoc.info,  Node: plscolbg; Set the background color by 8-bit RGB value,  Next: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_,  Prev: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index,  Up: The Common API for PLplot

17.114 plscolbg: Set the background color by 8-bit RGB value
============================================================

     plscolbg ( r , g , b );

   Set the background color (color 0 in cmap0) by 8-bit RGB value (see
*note Color Map0::).

‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

   Redacted form: ‘plscolbg(r, g, b)’

   This function is used in examples 15 and 31.


File: plplotdoc.info,  Node: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_,  Next: plscolor; Used to globally turn color output on/off,  Prev: plscolbg; Set the background color by 8-bit RGB value,  Up: The Common API for PLplot

17.115 plscolbga: Set the background color by 8-bit RGB value and PLFLT alpha transparency value.
=================================================================================================

     plscolbga ( r , g , b , alpha );

   Set the background color (color 0 in cmap0) by 8-bit RGB value and
PLFLT alpha transparency value (see *note Color Map0::).

‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of red in
     the color.

‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of green in
     the color.

‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Unsigned 8-bit integer (0-255) representing the degree of blue in
     the color.

‘alpha’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Value of the alpha transparency in the range (0.0-1.0).

   This function is used in example 31.


File: plplotdoc.info,  Node: plscolor; Used to globally turn color output on/off,  Next: plscompression; Set device-compression level,  Prev: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_,  Up: The Common API for PLplot

17.116 plscolor: Used to globally turn color output on/off
==========================================================

     plscolor ( color );

   Used to globally turn color output on/off for those drivers/devices
that support it.

‘color’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     Color flag (Boolean).  If zero, color is turned off.  If non-zero,
     color is turned on.

   Redacted form: ‘plscolor(color)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plscompression; Set device-compression level,  Next: plsdev; Set the device [keyword] name,  Prev: plscolor; Used to globally turn color output on/off,  Up: The Common API for PLplot

17.117 plscompression: Set device-compression level
===================================================

     plscompression ( compression );

   Set device-compression level.  Only used for drivers that provide
compression.  This function, if used, should be invoked before a call to
‘plinit’ (*note plinit; Initialize PLplot::).

‘compression’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     The desired compression level.  This is a device-dependent value.
     Currently only the jpeg and png devices use these values.  For jpeg
     value is the jpeg quality which should normally be in the range
     0-95.  Higher values denote higher quality and hence larger image
     sizes.  For png values are in the range -1 to 99.  Values of 0-9
     are taken as the compression level for zlib.  A value of -1 denotes
     the default zlib compression level.  Values in the range 10-99 are
     divided by 10 and then used as the zlib compression level.  Higher
     compression levels correspond to greater compression and small file
     sizes at the expense of more computation.

   Redacted form: ‘plscompression(compression)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdev; Set the device [keyword] name,  Next: plsdidev; Set parameters that define current device-space window,  Prev: plscompression; Set device-compression level,  Up: The Common API for PLplot

17.118 plsdev: Set the device (keyword) name
============================================

     plsdev ( devname );

   Set the device (keyword) name.

‘devname’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input)
     An ascii character string containing the device name keyword of the
     required output device.  If ‘devname’ is NULL or if the first
     character of the string is a "?", the normal (prompted) start up is
     used.

   Redacted form: ‘plsdev(devname)’

   This function is used in examples 1, 14, and 20.


File: plplotdoc.info,  Node: plsdidev; Set parameters that define current device-space window,  Next: plsdimap; Set up transformation from metafile coordinates,  Prev: plsdev; Set the device [keyword] name,  Up: The Common API for PLplot

17.119 plsdidev: Set parameters that define current device-space window
=======================================================================

     plsdidev ( mar , aspect , jx , jy );

   Set relative margin width, aspect ratio, and relative justification
that define current device-space window.  If you want to just use the
previous value for any of these, just pass in the magic value PL_NOTSET.
It is unlikely that one should ever need to change the aspect ratio but
it's in there for completeness.  If ‘plsdidev’ (*note plsdidev; Set
parameters that define current device-space window::) is not called the
default values of ‘ ‘mar’ ’, ‘ ‘jx’ ’, and ‘ ‘jy’ ’ are all 0.  ‘
‘aspect’ ’ is set to a device-specific value.

‘mar’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Relative margin width.

‘aspect’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Aspect ratio.

‘jx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Relative justification in x.  Value must lie in the range -0.5 to
     0.5.

‘jy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Relative justification in y.  Value must lie in the range -0.5 to
     0.5.

   Redacted form: ‘plsdidev(mar, aspect, jx, jy)’

   This function is used in example 31.


File: plplotdoc.info,  Node: plsdimap; Set up transformation from metafile coordinates,  Next: plsdiori; Set plot orientation,  Prev: plsdidev; Set parameters that define current device-space window,  Up: The Common API for PLplot

17.120 plsdimap: Set up transformation from metafile coordinates
================================================================

     plsdimap ( dimxmin , dimxmax , dimymin , dimymax , dimxpmm ,
     dimypmm );

   Set up transformation from metafile coordinates.  The size of the
plot is scaled so as to preserve aspect ratio.  This isn't intended to
be a general-purpose facility just yet (not sure why the user would need
it, for one).

‘dimxmin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     NEEDS DOCUMENTATION

‘dimxmax’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     NEEDS DOCUMENTATION

‘dimymin’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     NEEDS DOCUMENTATION

‘dimymax’ (‘‘PLINT’ (*note PLINT-type::)’, input)
     NEEDS DOCUMENTATION

‘dimxpmm’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     NEEDS DOCUMENTATION

‘dimypmm’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     NEEDS DOCUMENTATION

   Redacted form: ‘plsdimap(dimxmin, dimxmax, dimymin, dimymax, dimxpmm,
dimypmm)’

   This function is not used in any examples.


File: plplotdoc.info,  Node: plsdiori; Set plot orientation,  Next: plsdiplt; Set parameters that define current plot-space window,  Prev: plsdimap; Set up transformation from metafile coordinates,  Up: The Common API for PLplot

17.121 plsdiori: Set plot orientation
=====================================

     plsdiori ( rot );

   Set plot orientation parameter which is multiplied by 90 degrees to
obtain the angle of rotation.  Note, arbitrary rotation parameters such
as 0.2 (corresponding to 18 degrees) are possible, but the usual values
for the rotation parameter are 0., 1., 2., and 3.  corresponding to 0
degrees (landscape mode), 90 degrees (portrait mode), 180 degrees
(seascape mode), and 270 degrees (upside-down mode).  If ‘plsdiori’
(*note plsdiori; Set plot orientation::) is not called the default value
of ‘ ‘rot’ ’ is 0.

   N.B. aspect ratio is unaffected by calls to ‘plsdiori’ (*note
plsdiori; Set plot orientation::).  So you will probably want to change
the aspect ratio to a value suitable for the plot orientation using a
call to ‘plsdidev’ (*note plsdidev; Set parameters that define current
device-space window::) or the command-line options ‘ ‘-a’ ’ or ‘
‘-freeaspect’ ’.  For more documentation of those options see *note
Command Line Arguments::.  Such command-line options can be set
internally using ‘plsetopt’ (*note plsetopt; Set any command-line
option::) or set directly using the command line and parsed using a call
to ‘plparseopts’ (*note plparseopts; Parse command-line arguments::).

‘rot’ (‘‘PLFLT’ (*note PLFLT-type::)’, input)
     Plot orientation parameter.

   Redacted form: ‘plsdiori(rot)’

   This function is not used in any examples.

