PDL::Graphics::X is a PDL OO access to X windows.

SYNOPSIS

# 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.

FUNCTIONS

new

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)
imag

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)
ctab

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.

line

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
rect

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
circle

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
ellipse

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
erase

Erases the contents of the window.

Usage: $win1->erase();

Resets the contents of the window to the background color.

text

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

cursor

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.

we_exist

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.

winsize

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.

resize

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.