plplot 0.0.0

data/README

@@ -0,0 +1,115 @@
+--
+
+This file includes an RDoc hack so that links can be made to open up into a new
+frame rather then the current frame.
+
+The "trick" is to append ``"target="_top'' to the URL.
+
+++
+
+= Ruby/PLplot
+
+== Introduction
+
+This is the first public release of the Ruby bindings to
+PLplot[http://plplot.sourceforge.net/"target="_top], a cross-platform software
+package for creating scientific plots.
+
+This release should be considered a beta release because the {Ruby API to
+PLplot}[link:classes/PLplot.html] may change slightly based on user feedback.
+
+== Installation
+
+Ruby/PLplot can be installed via
+RubyGems[http://www.rubygems.org/"target=_top"]:
+
+  gem install plplot
+
+Ruby/PLplot should work with either Ruby 1.8 or 1.9.  It was developed mostly
+using Ruby 1.8.6 and somewhat tested against Ruby 1.9.1.
+
+Ruby/PLplot requires a very recent version of the \PLplot libraries.  Until a
+new version of \PLplot is released and package maintainers support it, you will
+likely have to build your own copy of the \PLplot libraries from source code
+checked out from the trunk of the \PLplot source code repository.  This must be
+done prior to installing Ruby/PLplot.  If you try to install Ruby/PLplot with
+an inappropriate version of \PLplot, you will get the error message "the
+\PLplot library lacks support for arbitrary storage of 2D data".
+
+== Documentation
+
+Documentation for the {Ruby aspects of the PLplot
+API}[link:classes/PLplot.html] are installed as part of the gem-based
+installation.  To view the documentation, run
+
+  gem server
+
+then point your browser to <tt>\http://localhost:8808/</tt> and navigate to
+(and follow) the plplot <b>[rdoc]</b> link.  You can get more information about
+RubyGem's documenation server by running:
+
+  gem help server
+
+The Ruby/PLplot API is mostly very similar to the \PLplot C API.  For details
+on \PLplot functionality, see the {PLplot
+documentation}[http://plplot.sourceforge.net/documentation.php"target="_top].
+
+== Examples
+
+Ruby/PLplot provides Ruby versions of the extensive suite of \PLplot's standard
+examples.  The only \PLplot examples not (yet) supported are those that depend
+on missing functionality (see below): x17 (stripchart), x19 (maps), and x29
+(time handling).
+
+The examples are installed automatically, but not as runnable programs.  They
+are "hidden" in the local gem repository.  At some point they will be made more
+visible, but until then you can find them in
+<tt>$GEMDIR/gems/plplot-X.Y.Z/examples</tt>.
+
+== Command line option parsing
+
+\PLplot has many different drivers and options that can be specified by the
+user.  \PLplot provides excellent command line parsing functionality via its
+<tt>plparseopts</tt> and related functions.  Ruby also provides excellent
+command line parsing via the OptionParser class.  In order to provide the best
+of both worlds, Ruby/PLplot provides the PLOptionParser class.  This class
+provides OptionParser functionality (it is a subclass of OptionParser) with
+built-in support for standard \PLplot options via a modified option syntax.
+
+Ruby/PLplot users are encouraged to use PLOptionParser for parsing command line
+arguments, but it is not required.  The Ruby <tt>plsetopt</tt> method is an
+enhanced version of \PLplot's <tt>plsetopt</tt> function.  In addition to the
+"standard" calling sequence
+
+  plsetopt(opt, optarg)
+  
+<tt>plsetopt</tt> can be called with an Array of Strings (such as
+<tt>ARGV</tt>) which provides functionality similar to <tt>plparseopts</tt>.
+This allows for a great deal of user control over how command line arguments
+are handled while still providing a simple way to leverage \PLplot's built-in
+command line parsing capabilties.
+
+== What's missing
+
+Most of the \PLplot API is supported, but there are a few \PLplot functions
+that have yet to be incorporated:
+
+* Stripchart functions
+  - <tt>plstripa</tt>
+  - <tt>plstripc</tt>
+  - <tt>plstripd</tt>
+
+* Time functions
+  - <tt>plbtime</tt>
+  - <tt>plconfigtime</tt>
+  - <tt>plctime</tt>
+
+* Map functions
+  - <tt>plmap</tt>
+  - <tt>plmeridians</tt>
+
+* Other functions
+  - <tt>plot3dcl</tt>
+  - <tt>plsmem</tt>
+  - <tt>plparseopts</tt> et al (but see above)
+  - <tt>plsurf3dl</tt>

data/examples/x01.rb

@@ -0,0 +1,284 @@
+#!/usr/bin/env ruby
+$-w = true if $0 == __FILE__
+
+require 'rubygems'
+require 'plplot'
+include PLplot
+include NMath
+
+# Simple line plot and multiple windows demo.
+#
+#   Copyright (C) 2004  Rafael Laboissiere
+#
+#  This file is part of PLplot.
+#
+#  PLplot is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Library Public License as published
+#  by the Free Software Foundation; either version 2 of the License, or
+#  (at your option) any later version.
+#
+#  PLplot is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Library General Public License for more details.
+#
+#  You should have received a copy of the GNU Library General Public License
+#  along with PLplot; if not, write to the Free Software
+#  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+
+# Defaults for user options.  Use global variables to track user options since
+# that matches the C example most closely.
+
+$locate_mode = false
+$test_xor = false
+$fontset = 1
+$f_name = nil
+
+# Create PLOptionParser for parsing options
+
+PLOP = PLOptionParser.new do |op|
+  op.separator('')
+  op.separator('x01 options:')
+  op.on('--locate', 'Turns on test of API locate function') do
+    $locate_mode = true
+  end
+  op.on('--xor', 'Turns on test of XOR') do
+    $test_xor = true
+  end
+  op.on('--font={0|1}', Integer, 'Selects stroke font set [1]') do |o|
+    raise "font must be 0 or 1" unless (0..1) === o
+    $font = o
+  end
+  op.on('--save=FILE', 'Save plot in color postscript file FILE') do |o|
+    $f_name = o
+  end
+  op.separator('')
+  op.separator('Make sure you get it right!')
+end
+
+def plot1(xscale, yscale, xoff, yoff, do_test)
+
+  x = NArray.float(60).indgen!(1).mul!(xscale/60.0).add!(xoff)
+  y = (x**2).mul!(yscale).add!(yoff)
+
+  xmin = x[0]
+  xmax = x[59]
+  ymin = y[0]
+  ymax = y[59]
+
+  xs=[]
+  ys=[]
+
+  6.times do |i|
+    xs[i] = x[i * 10 + 3]
+    ys[i] = y[i * 10 + 3]
+  end
+
+  # Set up the viewport and window using PLENV. The range in X is
+  # 0.0 to 6.0, and the range in Y is 0.0 to 30.0. The axes are
+  # scaled separately (just = 0), and we just draw a labelled
+  # box (axis = 0).
+
+  plcol0(1)
+  plenv(xmin, xmax, ymin, ymax, 0, 0)
+  plcol0(2)
+  pllab("(x)", "(y)", "#frPLplot Example 1 - y=x#u2")
+
+  # Plot the data points
+
+  plcol0(4)
+  plpoin(xs, ys, 9)
+
+  # Draw the line through the data
+
+  plcol0(3)
+  plline(x, y)
+
+  # xor mode enable erasing a line/point/text by replotting it again
+  # it does not work in double buffering mode, however
+
+  if do_test && $test_xor
+    st = plxormod(true) # enter xor mode
+    if (st)
+      60.times do |i|
+        plpoin(x[i], y[i], 9)  # draw a point
+        sleep(0.050)    # wait a little
+        plflush      # force an update of the tk driver
+        plpoin(x[i], y[i], 9)  # erase point
+      end
+      plxormod(0)     # leave xor mode
+    end
+  end
+end
+
+# ===============================================================
+
+def plot2
+
+  # Set up the viewport and window using PLENV. The range in X is -2.0 to
+  # 10.0, and the range in Y is -0.4 to 2.0. The axes are scaled separately
+  # (just = 0), and we draw a box with axes (axis = 1).
+
+  plcol0(1)
+  plenv(-2.0, 10.0, -0.4, 1.2, 0, 1)
+  plcol0(2)
+  pllab("(x)", "sin(x)/x", "#frPLplot Example 1 - Sinc Function")
+
+  # Fill up the arrays
+
+  x = NArray.float(100).indgen!(-19).div!(6)
+  y = sin(x)/x
+  y[x.eq(0).where] = 1.0
+
+  # Draw the line
+
+  plcol0(3)
+  plwid(2)
+  plline(x, y)
+  plwid(0) # Restore default(?)
+end
+
+# ===============================================================
+
+def plot3
+
+  space1 = 1500
+  mark1  = 1500
+
+  # For the final graph we wish to override the default tick intervals, and
+  # so do not use plenv.
+
+  pladv(0)
+
+  # Use standard viewport, and define X range from 0 to 360 degrees, Y range
+  # from -1.2 to 1.2.
+
+  plvsta
+  plwind(0.0, 360.0, -1.2, 1.2)
+
+  # Draw a box with ticks spaced 60 degrees apart in X, and 0.2 in Y.
+
+  plcol0(1)
+  plbox("bcnst", 60.0, 2, "bcnstv", 0.2, 2)
+
+  # Superimpose a dashed line grid, with 1.5 mm marks and spaces.
+
+  plstyl(mark1, space1)
+  plcol0(2)
+  plbox("g", 30.0, 0, "g", 0.2, 0)
+  plstyl
+
+  plcol0(3)
+  pllab("Angle (degrees)", "sine", "#frPLplot Example 1 - Sine function")
+
+  x = NArray.float(101).indgen!.mul!(3.6)
+  y = sin(x * (PI/180))
+
+  plcol0(4)
+  plline(x, y)
+end
+
+#--------------------------------------------------------------------------
+# main
+#
+# Generates several simple line plots.  Demonstrates:
+#   - subwindow capability
+#   - setting up the window, drawing plot, and labelling
+#   - changing the color
+#   - automatic axis rescaling to exponential notation
+#   - placing the axes in the middle of the box
+#   - gridded coordinate axes
+#--------------------------------------------------------------------------
+
+
+# plplot initialization
+
+PLOP.parse!
+
+# Get version number, just for kicks
+
+puts "PLplot library version: #{PL::VERSION}"
+
+# Initialize plplot
+# Divide page into 2x2 plots
+# Note: calling plstar replaces separate calls to plssub and plinit
+
+plstar(2,2)
+
+## Select font set as per input flag
+
+plfontld($fontset)
+
+# Set up the data
+# Original case
+
+xscale = 6
+yscale = 1
+xoff = 0
+yoff = 0
+
+# Do a plot
+
+plot1(xscale, yscale, xoff, yoff, 0)
+
+# Set up the data
+
+xscale = 1
+yscale = 0.0014
+yoff = 0.0185
+
+# Do a plot
+
+digmax = 5
+plsyax(digmax, 0)
+
+plot1(xscale, yscale, xoff, yoff, 1)
+
+plot2
+
+plot3
+
+# Show how to save a plot:
+# Open a new device, make it current, copy parameters,
+# and replay the plot buffer
+
+if ($f_name)            # command line option '-save filename'
+  printf("The current plot was saved in color Postscript under the name `%s'.\n", $f_name)
+  cur_strm = plgstrm    # get current stream
+  new_strm = plmkstrm   # create a new one
+
+  plsfnam($f_name)      # file name
+  plsdev("psc")         # device type
+
+  plcpstrm(cur_strm, 0) # copy old stream parameters to new stream
+  plreplot              # do the save by replaying the plot buffer
+  plend1                # finish the device
+
+  plsstrm(cur_strm)     # return to previous stream
+end
+
+# Let's get some user input
+
+if ($locate_mode)
+  while(true)
+    break unless gin = plGetCursor
+    break if gin.keysym == PLK::Escape
+
+    pltext
+    if gin.keystr
+      printf("subwin = %d, wx = %f, wy = %f,  dx = %f, dy = %f,  c = '%s', state = 0x%08x\n",
+           gin.subwindow, gin.wx, gin.wy, gin.dx, gin.dy, gin.keystr, gin.state)
+    else
+      printf("subwin = %d, wx = %f, wy = %f,  dx = %f, dy = %f,  c = 0x%08x, state = 0x%08x\n",
+           gin.subwindow, gin.wx, gin.wy, gin.dx, gin.dy, gin.keysym, gin.state)
+    end
+
+    plgra
+  end
+end
+
+# Don't forget to call plend to finish off!
+
+plend1
+plend

data/examples/x02.rb

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+$-w = true if $0 == __FILE__
+
+require 'rubygems'
+require 'plplot'
+include PLplot
+
+# Multiple window and color map 0 demo.
+#
+# Demonstrates multiple windows and color map 0 palette, both default and
+# user-modified.
+
+#--------------------------------------------------------------------------*\
+# demo1
+#
+# Demonstrates multiple windows and default color map 0 palette.
+#--------------------------------------------------------------------------*/
+
+def demo1
+
+  plbop
+
+  # Divide screen into 16 regions */
+  plssub(4, 4)
+
+  draw_windows( 16, 0 )
+
+  pleop
+end
+
+#--------------------------------------------------------------------------*\
+# demo2
+#
+# Demonstrates multiple windows, user-modified color map 0 palette, and
+# HLS -> RGB translation.
+#--------------------------------------------------------------------------*/
+
+def demo2
+
+  # Set up cmap0 */
+  # Use 100 custom colors in addition to base 16 */
+  n = 100+16
+  r = NArray.int(n)
+  g = NArray.int(n)
+  b = NArray.int(n)
+
+  # Min & max lightness values */
+  lmin = 0.15
+  lmax = 0.85
+
+  plbop
+
+  # Divide screen into 100 regions
+
+  plssub(10, 10)
+
+  100.times do |i|
+
+    # Bounds on HLS, from plhlsrgb commentary --
+    #   hue             [0., 360.]      degrees
+    #   lightness       [0., 1.]        magnitude
+    #   saturation      [0., 1.]        magnitude
+
+    # Vary hue uniformly from left to right
+    h = (360.0 / 10.0 ) * ( i % 10 )
+    # Vary lightness uniformly from top to bottom, between min & max
+    l = lmin + (lmax - lmin) * (i / 10) / 9.0
+    # Use max saturation
+    s = 1.0
+
+    r1, g1, b1 = plhlsrgb(h, l, s)
+    #printf("%3d %15.9f %15.9f %15.9f %15.9f %15.9f %15.9f\n", 
+    #       i+16,h,l,s,r1,g1,b1)
+
+    # Use 255.001 to avoid close truncation decisions in this example. */
+    r[i+16] = r1 * 255.001
+    g[i+16] = g1 * 255.001
+    b[i+16] = b1 * 255.001
+  end
+
+  # Load default cmap0 colors into our custom set
+  16.times {|i| r[i], g[i], b[i] = plgcol0(i)}
+
+  #n.times {|i| printf("%3d %3d %3d %3d\n", i, r[i], g[i], b[i])}
+
+  # Now set cmap0 all at once (faster, since fewer driver calls) */
+  plscmap0(r, g, b)
+
+  draw_windows( 100, 16 )
+
+  pleop
+end
+
+#--------------------------------------------------------------------------
+# draw_windows
+#
+# Draws a set of numbered boxes with colors according to cmap0 entry.
+#--------------------------------------------------------------------------
+
+def draw_windows(nw, cmap0_offset)
+
+  plschr(0.0, 3.5)
+  plfont(4)
+
+  nw.times do |i|
+    plcol0(i+cmap0_offset)
+    text = i.to_s
+    pladv(0)
+    vmin = 0.1
+    vmax = 0.9
+    3.times do |j|
+      plwid(j + 1)
+      plvpor(vmin, vmax, vmin, vmax)
+      plwind(0.0, 1.0, 0.0, 1.0)
+      plbox("bc", 0.0, 0, "bc", 0.0, 0)
+      vmin = vmin + 0.1
+      vmax = vmax - 0.1
+    end
+    plwid(1)
+    plptex(0.5, 0.5, 1.0, 0.0, 0.5, text)
+  end
+end
+
+# Parse and process command line arguments
+PLOptionParser.parse!
+
+# Initialize plplot
+plinit
+
+# Run demos
+demo1
+demo2
+
+plend