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 anticlockwise 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 reused without needing to be recalculated 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 aMath::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 (Persistance 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 aMath::MatrixReal
objects. Optional argument defines the object class to be returned (defaults toMath::MatrixReal
).Note that as a
Math::VectorReal
is internally equivelent to aMath::MatrixReal
row matrix,vector2matrix_row
is essentually just a bless operation, which is NOT required to use withMath::MatrixReal
functions.The
vector2matrix_col
performs the required transpose to convert theMath::VectorReal
object into aMath::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 aMath::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 nonsensical 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
Posible 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::MatrixRealExt1
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.
4 POD Errors
The following errors were encountered while parsing the POD:
 Around line 198:
You forgot a '=back' before '=head1'
 Around line 200:
'=item' outside of any '=over'
 Around line 372:
You forgot a '=back' before '=head2'
 Around line 374:
'=item' outside of any '=over'