# FreeBSD Manual Pages

```VectorReal(3)	      User Contributed Perl Documentation	 VectorReal(3)

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

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!

neg	   unary minus - multiply vector by -1
""	   automatic string conversion using stringify() function
-	   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.

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>

is free software; you can redistribute it and/or	modify it under	the
same terms as Perl itself. I would appreciate any suggestions however.

POD ERRORS
Hey! The	above document had some	coding errors, which are explained
below:

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'

perl v5.32.0			  2002-08-19			 VectorReal(3)
```