
P-PGPLOT FUNCTION REFERENCE:

Nick Patavalis
Athens, 8 Feb 1997

Here is a list of the Python functions provided by ppgplot, along with
their prototypes (calling conventions) and a very short (single-line)
description of their operation. The order is alphabetical. Look after
the end of the function-list for some comments on the notation, and
other random notes. For more information on the functions's operation
refer to the original PGPLOT documentation.

EDIT BY M.A. Breddels(maartenbred at hotmail d0t com):
	
  I've added these function, documentation in the same style as the
  original author

	FUNCTION: pgqinf
	PROTOTYPE: pgqinf(string: item)
	DESCRIPTION: inquire PGPLOT general information
	RETURN: string: value

	FUNCTION: pgpoly
	PROTOTYPE: pgpoly(vector: x, y)
	DESCRIPTION: draw a polygon, using fill-area attributes
	RETURN:

	-----

	FUNCTION: pgqvp
	PROTOTYPE: pgqvp(int: units)
	DESCRIPTION: inquire viewport size and position
	RETURN: flota: x1, x2, y1, y2

	-----

	FUNCTION: pgqvsz
	PROTOTYPE: pgqvsz(int: units)
	DESCRIPTION: inquire size of view surface
	RETURN: x1, x2, y1, y2

	-----

	FUNCTION: pgsclp
	PROTOTYPE: pgsclp(int state)
	DESCRIPTION: enable or disable clipping at edge of viewport
	RETURN:

	-----

	FUNCTION: pgqclp
	PROTOTYPE: pgqclp()
	DESCRIPTION: inquire clipping status
	RETURN: int: state

	-----

	FUNCTION: pgqtxt
	PROTOTYPE: pgqtxt(real: x, y, angle, just, string: text)
	DESCRIPTION: find bounding box of text string
	RETURN: 4 (real: x,y) tuple, bottomleft, topleft, topright, bottomright

	-----

	FUNCTION: pgconf
	PROTOTYPE: pgconf(matrix: a, int: idim, jdim, i1, i2, j1, j2,
		           real: c1, c2, matrix: tr)
	DESCRIPTION: fill between two contours
	RETURN:

FUNCTION: pgarro
PROTOTYPE: pgarro (real: x1, y1, x2, y2)
DESCRIPTION: draw an arrow

-----

FUNCTION: pgask
PROTOTYPE: pgask (bool: t)
DESCRIPTION: control new page prompting

-----

FUNCTION: pgband
PROTOTYPE: pgband (int: mode, [posn, real: xref, yref]) 
DESCRIPTION: read cursor position, with anchor

-----

FUNCTION: pgbbuf
PROTOTYPE: pgbbuf ()
DESCRIPTION: begin batch of output (buffer)

-----

FUNCTION: pgbeg
PROTOTYPE: pgbeg ([string: device, int: xnsub, ynsub])
DESCRIPTION: begin PGPLOT, open output device

-----

FUNCTION: pgbin
PROTOTYPE: pgbin (int: nbin, vector: x, data, [bool: center])
DESCRIPTION: histogram of binned data

-----

FUNCTION: pgbin_s
PROTOTYPE: pgbin_s (vector: data, [real: x1, x2, bool: center])
DESCRIPTION: histogram of binned data. Simplified interface

-----

FUNCTION: pgbox
PROTOTYPE: pgbox ([string: xopt, real: xtick, int: nxsub, 
		          string: yopt, real: ytick, int: nysub])
DESCRIPTION: draw labeled frame around viewport

-----

FUNCTION: pgcirc
PROTOTYPE: pgcirc (real: x, y, radius)
DESCRIPTION: draw a filled or outline circle

-----

FUNCTION: pgclos
PROTOTYPE: pgclos ()
DESCRIPTION: close the selected graphics device

-----

FUNCTION: pgconb
PROTOTYPE: pgconb (matrix: a, int: cd, rd, c1, c2, r1, r2,
		           vector: c, int: nc,
		           vector: tr, [real: blank])
DESCRIPTION: contour map of a 2D data array, with blanking

-----

FUNCTION: pgconb_s
PROTOTYPE: pgconb_s (matrix: a, int: nc, 
                     [vector: c, real: x1, y1, x2, y2, real: blank])
DESCRIPTION: contour map of a 2D data array, with blanking. 
    Simplified interface

-----

FUNCTION: pgconl
PROTOTYPE: pgconl (matrix: a, int: cd, rd, c1, c2, r1, r2, real: c, 
		           vector: tr, string: label, int: intval, minint)
DESCRIPTION: label contour map of a 2D data array

-----

FUNCTION: pgconl_s
PROTOTYPE: pgconl_s (matrix: a, real: c, string: label,
				     int: intval, minint, real: x1, x2, y1, y2)
DESCRIPTION: label contour map of a 2D data array. Simplified interface

-----

FUNCTION: pgcons
PROTOTYPE: pgcons (matrix: a, int: cd, rd, c1, c2, r1, r2, 
		           vector: c, int: nc, 
		           vector: tr)
DESCRIPTION: contour map of a 2D data array (fast algorithm)

-----

FUNCTION: pgcons_s
PROTOTYPE: pgcons_s (matrix: a, int: nc, 
                     [vector: c, real: x1, y1, x2, y2])
DESCRIPTION: contour map of a 2D data array (fast algorithm). 
    Simplified interface

-----

FUNCTION: pgcont
PROTOTYPE: pgcont (matrix: a, int: cd, rd, c1, c2, r1, r2, 
		           vector: c, int: nc,
		           vector: tr)
DESCRIPTION: contour map of a 2D data array (contour-following)

-----

FUNCTION: pgcont_s
PROTOTYPE: pgcont_s (matrix: a, int: nc, 
                     [vector: c, real: x1, y1, x2, y2])
DESCRIPTION: contour map of a 2D data array (contour-following). 
    Simplified interface

-----

FUNCTION: pgctab
PROTOTYPE: pgctab (vector: l, r, g, b, [int: nc, real: contra, bright])
DESCRIPTION: install the color table to be used by pgimag

-----

FUNCTION: pgdraw
PROTOTYPE: pgdraw (real: x, y)
DESCRIPTION: draw a line from the current pen position to a point

-----

FUNCTION: pgebuf
PROTOTYPE: pgebuf ()
DESCRIPTION: end batch of output (buffer)

-----

FUNCTION: pgend
PROTOTYPE: pgend ()
DESCRIPTION: terminate PGPLOT

-----

FUNCTION: pgenv 
PROTOTYPE: pgenv (real: xmin, xmax, ymin, ymax, [int: just, int: axis])
DESCRIPTION: set window and viewport and draw labeled frame

-----

FUNCTION: pgeras
PROTOTYPE: pgeras ()
DESCRIPTION: erase all graphics from current page

-----

FUNCTION: pgetxt
PROTOTYPE: pgetxt ()
DESCRIPTION: erase text from graphics display

-----

FUNCTION: pggray
PROTOTYPE: pggray (matrix: a, int: cd, rd, c1, c2, r1, r2, 
		           real: fg, bg, vector: tr) 
DESCRIPTION: gray-scale map of a 2D data array

-----

FUNCTION: pggray_s
PROTOTYPE: pggray_s (matrix: a, [real: fg, bg, x1, y1, x2, y2])
DESCRIPTION: gray-scale map of a 2D data array. Simplified interface

-----

FUNCTION: pghi2d 
PROTOTYPE: pghi2d (matrix: data, int: cd, rd, c1, c2, r1, r2, vector: x,
		           int: ioff, real: bias, bool: center, vector: ylims)
DESCRIPTION: cross-sections through a 2D data array

-----

FUNCTION: pghi2d_s
PROTOTYPE: pghi2d_s (matrix: data, real: x1, x2, 
                     [int: ioff, real: bias, bool: center])
DESCRIPTION: cross-sections through a 2D data array. Simplified interface

-----

FUNCTION: pghist
PROTOTYPE: pghist (int: n, vector: data, real: datamin, datamax, 
                   int: nbin, [pgflag])
DESCRIPTION: histogram of unbinned data

-----

FUNCTION: pghist_s
PROTOTYPE: pghist_s (vector: data, int: nbin, 
                     [int: pgflag, real: datamin, datamax])
DESCRIPTION: histogram of unbinned data. Simplified interface

-----

FUNCTION: pgiden
PROTOTYPE: pgiden ()
DESCRIPTION: write username, date, and time at bottom of plot

-----

FUNCTION: pgimag
PROTOTYPE: pgimag (matrix: a, int: cd, rd, c1, c2, r1, r2, 
		           real: fg, bg, vector: tr)
DESCRIPTION: color image from a 2D data array

-----

FUNCTION: pgimag_s
PROTOTYPE: pgimag_s (matrix: a, [real: fg, bg, x1, y1, x2, y2])
DESCRIPTION: color image from a 2D data array. Simplified interface

-----

FUNCTION: pglab 
PROTOTYPE: pglab ([string: xlabel, ylabel, toplabel])
DESCRIPTION: write labels for x-axis, y-axis, and top of plot

-----

FUNCTION: pgldev
PROTOTYPE: pgldev ()
DESCRIPTION: list available device types

-----

FUNCTION: pglen
PROTOTYPE: pglen (string: text, [int: units])
DESCRIPTION: find length of a string in a variety of units

-----

FUNCTION: pgline
PROTOTYPE: pgline (vector: xpts, ypts)
DESCRIPTION: draw a polyline (curve defined by line-segments)

-----

FUNCTION: pgmove
PROTOTYPE: pgmove (real: x, y)
DESCRIPTION: move pen (change current pen position)

-----

FUNCTION: pgmtxt
PROTOTYPE: pgmtxt (string: side, real: disp, coord, fjust, string: text)
DESCRIPTION: write text at position relative to viewport

-----

FUNCTION: pgopen
PROTOTYPE: pgopen ([string: device])
DESCRIPTION: open a graphics device

-----

FUNCTION: pgpage
PROTOTYPE: pgpage ()
DESCRIPTION: advance to new page

-----

FUNCTION: pgpanl
PROTOTYPE: pgpanl ([int: x, y])
DESCRIPTION: switch to a different panel on the view surface

-----

FUNCTION: pgpap
PROTOTYPE: pgpap (real: width, [aspect])
DESCRIPTION: change the size of the view surface 

-----

FUNCTION: pgpt
PROTOTYPE: pgpt (vector: xpts, ypts, [int: symbol])
DESCRIPTION: draw one or more graph markers

-----

FUNCTION: pgptxt
PROTOTYPE: pgptxt (real: x, y, angle, fjust, string: text)
DESCRIPTION: write text at arbitrary position and angle

-----

FUNCTION: pgqah
PROTOTYPE: pgqah ()
RETURNS: int: fs, real: angle, vent
DESCRIPTION: inquire arrow-head style

-----

FUNCTION: pgqcf
PROTOTYPE: pgqcf ()
RETURNS: int: cf
DESCRIPTION: inquire character font

-----

FUNCTION: pgqch
PROTOTYPE: pgqch ()
RETURNS: real: ch
DESCRIPTION: inquire character height

-----

FUNCTION: pgqci
PROTOTYPE: pgqci ()
RETURNS: int: ci
DESCRIPTION: inquire color index

-----

FUNCTION: pgqcir
PROTOTYPE: pgqcir ()
RETURNS: int: ci1, ci2
DESCRIPTION: inquire color index range

-----

FUNCTION: pgqcol
PROTOTYPE: pgqcol ()
RETURNS: int: ci1, ci2
DESCRIPTION: inquire color capability

-----

FUNCTION: pgqcr
PROTOTYPE: pgqcr ([int: ci])
RETURNS: real: r, g, b
DESCRIPTION: inquire color representation

-----

FUNCTION: pgqcs
PROTOTYPE: pgqcs ([int: units])
RETURNS: real: xch, ych
DESCRIPTION: inquire character height in a variety of units

-----

FUNCTION: pgqfs
PROTOTYPE: pgqfs ()
RETURNS: int: fs
DESCRIPTION: inquire fill-area style

-----

FUNCTION: pgqhs
PROTOTYPE: pgqhs ()
RETURNS: real: angle, sepn, phase
DESCRIPTION: inquire hatching style

-----

FUNCTION: pgqid
PROTOTYPE: pgqid ()
RETURNS: int: id
DESCRIPTION: inquire current device identifier

-----

FUNCTION: pgqitf
PROTOTYPE: pgqitf ()
RETURNS: int: itf
DESCRIPTION: inquire image transfer function

-----

FUNCTION: pgqls
PROTOTYPE: pgqls
RETURNS: int: ls
DESCRIPTION: inquire line style

-----

FUNCTION: pgqlw
PROTOTYPE: pgqlw
RETURNS: int: lw
DESCRIPTION:inquire line width

-----

FUNCTION: pgqpos
PROTOTYPE: pgqpos
RETURNS: real: x, y
DESCRIPTION: inquire current pen position

-----

FUNCTION: pgrect
PROTOTYPE: pgrect (real: x1, x2, y1, y2)
DESCRIPTION: draw a rectangle, using fill-area attributes

-----

FUNCTION: pgsah
PROTOTYPE: pgsah ([int: fs, real: angle, vent])
DESCRIPTION: set arrow-head style

-----

FUNCTION: pgsave
PROTOTYPE: pgsave ()
DESCRIPTION: save PGPLOT attributes

-----

FUNCTION: pgunsa
PROTOTYPE: pgunsa ()
DESCRIPTION: restore PGPLOT attributes

-----

FUNCTION: pgscf
PROTOTYPE: pgscf ([int: cf])
DESCRIPTION: set character font

-----

FUNCTION: pgsch
PROTOTYPE: pgsch ([int: ch])
DESCRIPTION: set character height

-----

FUNCTION: pgsci
PROTOTYPE: pgsci ([int: ci])
DESCRIPTION: set color index

-----

FUNCTION: pgscir
PROTOTYPE: pgscir ([int: ci1, ci2])
DESCRIPTION: set color index range

-----

FUNCTION: pgscr
PROTOTYPE: pgscr (int: ci, real: r, g, b)
DESCRIPTION: set color representation

-----

FUNCTION: pgsfs
PROTOTYPE: pgsfs ([int: fs])
DESCRIPTION: set fill-area style

-----

FUNCTION: pgshls
PROTOTYPE: pgshls (int: ci, real: hue, level, saturation)
DESCRIPTION: set color representation using HLS system

-----

FUNCTION: pgshs
PROTOTYPE: pgshs (real: angle, sepn, phase)
DESCRIPTION: set hatching style

-----

FUNCTION: pgsitf
PROTOTYPE: pgsitf ([int: itf])
DESCRIPTION: set image transfer function

-----

FUNCTION: pgslct
PROTOTYPE: pgslct ([int: devid])
DESCRIPTION: select an open graphics device

-----

FUNCTION: pgsls
PROTOTYPE: pgsls ([int: ls])
DESCRIPTION: set line style

-----

FUNCTION: pgslw
PROTOTYPE: pgslw ([int: lw])
DESCRIPTION: set line width

-----

FUNCTION: pgstbg
PROTOTYPE: pgstbg ([int: tbg])
DESCRIPTION: set text background color index

-----

FUNCTION: pgsubp
PROTOTYPE: pgsubp ([int: xnsub, ynsub])
DESCRIPTION: subdivide view surface into panels

-----

FUNCTION: pgsvp
PROTOTYPE: pgsvp ([real: xleft, xright, ybot, ytop])
DESCRIPTION: set viewport (normalized device coordinates)

-----

FUNCTION: pgswin
PROTOTYPE: pgswin ([real: x1, x2, y1, y2])
DESCRIPTION: set window

-----

FUNCTION: pgtext
PROTOTYPE: pgtext (real: x, y, string: text)
DESCRIPTION: write text (horizontal, left-justified)

-----

FUNCTION: pgunsa
PROTOTYPE: pgunsa ()
DESCRIPTION: restore PGPLOT attributes

-----

FUNCTION: pgupdt
PROTOTYPE: pgupdt ()
DESCRIPTION: update display

-----

FUNCTION: pgvsiz
PROTOTYPE: pgvsiz (real: xleft, xright, ybot, ytop)
DESCRIPTION: set viewport (inches)

-----

FUNCTION: pgvstd
PROTOTYPE: pgvstd ()
DESCRIPTION: set standard (default) viewport

-----

FUNCTION: pgwedg
PROTOTYPE: pgwedg (string: side, real: disp, width, fg, bg, string: label)
DESCRIPTION: annotate an image plot with a wedge

-----

FUNCTION: pgwedg_s
PROTOTYPE: pgwedg_s (real: fg, bg, 
                     [string: side, label, real: disp, width])
DESCRIPTION: annotate an image plot with a wedge. Simplified interface

-----

FUNCTION: pgwnad
PROTOTYPE: pgwnad (real: x1, x2, y1, y2)
DESCRIPTION: set window and adjust viewport to same aspect ratio

-----

---------------------------------------------------------------------------
NOTE: Prototypes Notation.
---------------------------------------------------------------------------

The prototypes are written like this:

PROTOTYPE: function (type: arg, arg, ..., [type: arg, arg ...])

Square brackets are used to indicate optional arguments.

Python is a self-typed language. This doesn't mean that any function
can operate sentiently on any data type. (Although it is semantically
correct to call it with any type of arguments). So ``type'' above,
simply indicates what kind of object is expected by the function. It
has the following meaning:

     real:   the function expects a real quantity (an int, 
             a floating point, etc)
	 int:    the function expects an integer quantity.
     bool:   the function expects a boolean value (something evaluated 
             as `true' or `false').
	 vector: the function expects an one-dimensional array of FLOATS.
     matrix: the function expects a two-dimensional array of FLOAT. 

For example ``PROTOTYPE: pgpap (real: width, [aspect])'' means that:
The ``pgpap'' function takes two arguments. The arguments are expected 
to be real numbers. The last argument is optional (can be omited from 
the call).

If the function returns a value (a.k.a something other that None),
the type of the return value is written like this:

RETURNS: type: val, val, ... type: val, val ...

For example ``RETURNS: real: angle, sepn, phase'' means that the
function in question return a tupple of 3 elements, all of them beign
real numbers.

---------------------------------------------------------------------------
NOTE: Array syntax and storage in python (C) and Fortran
---------------------------------------------------------------------------

Memory is visualized as a notebook, where you write left to right, and
when the line (row) ends, you go to the leftmost part of the next 
one and start again, and so on. This paradigm is used throughout
the comments in this file, and throughout all the associated 
documentation. If you like to visualize memory as writting top
to bottom, then just replace the word "column" with the word 
"row" (and vice-versa) everywhere.

in python (and C) a matrix looks like: a[i,j] i=rows j=cols. 
In mem it is: 

         a[1,0],    a[1,1],    a[1,2]   ....a[1,nc-1]
         c[2,0],    a[2,1],    a[2,2]   ....a[2,nc-1]
                   ..................
         a[nr-1,1], a[nr-1,1], a[nr-1,2]....a[nr-1,nc-1]

A.k.a the major (faster running) index is written (spelled) last.

The same matrix in fortran syntax looks like: a(i,j) i=cols 
j=rows. In mem it is:

         a(1,1),    a(2,1),    a(3,1),  ....a(nc,1)
         a(1,2),    a(2,2),    a(3,2),  ....a(nc,2)
                 ..................
         a(1,nr),   a(2,nr),   a(3,nr), ....a(nc,nr)

A.k.a the major (faster running) index is written (spelled) first.

In this file (and all associated documentation) whenever i'm using
the () as indexing operators, I'm talking fortran-lingo, and whenever 
I'm using the [] as an indexing operator, I'm talking C/Python-lingo.

In the pgplot documentation the FORTRAN notation is always used.
So translating the function prototypes found in the PGPLOT docs, 
to the variable naming sceme used in the ppgplot function, yields 
something like this:

idim ---> cd (columns dimension / # of columns)
jdim ---> rd (rows dimension / # of rows)
i1   ---> c1 (first column)
i2   ---> c2 (last column)
j1   ---> r1 (first row)
j2   ---> r2 (last row)

I repeat that columns run faster.
 
Also remember than when you use python (even if calling PGPLOT)
all indices start from 0, *not* 1.

--------------------------------------------------------------------------- 
NOTE: A word about transformations
---------------------------------------------------------------------------

In order to plot (map) a matrix 

        a[r1:r2,c1:c2] 

in a viewport scaled as:

        x-axis form x1 to x2
        y-axis from y1 to y2

having rows run on x and columns on run y, you have to use the 
following transformation matrix:

        tr = array([t0,t1,t2,t3,t4,t5])

where

        t0 = x1 - (t1 * c1) / 2
        t1 = (x2-x1) / (c2-c1)
        t2 = 0.0
        t3 = y1 - (t1 * r1) / 2
        t4 = (y2 - y1) / (c2 - c1)
        t5 = 0.0

The 2 denominator in t0 and t3 is justified by the fact that
cordinates pin-point the CENTER of the pixels, and not their
SW corner. t2 and t5 are used only if you want shearing or 
rotations.

If all these sound just too-much for you, you should 
consider using pggray_s which is a simplified allternative 
to pggray. Not the complete but enough of pgray's functionality
is wrapped around an easy-to-use interface. The basic limitation
of pggray_s is that it cannot do rotations and shearing
(it can do flips though!). The same is true for color 
image-maps (pgimag).





