From octave-sources-request at bevo dot che dot wisc dot edu  Wed Apr  1 19:58:12 1998
Subject: PLplot_octave: README
From: jcardoso at inescn dot pt
To: octave-sources at bevo dot che dot wisc dot edu
Date: Wed, 1 Apr 1998 23:53:32 +0100 (BST)




This package enables you to use PLplot from within Octave.

You have two advantages:

	1 - Use a superior plotting package, having access to dozens
		of plotting commands, enabling you to customize your plots
		at your will,

	2 - Still use the same plot commands that you are familiarized,
		if you really want to.

	3 - Have some new and long waited ploting command scripts.

PLplot also has its disadvantages:

	It is not beeing maintained anymore, and you must use the last
snapshot available before developpement ceased (plplot-961023 plus a
patch to this snapshot). This is a kind of walking in a sharp knife, but
in my experience I found it bug free.

	If you build the Tcl/Tk driver, optional, you have a menu driven
way to plot to a file, choose the output device, zoom, pan, change
colors, etc.

Besides having acess to all PLplot API commands, and all Octave usual
commands, some with some improvements, new commands are available. A
brief description of the new commands:

autostyle "on" | "off"

 increases line style after each plot.
 Usefull for B&W plots

[x, y, button] = ginput([n])

   gets n points (default 1e6) from the current axes and returns
       the x- and y-coordinates in length N vectors X and Y.  The cursor
       can be positioned using a mouse (or by using the Arrow Keys on some
       systems).  Data points are entered by pressing a mouse button
       or any key on the keyboard.  A carriage return terminates the
       input before N points are entered.

   	button contains a vector of integers specifying which mouse button was
       used (1,2,3 from left) or ASCII numbers if a key on the keyboard
       was used.

       A mouseclick or key press with the pointer positioned outside of
       the viewport is ignored.

		A bug makes the cross-hair remain in the plot after ginput terminates.
		To avoid, move the cross-hair outside the window, and press <RET>
		or issue plflush after calling ginput


grid ("on" | "off" | "minor")

 Turn grid lines at major ticks "on" or "off" for plotting.
 "minor" means to draw the grid at minor tiks.
 To setup the grid at your wish, use `x(y,z)ticks'

 If the argument is omitted, "on" is assumed.

gtext(string [,just [,orient]])

       Place text on a 2-D graph using a mouse.
       gtext('string') displays the graph window, puts up a
       cross-hair, and waits for a mouse button or keyboard key to be
       pressed.  The cross-hair can be positioned with the mouse (or
       with the arrow keys on some computers).  Pressing a mouse button
       or any key writes the text string onto the graph at the selected
       location.
       just controls justification of text;
       just=0, left justified; just=1, right justified. In between values
       justify acordingly. Default, center justified.
	   orient control orientation of text, measured in degrees. Default horizontal.

legend ([status [, xposition [, yposition]])

 turns the plot legend status = "off" || "on" == "transparent" || "opaque",
 left top corner legend at position (left)(botton) 0 <= position <= 1 (right)(top)


cmap = plcolormap([map])
 
 Set colormap1 to map; map is an n row by 3 columns matrix, representing
   red, green and blue components in the range [0..1]

 if map == 'default', returns and sets the default hsv colormap
 if map don't exist, return the current colormap


pldef

 set some options, as if they where in the command line, before plinit()


save_fig(device, file)

 save current plot figure in 'file' for 'device' type.

 *Usual* devices are:
	
	ps         PostScript File (monochrome)
	psc        PostScript File (color)
	plmeta     PLPLOT Native Meta-File (can be displayed with 'plrender')
	xfig       Xfig file
	pbm        PDB (PPM) Driver
	lj_hpgl    HP Laserjet III, HPGL emulation mode
	hp7470     HP 7470 Plotter File (HPGL Cartridge, Small Plotter)
	hp7580     HP 7580 Plotter File (Large Plotter)


set_view ([alt, az])

 Set up the altitude and azimute in degrees for posterior 3d plots.

 If called without arguments, rotates iteratively a cube.
 The keys `jklmi' control the rotation, in the usual star-like maker.
 The key `k' sets a default view. Finish with the enter key.
 Each key press steps the value by 10 degrees.
 If the Shift key is also pressed the step is by 1 degree value.

     i
   j k l
     m


shade(x, y, z [, levels [, contour] )
shade(z [, levels [, contour] )

 plot shade of matrix z versus vectors x,y.
 level can be a scalar speficying the number of shade levels,
 or a vector, specifying where the shade level must be
 if contour exists, each shade level will be contoured with 'countour' color

contour ([x, y,] z [, n])

  Draws a contour plot of matrix z versus vectors x and y.
  If n is a scalar, then n contour lines will be ploted
  If n is a vector, then length(n) contour lines will be plot at the
  value specified by n.


id = stripc (xmin, xmax, xjump, ymin, ymax,
	legend1, legend2, legend3, legend4,
	acc, autoy)

	creates a four pen stripchar. Points are added calling stripc_add().
	the scripchart *must* be deleted after use calling stripc_del()

	xmin, ymin, xmax and ymax are initial rasonable values for the chart
	xjump is the percentage of the window that skips when the plot lines
	arrive at the right.
	legend[i] is the legend of plot pen 'i'
	acc if '1' means to accumulate values instead of losting it, as a normal
	stripchart does (well, paper is always available)
	autoy if '1' means to autoscale the y axis *between* xjumps. After a
	xjump, the y scale is always rescaled.
	The current values of xlabel, ylabel, and legend position are used.

stripc_add(id, pen, x, y)

 add a point (x,y) to pen [0..3] of the stripchart 'id'


stripc_del(id)

 deletes the stripchart identified by id


tdeblank (s)

 Remove trailing amd leading blanks from the string s.


text(x,y,string);

   Place text on a 2-D graph at x y positions


xticks ([x_interval [, num_minor])

 set the xticks interval, and the number of minor ticks between major xticks.
 No arguments makes it automatic (default).


zoom

 No, it is just a frontend to set axis :(
 Select left botton and right top area for setting axis.
 Clicking with right mouse button or arg == "off" set axis "autoscale"
 Due to a bug in ginput, the cross-hair remains in the plot after zoom terminate
 Use the tk driver for zooming and panning.

	Read the INSTALL file to continue.

	

--
Joao Cardoso, INESC  |  e-mail:
R. Jose Falcao 110   |  tel:    + 351 2 2094345
4050 Porto, Portugal |  fax:    + 351 2 2008487