PDL::Graphics::X - PDL OO access to X windows
# example 1
use PDL;
use PDL::Graphics::X;
my $x_size = 255; my $y_size = 255;
my $win1 = PDL::Graphics::X->new({SIZE_X => $x_size, SIZE_Y => $y_size});
my $a = xvals(zeroes(byte,$x_size,$y_size));
$win1->imag($a);
# example 2
use PDL;
use PDL::Graphics::X;
my $win1 = PDL::Graphics::X->new({WIN_TITLE => "PDL", SIZE_X => 210, SIZE_Y => 210});
my $x = pdl(10, 100, 100, 10);
my $y = pdl(10, 10, 100, 100);
$win1->line($x, $y, {COLOR => [1,0,0], LINEWIDTH => 5});
This module interfaces PDL directly to X windows in a OO fashion. Each X object has an associated X window and handles opening, closing and drawing in the associated window. Hopefully it is reasonably intuitive to use. The vision is that this will serve as a base upon which other fully native PDL graphics modules could be built.
Common options such as LINEWIDTH are remembered from function call to function call, i.e. if you call $win1->line($x, $y, {COLOR => [1,0,0], LINEWIDTH => 5}) then the rectangle drawn by $win1->rect(10, 10, 190, 190) will also have a red border of width equal to 5.
Constructor for a new X window object.
Usage: my $win1 = PDL::Graphics::X->new(); # open the window with the defaults
Usage: my $win1 = PDL::Graphics::X->new({WIN_TITLE => "PDL", SIZE_X => 210, SIZE_Y => 210});
Creates a new X object & its associated X window.
Options recognized :
SIZE_X - window x size in pixels (default = 400)
SIZE_Y - window y size in pixels (default = 300)
WIN_TITLE - A title for the window, if desired (default = "X")
BACK_COLOR - [r, g, b] the windows background color (default = [1.0, 1.0, 1.0], i.e. white)
Display a PDL as a bitmap.
Usage: $win1->imag($my_img); # display an image with default size and scaling
Usage: $win1->imag($my_img, {AUTO_SCALE => 1.0}); # display an auto-scaled image
Displays a PDL as a bitmap. The PDL can be of size either (m,n) or (m,n,3). PDLs of size (m,n) are converted to indexed color based on the current color table (see ctab). PDLs of size (m,n,3) are displayed as true-color images with the last dimension specifying the color (RGB). Unless a re-scaling is specified, the minimum value displayed is 0.0 and the maximum is 255.0. If the PDL is larger then the window then the window will be re-scaled to accomodate the PDL;
Options recognized :
DEST_X - position of the left side of the bitmap in pixels (default = 0)
DEST_Y - position of the bottom of the bitmap in pixels (default = 0)
DEST_W - width of the bitmap to be displayed (default = width of the PDL)
DEST_H - height of the bitmap to be displayed (default = height of the PDL)
AUTO_SCALE - if set equal to 1, the PDL will be rescaled such that its
minimum value is 1 and its max is 255 (default = 0)
MIN - the minimum value to be displayed (default = 0.0)
MAX - the maximum value to be displayed (default = 255.0)
Set the color table
Usage: $win1->ctab(cat(lut_data('idl5'))); # set the color table to idl5
Makes a local copy of a user supplied color table. The color table must be a 256 x 4 pdl of the form (l,r,g,b), as would be generated by the command '$ct = cat(lut_data("xyz"))'. The l value is ignored. The r, g and b values should be in the range 0.0 - 1.0.
Draws a vector as connected points.
Usage: $win1->line($x, $y, {COLOR => [0,0,0], LINEWIDTH => 5}); # draw black line of width 5
Draw a poly-line between a set of points given by two PDLs of size (n). The first PDL gives the x position & the second piddle gives the y position of the individual points, n is the total number of points.
Options recognized
LINEWIDTH - line width
LINESTYLE - line style (0 = normal, 1 = dashed)
COLOR - [r, g, b] color of the line
Draws a rectangle.
Usage: $win1->rect($x1, $y1, $x2, $y2);
Draws a rectangle with corners at ($x1, $y1) and ($x2, $y2).
Options recognized
LINEWIDTH - line width
LINESTYLE - line style (0 = normal, 1 = dashed)
COLOR - [r, g, b] color of the line
Draws a circle.
Usage: $win1->circle($x, $y, $r);
Draws a circle centered at ($x, $y) with radius $r.
Options recognized
LINEWIDTH - line width
LINESTYLE - line style (0 = normal, 1 = dashed)
COLOR - [r, g, b] color of the line
Draws an oval.
Usage: $win1->ellipse($x, $y, $a, $b);
Draws a oval centered at ($x, $y) with x size $a and y size $b.
Options recognized
LINEWIDTH - line width
LINESTYLE - line style (0 = normal, 1 = dashed)
COLOR - [r, g, b] color of the line
Erases the contents of the window.
Usage: $win1->erase();
Resets the contents of the window to the background color.
Draw text
Usage: $win1->text("hello", $x, $y, $angle);
Draws text starting at $x and $y with baseline angle given by $angle. If you know how to draw truly rotated text in X, please let me know. How fonts are currently dealt with is imperfect at best. So that the font size can easily be changed, a search is performed for a scalable font with specified font name. If such a font cannot be found then the text will be displayed with the default X font and no font scaling.
Options recognized
FONT_NAME - name of the font family (default = "courier")
CHARSIZE - desired font size in points
COLOR - [r, g, b] color of the font
Returns the location of next mouse click in the window
Usage : my($x,$y) = $win1->cursor();
Returns the x & y locations of the next mouse click in the window.
Returns 0 if the window still exists, 1 if it does not
Usage : my $exists = $win1->we_exist();
Originally written to help debug some problems with associated with X windows being closed by the user with a mouse. Preserved on the off chance that it will be useful to a dependent module.
Returns the window size & maximum window size (in pixels) in x and y
Usage : my ($win_x, $win_y, $max_x, $max_y) = $win1->winsize();
Primarily intended for use by dependent modules that might want to know what the current and maximum window size is.
resizes a window & returns the new size (which might not be what you requested)
Usage : my ($new_x, $new_y) = $win1->resize($size_x, $size_y);
Primarily intended for use by dependent modules that might want to resize a window without destroying it and creating another one.
In order to keep from crashing hard when an X window is closed by the mouse, this module has its own SIGPIPE error handler. Hopefully this will not conflict with possibly similar error handlers created by other modules.
Font handling is poorly implemented as is rotated text.
Depending on the context RGB triples do not always give you the color you might have desired. They seem to work fine in the context of bitmaps, but more poorly in the context of line & text coloring.
...
Hazen Babcock (hbabcockos1 at mac.com)
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
