Provided by: pdl_2.084-1_amd64 bug

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)->transpose;
        my $red = cos(2*$t); my $green = sin($t); my $blue = $t;
        $colors = cat($red, $green, $blue)->transpose;

        # After each graph, let the user rotate and
        # wait for them 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)->transpose;
        $red = cos(2*$surface); $green = sin($surface); $blue = $surface;
        $colors = cat($red, $green, $blue)->transpose;
        imagrgb([$red,$green,$blue]);     # 2-d ndarrays
        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 ndarray (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.

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 ndarray, 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

          $ndarray                             # MUST have 3 as first dim.
         [$ndarray]
         [$ndarray1,$ndarray2]
         [$ndarray1,$ndarray2,$ndarray3]
         [CONTEXT,$ndarray]
         [CONTEXT,$ndarray1,$ndarray2]
         [CONTEXT,$ndarray1,$ndarray2,$ndarray3]

       where "CONTEXT" is a string describing in which context you wish these ndarrays 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 they
       specify less than 3 ndarrays.

       The following contexts are currently supported:

       SURF2D  A 2-D lattice. " [$ndarray] " is interpreted as the Z coordinate over a lattice
               over the first dimension. Equivalent to "[$ndarray->xvals, $ndarray->yvals,
               $ndarray]".

       POLAR2D A 2-D polar coordinate system. " [$ndarray] " is interpreted as the z coordinate
               over theta and r (theta = the first dimension of the ndarray).

       COLOR   A set of colors. " [$ndarray] " is interpreted as grayscale color (equivalent to "
               [$ndarray,$ndarray,$ndarray] ").

       LINE    A line made of 1 or 2 coordinates. " [$ndarray] " is interpreted as
               "[$ndarray->xvals,$ndarray,0]". " [$ndarray1,$ndarray2] " is interpreted as
               "[$ndarray1,$ndarray2,$ndarray1->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 thinking 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 back-track 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.

       More generally, each coordinate is expected to be arranged in a 3D fashion, similar to
       "3,x,y". The "3" is the actual 3D coordinates of each point. The "x,y" help with gridding,
       because each point at "x,y" is expected to have as geographical neighbours "x+1,y",
       "x-1,y", "x,y+1", "x,y-1", and the grid polygon-building relies on that.  This is how, and
       why, the 3D earth in "demo 3d" arranges its data.

        #!/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 ndarray, 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)->transpose;
        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(51) / 50 * $two_pi;
        # We want three 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.

       Implemented by "PDL::Graphics::TriD::LineStrip".

        line3d ndarray(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

       Implemented by "PDL::Graphics::TriD::SLattice_S".

       The variant, "imag3d_ns", is implemented by "PDL::Graphics::TriD::SLattice".

        imag3d ndarray(3,x,y), {OPTIONS}
        imag3d [ndarray,...], {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

       Implemented by "PDL::Graphics::TriD::Lattice".

        mesh3d ndarray(3,x,y), {OPTIONS}
        mesh3d [ndarray,...], {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

   trigrid3d
       Show a triangular mesh, giving $vertices and $faceidx which is a series of triplets of
       indices into the vertices, each describing one triangle. The order of points matters for
       the shading - the normal vector points towards the clockface if the points go clockwise.

       Options: "Smooth" (on by default), "Lines" (off by default), "ShowNormals" (off by
       default, useful for debugging).

       Implemented by "PDL::Graphics::TriD::STrigrid_S".

   trigrid3d_ns
       Like "trigrid3d", but without shading or normals.

       Implemented by "PDL::Graphics::TriD::STrigrid".

   points3d
       3D points plot, defined by a variety of contexts

       Implemented by "PDL::Graphics::TriD::Points".

        points3d ndarray(3), {OPTIONS}
        points3d [ndarray,...], {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)

       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.

       Implemented by "PDL::Graphics::TriD::Spheres".

        spheres3d ndarray(3), {OPTIONS}
        spheres3d [ndarray,...], {OPTIONS}

       Example:

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

        - lattice of spheres at coordinates on 10x10x10 grid

   imagrgb
       2D RGB image plot (see also imag2d)

       Implemented by "PDL::Graphics::TriD::Image".

        imagrgb ndarray(3,x,y), {OPTIONS}
        imagrgb [ndarray,...], {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> $x=sqrt(rvals(zeroes(50,50))/2)
        pdl> imagrgb [0.5*sin(8*$x)+0.5,0.5*cos(8*$x)+0.5,0.5*cos(4*$x)+0.5]

   imagrgb3d
       2D RGB image plot as an object inside a 3D space

       Implemented by "PDL::Graphics::TriD::Image".

        imagrdb3d ndarray(3,x,y), {OPTIONS}
        imagrdb3d [ndarray,...], {OPTIONS}

       The ndarray gives the colors. The option allowed is Points, which should give 4 3D
       coordinates for the corners of the polygon, either as an ndarray 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 ndarray 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);
        do {
               $c .= nextfunc($c);
               $o->data_changed;
        } while(!twiddle3d()); # animate one step, then iterate
        keeptwiddling3d();
        twiddle3d(); # wait one last time

   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 they press '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.

   close3d
       Close the currently-open 3D window.

NOT EXPORTED

       These functions are not exported, partly because they are not fully implemented.

       contour3d
           Implemented by "PDL::Graphics::TriD::Contours".

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

               $c = PDL::Graphics::TriD::Scale->new($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 ndarrays which
       describe the vertices of a continuous line and an optional color ndarray (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 ndarrays where each
       contiguous pair of vertices describe a line segment and an optional color ndarray (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 ndarrays.

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

   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.

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.