VectorReal(3pm)

💖 VectorReal(3pm) 💖

okay so bestie, this is the manual page for Math::VectorReal, straight outta the User Contributed Perl Documentation. it's a whole 3D vector math module for perl and honestly? it ate. sit down, grab a strawberry 🍓, and let's get into it.

---

🌸 NAME 🌸

Math::VectorReal — Module to handle 3D Vector Mathematics 💅

🎀 SYNOPSIS 🎀

like, here's the whole vibe in code form, every last line, no cap:

#!/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 ✨

so the Math::VectorReal package defines a 3D mathematical "vector", and it does it in a way that plays nice with the older CPAN module Math::MatrixReal. but like — it's the glow-up version, bc it hands you a way more vector-oriented set of math functions and overloaded operators than MatrixReal does. for example: the normal perl string functions x and . have been overloaded so they do vector cross product and dot product instead. which means vector math formulas in your perl programs literally just look like vector math formulas. iconic behaviour, honestly. 👑

so even though this package is compatible with Math::MatrixReal, you DO NOT need that package installed to do pure vector-oriented calculations. you do need it if you wanna do matrix operations with your vectors, tho. the interface was designed with that flexibility in mind from the jump. 🦋

the vectors are defined the same way a "row" Math::MatrixReal matrix is, rather than that package's choice of a "column" definition for vector operations. so these vectors get multiplied into matrices with the vector on the left and the matrix on the right. EG: v * M -> 'v

not only is this how the author prefers to handle vectors — it's also how most graphics books use vectors. and as a lil bonus, it means there's no overload conflicts between this package and Math::MatrixReal (the left object's overloaded operator gets called to do the math). it's also a whole lot simpler than MatrixReal's column vector methods, which were designed for equation solving and not for 3D geometry ops. different assignment, bestie. 💅

and the vector_matrix() function that comes with it? it simplifies creating a MatrixReal object out of 3 (usually orthogonal) vectors. pair that with the vector-oriented math operators and it becomes super easy to define orthogonal rotation matrices out of Math::VectorReal objects. peep a rough example up in the synopsis, or in the file matrix_test in the package's source.

⚠️ NOTE: the 6th element of the Math::MatrixReal array object is used to hold the length of the vector, so it can be reused without needing to be recalculated every single time. that means the expensive sqrt() function doesn't need to be called unless it's actually necessary. this usage should not affect direct use of these objects in the Math::MatrixReal functions. 🫶

🧚 CONSTANTS 🧚

four constant vectors are available for export (using an :all tag). and they 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 brand new vector with the values of x, y, z and get back the appropriate object. ✨
• vector(x,y,z) — same energy as new, except it's an exported function, so you don't need a package reference to create a Math::VectorReal object. convenient queen behaviour.
• clone() — returns a completely new copy of the referring Math::VectorReal object. twin, but make it a separate object.

💅 METHODS 💅

• array() — returns the x,y,z elements of the referring vector as an array of values.
• x() — returns the x element of the referring vector.
• y() — returns the y element of the referring vector.
• z() — returns the z element of the referring vector.
• stringify( [ FORMAT ] ) — returns the referring vector as a string. if you pass a FORMAT, that's used to sprintf-format the vector. this is what gets 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". and yes bestie, that includes a newline character at the end. 💀

but unlike Math::MatrixReal, you can assign a brand new default sprintf format by assigning it to the package's $FORMAT variable. for example:

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

which is a great format for outputting vectors for the POVray (Persistence of Vision Raytracer) program. 🎨

• length() — returns the length of the given vector. as a side effect, that length gets saved into the vector's object so the expensive sqrt() function doesn't have to be called again. smart, honestly.
• norm() — normalises the Vector. that means scalar-dividing the vector by its length so it becomes length one. normal vectors are commonly used to define directions without scale, or the orientation of a 3 dimensional plane. 🦋
• plane( v1, v2, v3 ) — give it three points defined counter clockwise on a plane, and it returns an array where the first element is the plane's normal unit vector, and the second is its distance from the origin along that vector. NOTE: the distance may be negative, in which case the origin is above the defined plane in 3d space.
• vector_matrix( nx, ny, nz ) — given the new location for the X, Y and Z vectors, it concatenates them together (row wise) to create a Math::MatrixReal translation matrix. for example, if the 3 vectors are orthogonal to each other, the matrix created will be a rotation matrix that rotates the X, Y and Z axes to the given vectors. see above for an example. 🔥

💜 VECTOR/MATRIX CONVERSION 💜

the functions below are the links between the Math::VectorReal and Math::MatrixReal packages. matchmaker energy, honestly.

⚠️ NOTE: while this package is closely related to Math::MatrixReal, it does NOT require that package to be installed unless you actually wanna 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] )

these convert Math::VectorReal objects into Math::MatrixReal objects. the optional argument defines the object class to be returned (and it defaults to Math::MatrixReal).

note that since a Math::VectorReal is internally equivalent to a Math::MatrixReal row matrix, vector2matrix_row is essentially just a bless operation — which is NOT required for use with Math::MatrixReal functions.

meanwhile vector2matrix_col performs the transpose required 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, these extract 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 do the usual string conversion, addition, subtraction, unary minus, scalar multiplication & division. but on top of all that, the multiply has been expanded so it looks for and executes MatrixReal multiplication too. 💅

the main purpose of this package, tho, 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 appropriate vector math operation instead. slay.

but note — if one side of the dot . operator is already a string, then the vector gets converted to a string and a string concatenation happens instead. and the cross operator x will just croak() right there, because it's non-sensical to either repeat the string conversion of a vector, OR to repeat a string, vector, times! 😭 so don't do that.

overloaded operator summary... 👑

• neg — unary minus, multiplies vector by -1
• "" — automatic string conversion using the 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 concatenation

possible future addition: '~' to transpose a VectorReal into a MatrixReal column vector (as per that operator on MatrixReal objects). it was not added because it just did not seem to be needed. no problem bestie, we respect the restraint. 🙈

🌈 SEE ALSO 🌈

the Math::MatrixReal CPAN Module by Steffen Beyer, and the Math::MatrixReal-Ext1 CPAN extension by Mike South. go show them some love. 💖

🌸 AUTHOR 🌸

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

---

👀 bestie we are NOT done — this thing keeps going, part 2 is right there 🌸

🎀 COPYRIGHT 🎀

okay bestie, legal era, but make it cute 💖

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.

so Anthony Thyssen made this in 2001, and it's still serving looks, we love that for us 👑 every single word of that copyright notice stays exactly where it is — all rights reserved, and yes that's All rights reserved, no cap.

the good news though? it's free software 🦋 which means you're literally allowed to redistribute it and/or modify it as much as your heart desires — the one vibe check being that you do it under the same terms as Perl itself. same terms, same energy, periodt 💅

and lowkey the sweetest part: he'd appreciate any suggestions 🫶 fr fr, if you've got ideas, he wants to hear them. not required, not a rule, just a genuine "pls tell me ur thoughts" moment. iconic behaviour, honestly.

---

heads up bestie: this whole page lives in the official Perl docs — it's VectorReal(3pm) from perl v5.36.0, dated 2022-10-13 💜 so if you're quoting it in the group chat, that's the era you're working with. slay, go forth, and vector responsibly ✨🌈