NAME

       Math::VectorReal - Module to handle 3D Vector Mathematics

SYNOPSIS

           #!/usr/bin/perl
           use Math::VectorReal;

           $a = vector( 1, 2, .5 );
           print "Vector as string (MatrixReal default format)\n\$a => ", $a;

           print  $a->stringify("Formated Output   \$a => { %g, %g, %g }\n");

           # I hate newline in the default output format (defined as MatrixReal)
           $Math::VectorReal::FORMAT = "[ %.5f %.5f %.5f ]";
           print "Modified default output format   \$a => $a\n";

           print 'length     => ', $a->length, "\n";
           print 'normalised => ', $a->norm, "\n";

           use Math::VectorReal qw(:all);  # Include O X Y Z axis constant vectors
           print 'string concat   $a."**" = ', $a."**", "\n";
           print 'vector constant    X    = ',   X,    "\n";
           print 'subtraction     $a - Z  = ', $a - Z, "\n";
           print 'scalar divide   $a / 3  = ', $a / 3, "\n";
           print 'dot product     $a . Y  = ', $a . Y, "\n";
           print 'cross product   $a x Y  = ', $a x Y, "\n";

           print "Plane containing points X, \$a, Z (in anti-clockwise order)\n";
           ($n,$d) = plane( X, $a, Z ); # return normal and disance from O
           print '      normal      =    $n     = ', $n, "\n";
           print '  disance from O  =    $d     = ', $d, "\n";
           print ' Y axis intersect = $d/($n.Y) = ', $d/($n.Y), "\n";

           print "VectorReal and MatrixReal interaction\n\n";
           use Math::MatrixReal;  # Not required for pure vector math as above

           $r = $a->vector2matrix_row;  # convert to MatrixReal Row Vector
           $c = $a->vector2matrix_col;  # convert to MatrixReal Column Vector
           print 'Vector as a MatrixReal Row $r (vector -> matrix) => ', "\n", $r;
           print 'Vector as a MatrixReal Col $c (vector -> matrix) => ', "\n", $c;

           $nx = $a->norm;   $ny = $nx x Z;  $nz = $nx x $ny; # orthogonal vectors
           $R = vector_matrix( $nx, $ny, $nz );   # make the rotation matrix
           print 'Rotation Matrix from 3 Vectors   $R   => ',"\n", $R, "\n";

           print "Extract the Y row from the matrix as a VectorReal..\n";
           print '$R->matrix_row2vector(1) => ', $R->matrix_row2vector(1), "\n";

           print "Rotate a vector with above rotation matrix\n";
           print '$a * $R (vector -> vector)',"\n", $a * $R, "\n";

           print "Rotate a MatrixReal column (post multiply)...\n";
           print "(NB: matrix must be transposed (~) to match column format)\n";
           print '~$R * $c (col_matrix -> col_matrix) =>',"\n", ~$R * $c, "\n";

DESCRIPTION

       The "Math::VectorReal" package defines a 3D mathematical "vector", in a way that is
       compatible with the previous CPAN module "Math::MatrixReal". However it provides a more
       vector oriented set of mathematical functions and overload operators, to the "MatrixReal"
       package.  For example the normal perl string functions "x" and "." have been overloaded to
       allow vector cross and dot product operations. Vector math formula thus looks like vector
       math formula in perl programs using this package.

       While this package is compatible with Math::MatrixReal, you DO NOT need to have that
       package to perform purely vector orientated calculations. You will need it however if you
       wish to do matrix operations with these vectors. The interface has been designed with this
       package flexibility in mind.

       The vectors are defined in the same way as a "row" "Math::MatrixReal" matrix, instead of
       that packages choice of "column" definition for vector operations.  Such vectors are
       multiplied to matices with the vector on the left and the matrix on the right. EG:   v * M
       -> 'v

       Not only is this the way I prefer to handle vectors, but it is the way most graphics books
       use vectors. As a bonus it results in no overload conflicts between this package and that
       of Math::MatrixReal, (the left objects overload operator is called to do the mathematics).
       It also is a lot simpler than "MatrixReal" column vector methods, which were designed for
       equation solving rather than 3D geometry operations.

       The  vector_matrix()  function provided, simplifies the creation a "MatrixReal" object
       from 3 (usually orthogonal) vectors. This with its vector orientated math operators makes
       it very easy to define orthogonal rotation matrices from "Math::VectorReal" objects.  See
       a rough example in the synopsis above, or in the file "matrix_test" in the packages
       source.

       NOTE: the 6th element the "Math::MatrixReal" array object is used to hold the length of
       the vector so that it can be re-used without needing to be re-calculated all the time.
       This means the expensive sqrt() function, need not be called unless nessary.  This usage
       should not effect the direct use of these objects in the "Math::MatrixReal" functions.

CONSTANTS

       Four constant vectors are available for export (using an ":all" tag).  these are

           0 = [ 0 0 0 ]   the zero vector or origin
           X = [ 1 0 0 ]   |
           Y = [ 0 1 0 ]    > Unit axis vectors
           Z = [ 0 0 1 ]   |

CONSTRUCTORS

       new(x,y,z)
           Create a new vector with the values of "x", "y", "z" returning the appropriate object.

       vector(x,y,z)
           As "new" but is a exported function which does not require a package reference to
           create a "Math::VectorReal" object.

       clone()
           Return a completely new copy of the referring "Math::VectorReal" object.

METHODS

       array()
           Return the x,y,z elements of the referring vector are an array of values.

       x() Return the x element of the referring vector.

       y() Return the y element of the referring vector.

       z() Return the z element of the referring vector.

       stringify( [ FORMAT ] )
           Return the referring verctor as a string. The "FORMAT" if given is used to sprintf
           format the vector. This is used for all VectorReal to String conversions.

           By default this format is the same as it would be for a "Math::MatrixReal" object, "[
           %#19.12E %#19.12E %#19.12E ]\n".  Note that this includes a newline character!.

           However unlike "Math::MatrixReal" you can assign a new default sprintf format by
           assigning it to the packages $FORMAT variable. For Example

              $Math::VectorReal::FORMAT = "{ %g, %g, %g }"

           Which is a good format to output vectors for use by the POVray (Persistence of Vision
           Raytracer) program.

       length()
           Return the length of the given vector. As a side effect the length is saved into that
           vectors object to avoid the use of the expensive sqrt() function.

       norm()
           Normalise the Vector. That is scalar divide the vector by its length, so that it
           becomes of length one.  Normal vectors are commonly use to define directions, without
           scale, or orientation of a 3 dimensional plane.

       plane( v1, v2, v3 )
           Given three points defined counter clockwise on a plane, return an array in which the
           first element is the planes normal unit vector, and the second its distance from the
           origin, along that vector.  NOTE: the distance may be negitive, in which case the
           origon is above the defined plane in 3d space.

       vector_matrix( nx, ny, nz )
           Given the new location for the X, Y and Z vectors, concatanate them together (row
           wise) to create a "Math::MatrixReal" translation matrix. For example if the 3 vectors
           are othogonal to each other, the matrix created will be a rotation matrix to rotate
           the X, Y and Z axis to the given vectors. See above for an example.

VECTOR/MATRIX CONVERSION

       The following functions provide links between the "Math::VectorReal" and
       "Math::MatrixReal" packages.

       NOTE: While this package is closely related to "Math::MatrixReal", it does NOT require
       that that package to be installed unless you actually want to perform matrix operations.

       Also the overload operations will automatically handle vector/matrix mathematics (See
       below).

   Vector to Matrix Conversion
       vector2matrix_row( [CLASS] )
       vector2matrix_col( [CLASS] )
           Convert "Math::VectorReal" objects to a "Math::MatrixReal" objects.  Optional argument
           defines the object class to be returned (defaults to "Math::MatrixReal").

           Note that as a "Math::VectorReal" is internally equivelent to a "Math::MatrixReal" row
           matrix, "vector2matrix_row" is essentually just a bless operation, which is NOT
           required to use with "Math::MatrixReal" functions.

           The "vector2matrix_col" performs the required transpose to convert the
           "Math::VectorReal" object into a "Math::MatrixReal" version of a vector (a column
           matrix).

   Matrix to Vector Conversion
       matrix_row2vector( [ROW] )
       matrix_col2vector( [COLUMN] )
           When referred to by a "Math::MatrixReal" object, extracts the vector from the matrix.
           the optional argument defines which row or column of the matrix is to be extracted as
           a "Math::VectorReal" vector.

OPERATOR OVERLOADING

       Overload operations are provided to perform the usual string conversion, addition,
       subtraction, unary minus, scalar multiplation & division.  On top of this however the
       multiply have been expanded to look for and execute "MatrixReal" multiplation.

       The Main purpose of this package however was to provide the special vector product
       operations: dot product "." and cross product "x".  In perl these operations are normally
       used for string operations, but if either argument is a "VectorReal" object, the operation
       will attempt the approprate vector math operation instead.

       Note however that if one side of the dot "." operator is already a string, then the vector
       will be converted to a sting and a string concatantion will be performed. The cross
       operator "x" will just croak() as it is non-sensical to either repeat the string
       conversion of a vector, OR to repeat a string, vector, times!

       Overloaded operator summery...
           neg     unary minus - multiply vector by -1
            ""     automatic string conversion using stringify() function
             +     vector addition
             -     vector subtraction
             /     scalar division (left argument must be the vector)
             *     scalar multiplication OR MatrixReal multiplication
             x     vector/cross product of two vectors
             .     dot product of two vectors OR vector/string concatanation

       Possible future addition   '~'  to transpose a "VectorReal" into a "MatrixReal" column
       vector (as per that operator on "MatrixReal" objects).  It was not added as it just did
       not seem to be needed.

SEE ALSO

       The "Math::MatrixReal" CPAN Module by   Steffen Beyer and the "Math::MatrixReal-Ext1" CPAN
       extension by  Mike South

AUTHOR

       Anthony Thyssen <anthony@cit.gu.edu.au>

COPYRIGHT

       Copyright (c) 2001 Anthony Thyssen. All rights reserved. This program is free software;
       you can redistribute it and/or modify it under the same terms as Perl itself. I would
       appreciate any suggestions however.