TriD(3pm)

NAME

PDL::Graphics::TriD -- PDL 3D interface

SYNOPSIS

use PDL::Graphics::TriD;

# Generate a somewhat interesting sequence of points:
$t = sequence(100)/10;
$x = sin($t); $y = cos($t), $z = $t;
$coords = cat($x, $y, $z)->xchg(0,1);
$r = cos(2*$t); $g = sin($t); $b = $t;
$colors = cat($r, $g, $b)->xchg(0,1);

# After each graph, let the user rotate and
# wait for him to press 'q', then make new graph
line3d($coords);       # $coords = (3,n,...)
line3d($coords,$colors);  # $colors = (3,n,...)
line3d([$x,$y,$z]);

# Generate a somewhat interesting sequence of surfaces
$surf1 = (rvals(100, 100) / 50)**2 + sin(xvals(100, 100) / 10);
$surf2 = sqrt(rvals(zeroes(50,50))/2);
$x = sin($surface); $y = cos($surface), $z = $surface;
$coords = cat($x, $y, $z)->xchg(0,1);
$r = cos(2*$surface); $g = sin($surface); $b = $surface;
$colors = cat($r, $g, $b)->xchg(0,1);
imagrgb([$r,$g,$b]);     # 2-d piddles
lattice3d([$surf1]);
points3d([$x,$y,$z]);
spheres3d([$x,$y,$z]);  # preliminary implementation

hold3d(); # the following graphs are on top of each other and the previous
line3d([$x,$y,$z]);
line3d([$x,$y,$z+1]);
$pic = grabpic3d(); # Returns the picture in a (3,$x,$y) float piddle (0..1).

release3d(); # the next graph will again wipe out things.

WARNING

These modules are still in a somewhat unfocused state: don't use them
yet if you don't know how to make them work if they happen to do
something strange.

DESCRIPTION

This module implements a generic 3D plotting interface for PDL.
Points, lines and surfaces (among other objects) are supported.

With OpenGL, it is easy to manipulate the resulting 3D objects with the mouse in real time - this helps data visualization a lot.

= for comment With VRML, you can generate objects for everyone to see
with e.g. Silicon Graphics' Cosmo Player. You can find out more about VRML at "http://vrml.sgi.com/" or "http://www.vrml.org/"

SELECTING A DEVICE

The default device for TriD is currently OpenGL. You can specify a
different device either in your program or in the environment variable "PDL_3D_DEVICE". The one specified in the program takes priority.

The currently available devices are

GL OpenGL

GLpic OpenGL but off-line (pixmap) rendering and writing to a: graphics file.
VRML ( Not available this release ): VRML objects rendering. This writes a VRML file describing the scene. This VRML file can then be read with a browser.

ONLINE AND OFFLINE VISUALIZATION

TriD offers both on- and off-line visualization. Currently the
interface w.r.t. this division is still much in motion.

For OpenGL you can select either on- or off-line rendering. VRML is
currently always offline (this may change later, if someone bothers to write the java(script) code to contact PDL and wait for the next
PDL image over the network.

COORDINATE SPECIFICATIONS

Specifying a set of coordinates is generally a context-dependent
operation. For a traditional 3D surface plot, you'll want two of the
coordinates to have just the xvals and yvals of the piddle,
respectively. For a line, you would generally want to have one
coordinate held at zero and the other advancing.

This module tries to make a reasonable way of specifying the context
while letting you do whatever you want by overriding the default
interpretation.

The alternative syntaxes for specifying a set of coordinates (or colors) are: $piddle # MUST have 3 as first dim.
[$piddle] [$piddle1,$piddle2] [$piddle1,$piddle2,$piddle3] [CONTEXT,$piddle] [CONTEXT,$piddle1,$piddle2] [CONTEXT,$piddle1,$piddle2,$piddle3]
where "CONTEXT" is a string describing in which context you wish these piddles to be interpreted. Each routine specifies a default context which is explained in the routines documentation. Context is usually used only to understand what the user wants when he/she specifies less than 3 piddles.
The following contexts are currently supported:
SURF2D A 2-D lattice. " [$piddle] " is interpreted as the Z coordinate: over a lattice over the first dimension. Equivalent to "
[$piddle-"xvals, $piddle->yvals, $piddle] >.
POLAR2D A 2-D polar coordinate system. " [$piddle] " is interpreted as: the z coordinate over theta and r (theta = the first dimension of the piddle).
COLOR A set of colors. " [$piddle] " is interpreted as grayscale: color (equivalent to " [$piddle,$piddle,$piddle] ").
LINE A line made of 1 or 2 coordinates. " [$piddle] " is interpreted: as " [$piddle-"xvals,$piddle,0] >. " [$piddle1,$piddle2] " is
interpreted as " [$piddle1,$piddle2,$piddle1-"xvals] >.
What makes contexts useful is that if you want to plot points instead of the full surface you plotted with: imag3d([$zcoords]);
you don't need to start thinking about where to plot the points:: points3d([SURF2D,$zcoords]);
will do exactly the same.
Wrapping your head around 3d surface specifications: Let's begin by thnking about how you might make a 2d data plot. If you sampled your data at regular intervals, you would have a time serires
y(t) = (y0, y1, y2, ...). You could plot y vs t by computing t0 = 0,
t1 = dt, t2 = 2 * dt, and then plotting (t0, y0), (t1, y1), etc.; Next suppose that you measured x(t) and y(t). You can still plot y vs t, but you can also plot y vs x by plotting (x0, y0), (x1, y1), etc.
The x-values don't have to increase monotonically: they could backtrack on each other, for example, like the latitude and longitude of a boat on a lake. If you use plplot, you would plot this data using
"$pl->xyplot($x, $y, PLOTTYPE => 'POINTS')".; Good. Now let's add a third coordinate, z(t). If you actually sampled x and y at regular intervals, so that x and y lie on a grid, then you
can construct a grid for z(x, y), and you would get a surface. This is the situation in which you would use "mesh3d([$surface])".; Of course, your data is not required to be regularly gridded. You
could, for example, be measuring the flight path of a bat flying after mosquitos, which could be wheeling and arching all over the space.
This is what you might plot using "line3d([$x, $y, $z])". You could
plot the trajectories of multiple bats, in which case $x, $y, and $z
would have multiple columns, but in general you wouldn't expect them to be coordinated.; Finally, imagine that you have an air squadron flying in formation.
Your (x, y, z) data is not regularly gridded, but the (x, y, z) data
for each plane should be coordinated and we can imagine that their
flight path sweep out a surface. We could draw this data using
"line3d([$x, $y, $z])", where each column in the variables corresponds to a different plane, but it would also make sense to draw this data
using "mesh3d([$x, $y, $z])", since the planes' proximity to each other should be fairly consistent. In other words, it makes sense to think
of the planes as sweeping out a coordinated surface, which "mesh3d"
would draw for you, whereas you would not expect the trajectories of
the various bats to describe a meaningful surface (unless you're into
fractals, perhaps).

#!/usr/bin/perl

use PDL;
use PDL::Graphics::TriD;

# Draw out a trajectory in three-space
$t = sequence(100)/10;
$x = sin($t); $y = cos($t); $z = $t;

# Plot the trajectory as (x(t), y(t), z(t))
print "using line3d to plot a trajectory (press q when you're done twiddling)\n";
line3d [$x,$y,$z];

# If you give it a single piddle, it expects
# the data to look like
# ((x1, y1, z1), (x2, y2, z2), ...)
# which is why we have to do the exchange:
$coords = cat($x, $y, $z)->xchg(0,1);
print "again, with a different coordinate syntax (press q when you're done twiddling)\n";
line3d $coords;

# Draw a regularly-gridded surface:
$surface = sqrt(rvals(zeroes(50,50))/2);
print "draw a mesh of a regularly-gridded surface using mesh3d\n";
mesh3d [$surface];
print "draw a regularly-gridded surface using imag3d\n";
imag3d [$surface], {Lines=>0};

# Draw a mobius strip:
$two_pi = 8 * atan2(1,1);
$t = sequence(50) / 50 * $two_pi;
# We want two paths:
$mobius1_x = cos($t) + 0.5 * sin($t/2);
$mobius2_x = cos($t);
$mobius3_x = cos($t) - 0.5 * sin($t/2);
$mobius1_y = sin($t) + 0.5 * sin($t/2);
$mobius2_y = sin($t);
$mobius3_y = sin($t) - 0.5 * sin($t/2);
$mobius1_z = $t - $two_pi/2;
$mobius2_z = zeroes($t);
$mobius3_z = $two_pi/2 - $t;

$mobius_x = cat($mobius1_x, $mobius2_x, $mobius3_x);
$mobius_y = cat($mobius1_y, $mobius2_y, $mobius3_y);
$mobius_z = cat($mobius1_z, $mobius2_z, $mobius3_z);

$mobius_surface = cat($mobius_x, $mobius_y, $mobius_z)->mv(2,0);

print "A mobius strip using line3d one way\n";
line3d $mobius_surface;
print "A mobius strip using line3d the other way\n";
line3d $mobius_surface->xchg(1,2);
print "A mobius strip using mesh3d\n";
mesh3d $mobius_surface;
print "The same mobius strip using imag3d\n";
imag3d $mobius_surface, {Lines => 0};

SIMPLE ROUTINES

Because using the whole object-oriented interface for doing all your
work might be cumbersome, the following shortcut routines are
supported:

FUNCTIONS

line3d: 3D line plot, defined by a variety of contexts.

line3d piddle(3,x), {OPTIONS}
line3d [CONTEXT], {OPTIONS}; Example:

pdl> line3d [sqrt(rvals(zeroes(50,50))/2)]
- Lines on surface
pdl> line3d [$x,$y,$z]
- Lines over X, Y, Z
pdl> line3d $coords
- Lines over the 3D coordinates in $coords.; Note: line plots differ from mesh plots in that lines only go in one
direction. If this is unclear try both!; See module documentation for more information on contexts and options
imag3d: 3D rendered image plot, defined by a variety of contexts

imag3d piddle(3,x,y), {OPTIONS}
imag3d [piddle,...], {OPTIONS}; Example:

pdl> imag3d [sqrt(rvals(zeroes(50,50))/2)], {Lines=>0};

- Rendered image of surface; See module documentation for more information on contexts and options
mesh3d: 3D mesh plot, defined by a variety of contexts

mesh3d piddle(3,x,y), {OPTIONS}
mesh3d [piddle,...], {OPTIONS}; Example:

pdl> mesh3d [sqrt(rvals(zeroes(50,50))/2)]

- mesh of surface; Note: a mesh is defined by two sets of lines at right-angles (i.e. this is how is differs from line3d).; See module documentation for more information on contexts and options
lattice3d: alias for mesh3d
points3d: 3D points plot, defined by a variety of contexts

points3d piddle(3), {OPTIONS}
points3d [piddle,...], {OPTIONS}; Example:

pdl> points3d [sqrt(rvals(zeroes(50,50))/2)];
- points on surface; See module documentation for more information on contexts and options
spheres3d: 3D spheres plot (preliminary implementation)

spheres3d piddle(3), {OPTIONS}
spheres3d [piddle,...], {OPTIONS}; Example:

pdl> spheres3d ndcoords(10,10,10)->clump(1,2,3)

- lattice of spheres at coordinates on 10x10x10 grid; This is a preliminary implementation as a proof of concept. It has
fixed radii for the spheres being drawn and no control of color or
transparency.
imagrgb: 2D RGB image plot (see also imag2d)

imagrgb piddle(3,x,y), {OPTIONS}
imagrgb [piddle,...], {OPTIONS}; This would be used to plot an image, specifying red, green and blue
values at each point. Note: contexts are very useful here as there are many ways one might want to do this.; e.g.

pdl> $a=sqrt(rvals(zeroes(50,50))/2)
pdl> imagrgb [0.5*sin(8*$a)+0.5,0.5*cos(8*$a)+0.5,0.5*cos(4*$a)+0.5]
imagrgb3d: 2D RGB image plot as an object inside a 3D space

imagrdb3d piddle(3,x,y), {OPTIONS}
imagrdb3d [piddle,...], {OPTIONS}; The piddle gives the colors. The option allowed is Points, which should give 4 3D coordinates for the corners of the polygon, either as a
piddle or as array ref. The default is
[[0,0,0],[1,0,0],[1,1,0],[0,1,0]].; e.g.

pdl> imagrgb3d $colors, {Points => [[0,0,0],[1,0,0],[1,0,1],[0,0,1]]};
- plot on XZ plane instead of XY.
grabpic3d: Grab a 3D image from the screen.

$pic = grabpic3d();; The returned piddle has dimensions (3,$x,$y) and is of type float
(currently). XXX This should be altered later.
hold3d, release3d: Keep / don't keep the previous objects when plotting new 3D objects

hold3d();
release3d();; or

hold3d(1);
hold3d(0);
keeptwiddling3d, nokeeptwiddling3d: Wait / don't wait for 'q' after displaying a 3D image.; Usually, when showing 3D images, the user is given a chance to rotate
it and then press 'q' for the next image. However, sometimes (for e.g. animation) this is undesirable and it is more desirable to just run one step of the event loop at a time.

keeptwiddling3d();
nokeeptwiddling3d();; or

keeptwiddling3d(1);
keeptwiddling3d(0);; When an image is added to the screen, keep twiddling it until user
explicitly presses 'q'.

keeptwiddling3d();
imag3d(..);
nokeeptwiddling3d();
$o = imag3d($c);
while(1) {
$c .= nextfunc($c);
$o->data_changed();
twiddle3d(); # animate one step, then return.

}
twiddle3d: Wait for the user to rotate the image in 3D space.; Let the user rotate the image in 3D space, either for one step or until (s)he presses 'q', depending on the 'keeptwiddling3d' setting. If
'keeptwiddling3d' is not set the routine returns immediately and
indicates that a 'q' event was received by returning 1. If the only
events received were mouse events, returns 0.

CONCEPTS

The key concepts (object types) of TriD are explained in the following:
Object: In this 3D abstraction, everything that you can "draw" without using
indices is an Object. That is, if you have a surface, each vertex is
not an object and neither is each segment of a long curve. The whole
curve (or a set of curves) is the lowest level Object.; Transformations and groups of Objects are also Objects.; A Window is simply an Object that has subobjects.
Twiddling: Because there is no eventloop in Perl yet and because it would be
hassleful to do otherwise, it is currently not possible to e.g. rotate objects with your mouse when the console is expecting input or the
program is doing other things. Therefore, you need to explicitly say
"$window->twiddle()" in order to display anything.

OBJECTS

The following types of objects are currently supported. Those that do not have a calling sequence described here should have their own manual pages.

There are objects that are not mentioned here; they are either internal to PDL3D or in rapidly changing states. If you use them, you do so at
your own risk.

The syntax "PDL::Graphics::TriD::Scale(x,y,z)" here means that you create an object like: $a = new PDL::Graphics::TriD::Scale($x,$y,$z);
PDL::Graphics::TriD::LineStrip: This is just a line or a set of lines. The arguments are 3 1-or-more-D piddles which describe the vertices of a continuous line and an
optional color piddle (which is 1-D also and simply defines the color
between red and blue. This will probably change).
PDL::Graphics::TriD::Lines: This is just a line or a set of lines. The arguments are 3 1-or-more-D piddles where each contiguous pair of vertices describe a line segment and an optional color piddle (which is 1-D also and simply defines the color between red and blue. This will probably change).
PDL::Graphics::TriD::Image: This is a 2-dimensional RGB image consisting of colored rectangles.
With OpenGL, this is implemented by texturing so this should be
relatively memory and execution-time-friendly.
PDL::Graphics::TriD::Lattice: This is a 2-D set of points connected by lines in 3-space. The
constructor takes as arguments 3 2-dimensional piddles.
PDL::Graphics::TriD::Points: This is simply a set of points in 3-space. Takes as arguments the x, y and z coordinates of the points as piddles.
PDL::Graphics::TriD::Scale(x,y,z): Self-explanatory
PDL::Graphics::TriD::Translation(x,y,z): Ditto
PDL::Graphics::TriD::Quaternion(c,x,y,z): One way of representing rotations is with quaternions. See the
appropriate man page.
PDL::Graphics::TriD::ViewPort: This is a special class: in order to obtain a new viewport, you need to have an earlier viewport on hand. The usage is:

$new_vp = $old_vp->new_viewport($x0,$y0,$x1,$y1);; where $x0 etc are the coordinates of the upper left and lower right
corners of the new viewport inside the previous (relative to the
previous viewport in the (0,1) range.; Every implementation-level window object should implement the
new_viewport method.

EXAMPLE SCRIPT FOR VARIOUS

BUGS

Not enough is there yet.

AUTHOR

Copyright (C) 1997 Tuomas J. Lukka (lukka@husc.harvard.edu).
Documentation contributions from Karl Glazebrook
(kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty.
You are allowed to redistribute this software / documentation under
certain conditions. For details, see the file COPYING in the PDL
distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

docs.sk

comprehensive documentation repository

See also