Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.

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

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

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.24.1			  2002-08-19			 VectorReal(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTANTS | CONSTRUCTORS | METHODS | VECTOR/MATRIX CONVERSION | OPERATOR OVERLOADING | SEE ALSO | AUTHOR | COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Math::VectorReal&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help