Argument Mapping - Simple Numbers And Arrays

This is more or less as you might expect - use Perl scalars and Perl arrays in place of FORTRAN/C variables and arrays.

Any FORTRAN REAL/INTEGER/CHARACTER* scalar variable maps to a Perl scalar (Perl doesn't care about the differences between strings and numbers and ints and floats).

Thus you can say:

To draw a line to point (42,$x):

 pgdraw(42,$x);

To plot 10 points with data in Perl arrays @x and @y with plot symbol no. 17. Note the Perl arrays are passed by reference:

 pgpoint(10, \@x, \@y, 17);

You can also use the old Perl4 style:

 pgpoint(10, *x, *y, 17);

but this is deprecated in Perl5.

Label the axes:

 pglabel("X axis", "Data units", $label);

Draw ONE point, see how when "N=1" pgpoint() can take a scalar as well as a array argument:

  pgpoint(1, $x, $y, 17);

Argument Mapping - Images And 2d Arrays

Many of the PGPLOT commands (e.g. "pggray") take 2D arrays as arguments. Several schemes are provided to allow efficient use from Perl:

1.

Simply pass a reference to a 2D array, e.g:

  # Create 2D array
  $x=[];
  for($i=0; $i<128; $i++) {
     for($j=0; $j<128; $j++) {
       $$x[$i][$j] = sqrt($i*$j);
     }
  }
  pggray( $x, 128, 128, ...);
    

2.

Pass a reference to a 1D array:

  @x=();
  for($i=0; $i<128; $i++) {
     for($j=0; $j<128; $j++) {
       $x[$i][$j] = sqrt($i*$j);
     }
  }
  pggray( \@x, 128, 128, ...);
    

Here @x is a 1D array of 1D arrays. (Confused? - see perldata(1)). Alternatively @x could be a flat 1D array with 128x128 elements, 2D routines such as pggray() etc. are programmed to do the right thing as long as the number of elements match.

3.

If your image data is packed in raw binary form into a character string you can simply pass the raw string. e.g.:

   read(IMG, $img, 32768);
   pggray($img, $xsize, $ysize, ...);
    

Here the read() function reads the binary data from a file and the pggray() function displays it as a grey-scale image.

This saves unpacking the image data in to a potentially very large 2D perl array. However the types must match. The string must be packed as a "f*" for example to use "pggray". This is intended as a short-cut for sophisticated users. Even more sophisticated users will want to download the "PDL" module which provides a wealth of functions for manipulating binary data.

Please Note: As PGPLOT is a Fortran library it expects its images to be be stored in row order. Thus a 1D list is interpreted as a sequence of rows end to end. Perl is similar to C in that 2D arrays are arrays of pointers thus images end up stored in column order.

Thus using perl multidimensional arrays the coordinate ($i,$j) should be stored in $img[$j][$i] for things to work as expected, e.g:

   $img = [];
   for $j (0..$nx-1) for $i (0..$ny-1) {
      $$img[$j][$i] = whatever();
   }}
   pggray($$img, $nx, $ny, ...);
    

Also PGPLOT displays coordinate (0,0) at the bottom left (this is natural as the subroutine library was written by an astronomer!).

Argument Mapping - Function Names

Some PGPLOT functions (e.g. "pgfunx") take functions as callback arguments. In Perl simply pass a subroutine reference or a name, e.g.:

 # Anonymous code reference:
 pgfunx(sub{ sqrt($_[0]) },  500, 0, 10, 0);
 # Pass by ref:
 sub foo {
   my $x=shift;
   return sin(4*$x);
 }
 pgfuny(\&foo, 360, 0, 2*$pi, 0);
 # Pass by name:
 pgfuny("foo", 360, 0, 2*$pi, 0);

Argument Mapping - General Handling Of Binary Data

In addition to the implicit rules mentioned above PGPLOT now provides a scheme for explicitly handling binary data in all routines.

If your scalar variable (e.g. $x) holds binary data (i.e. 'packed') then simply pass PGPLOT a reference to it (e.g. "\$x"). Thus one can say:

   read(MYDATA, $wavelens, $n*4);
   read(MYDATA, $spectrum, $n*4);
   pgline($n, \$wavelens, \$spectrum);

This is very efficient as we can be sure the data never gets copied and will always be interpreted as binary.

Again see the PDL module for sophisticated manipulation of binary data, since it takes great advantage of these facilities. See in particular PDL::Graphics::PGPLOT.

Be VERY careful binary data is of the right size or your segments might get violated.

Cygwin

Build the pgplot library and install as above, but with these notes in mind.

Edit drivers.list to enable the drivers you wish but uncommenting desired drivers by removing the leading ! on the line. Here are the ones used by a previous PDL maintainer:

  $ grep -v '^!' drivers.list
    LXDRIV 0 /LATEX     LaTeX picture environment
    NUDRIV 0 /NULL      Null device (no output)                           Std F77
    PPDRIV 1 /PPM       Portable Pixel Map file, landscape
    PPDRIV 2 /VPPM      Portable PIxel Map file, portrait
    PSDRIV 1 /PS        PostScript printers, monochrome, landscape        Std F77
    PSDRIV 2 /VPS       Postscript printers, monochrome, portrait         Std F77
    PSDRIV 3 /CPS       PostScript printers, color, landscape             Std F77
    PSDRIV 4 /VCPS      PostScript printers, color, portrait              Std F77
    TTDRIV 5 /XTERM     XTERM Tektronix terminal emulator                 Std F77
    WDDRIV 1 /WD        X Window dump file, landscape
    WDDRIV 2 /VWD       X Window dump file, portrait
    XWDRIV 1 /XWINDOW   Workstations running X Window System              C
    XWDRIV 2 /XSERVE    Persistent window on X Window System              C
  $ vi sys_cygwin/g77_gcc.conf
  # This diff command shows the lines that need changing
  $ diff g77_gcc.conf*
  12c12
  <    XINCL="-I/usr/X11R6/include"
  ---
  >    XINCL="-I/usr/X11R6.4/include"
  48c48
  <    FFLAGD="-fno-backslash -I/usr/include"
  ---
  >    FFLAGD="-fno-backslash"
  58c58
  <    CFLAGC="-DPG_PPU -O2 -DNOMALLOCH -I. -I/usr/include"
  ---
  >    CFLAGC="-DPG_PPU -O2 -DNOMALLOCH -I."
  75c75
  <    LIBS="-L/usr/X11R6/lib -lX11 -lpng -lz"
  ---
  >    LIBS="-L/usr/X11R6.4/lib -lX11"
  $ ~/pgplot/makemake ~/pgplot cygwin
  $ make
  $ make clean
  $ make cpg
  $ PGPLOT_DIR="/usr/local/pgplot/"; export PGPLOT_DIR

Be sure to add "PGPLOT_DIR" to your environment and add it to your PATH as well.

NOTE: if problems occur, you may need to "rebaseall" your libraries.