1Math::Vec(3pm) User Contributed Perl Documentation Math::Vec(3pm)
2
6 Math::Vec - Object-Oriented Vector Math Methods in Perl
7
9 use Math::Vec;
10 $v = Math::Vec->new(0,1,2);
11 or
13 use Math::Vec qw(NewVec);
15 $v = NewVec(0,1,2);
16 @res = $v->Cross([1,2.5,0]);
17 $p = NewVec(@res);
18 $q = $p->Dot([0,1,0]);
19 or
21 use Math::Vec qw(:terse);
23 $v = V(0,1,2);
24 $q = ($v x [1,2.5,0]) * [0,1,0];
25
27 This module is still somewhat incomplete. If a function does nothing,
28 there is likely a really good reason. Please have a look at the code
29 if you are trying to use this in a production environment.
30
32 Eric L. Wilhelm <ewilhelm at cpan dot org>
33 http://scratchcomputing.com
35
37 This module was adapted from Math::Vector, written by Wayne M.
38 Syvinski.
39 It uses most of the same algorithms, and currently preserves the same
41 names as the original functions, though some aliases have been added to
42 make the interface more natural (at least to the way I think.)
43 The "object" for the object oriented calling style is a blessed array
45 reference which contains a vector of the form [x,y,z]. Methods will
46 typically return a list.
47
49 Copyright (C) 2003-2006 Eric Wilhelm
50 portions Copyright 2003 Wayne M. Syvinski
52
54 Absolutely, positively NO WARRANTY, neither express or implied, is
55 offered with this software. You use this software at your own risk.
56 In case of loss, neither Wayne M. Syvinski, Eric Wilhelm, nor anyone
57 else, owes you anything whatseover. You have been warned.
58 Note that this includes NO GUARANTEE of MATHEMATICAL CORRECTNESS. If
60 you are going to use this code in a production environment, it is YOUR
61 RESPONSIBILITY to verify that the methods return the correct values.
62
64 You may use this software under one of the following licenses:
65 (1) GNU General Public License
67 (found at http://www.gnu.org/copyleft/gpl.html)
68 (2) Artistic License
69 (found at http://www.perl.com/pub/language/misc/Artistic.html)
70
72 Math::Vector
73
75 new
76 Returns a blessed array reference to cartesian point ($x, $y, $z),
77 where $z is optional. Note the feed-me-list, get-back-reference syntax
78 here. This is the opposite of the rest of the methods for a good
79 reason (it allows nesting of function calls.)
80 The z value is optional, (and so are x and y.) Undefined values are
82 silently translated into zeros upon construction.
83 $vec = Math::Vec->new($x, $y, $z);
85 NewVec
87 This is simply a shortcut to Math::Vec->new($x, $y, $z) for those of
88 you who don't want to type so much so often. This also makes it easier
89 to nest / chain your function calls. Note that methods will typically
90 output lists (e.g. the answer to your question.) While you can simply
91 [bracket] the answer to make an array reference, you need that to be
92 blessed in order to use the $object->method(@args) syntax. This
93 function does that blessing.
94 This function is exported as an option. To use it, simply use
96 Math::Vec qw(NewVec); at the start of your code.
97 use Math::Vec qw(NewVec);
99 $vec = NewVec($x, $y, $z);
100 $diff = NewVec($vec->Minus([$ovec->ScalarMult(0.5)]));
101
103 These are all one-letter shortcuts which are imported to your namespace
104 with the :terse flag.
105 use Math::Vec qw(:terse);
107 V
109 This is the same as Math::Vec->new($x,$y,$z).
110 $vec = V($x, $y, $z);
112 U
114 Shortcut to V($x,$y,$z)->UnitVector()
115 $unit = U($x, $y, $z);
117 This will also work if called with a vector object:
119 $unit = U($vector);
121 X
123 Returns an x-axis unit vector.
124 $xvec = X();
126 Y
128 Returns a y-axis unit vector.
129 $yvec = Y();
131 Z
133 Returns a z-axis unit vector.
134 $zvec = Z();
136
138 Best used with the :terse functions, the Overloading scheme introduces
139 an interface which is unique from the Methods interface. Where the
140 methods take references and return lists, the overloaded operators will
141 return references. This allows vector arithmetic to be chained
142 together more easily. Of course, you can easily dereference these with
143 @{$vec}.
144 The following sections contain equivelant expressions from the longhand
146 and terse interfaces, respectively.
147 Negation:
149 @a = NewVec->(0,1,1)->ScalarMult(-1);
150 @a = @{-V(0,1,1)};
151 Stringification:
153 This also performs concatenation and other string operations.
154 print join(", ", 0,1,1), "\n";
156 print V(0,1,1), "\n";
158 $v = V(0,1,1);
160 print "$v\n";
161 print "$v" . "\n";
162 print $v, "\n";
163 Addition:
165 @a = NewVec(0,1,1)->Plus([2,2]);
166 @a = @{V(0,1,1) + V(2,2)};
168 # only one argument needs to be blessed:
170 @a = @{V(0,1,1) + [2,2]};
171 # and which one is blessed doesn't matter:
173 @a = @{[0,1,1] + V(2,2)};
174 Subtraction:
176 @a = NewVec(0,1,1)->Minus([2,2]);
177 @a = @{[0,1,1] - V(2,2)};
179 Scalar Multiplication:
181 @a = NewVec(0,1,1)->ScalarMult(2);
182 @a = @{V(0,1,1) * 2};
184 @a = @{2 * V(0,1,1)};
186 Scalar Division:
188 @a = NewVec(0,1,1)->ScalarMult(1/2);
189 # order matters!
191 @a = @{V(0,1,1) / 2};
192 Cross Product:
194 @a = NewVec(0,1,1)->Cross([0,1]);
195 @a = @{V(0,1,1) x [0,1]};
197 @a = @{[0,1,1] x V(0,1)};
199 Dot Product:
201 Also known as the "Scalar Product".
202 $a = NewVec(0,1,1)->Dot([0,1]);
204 $a = V(0,1,1) * [0,1];
206 Note: Not using the '.' operator here makes everything more efficient.
208 I know, the * is not a dot, but at least it's a mathematical operator
209 (perl does some implied string concatenation somewhere which drove me
210 to avoid the dot.)
211 Comparison:
213 The == and != operators will compare vectors for equal direction and
214 magnitude. No attempt is made to apply tolerance to this equality.
215 Length:
217 $a = NewVec(0,1,1)->Length();
218 $a = abs(V(0,1,1));
220 Vector Projection:
222 This one is a little different. Where the method is written
223 $a->Proj($b) to give the projection of $b onto $a, this reads like you
224 would say it (b projected onto a): $b>>$a.
225 @a = NewVec(0,1,1)->Proj([0,0,1]);
227 @a = @{V(0,0,1)>>[0,1,1]};
229
231 The above examples simply show how to go from the method interface to
232 the overloaded interface, but where the overloading really shines is in
233 chaining multiple operations together. Because the return values from
234 the overloaded operators are all references, you dereference them only
235 when you are done.
236 Unit Vector left of a line
238 This comes from the CAD::Calc::line_to_rectangle() function.
239 use Math::Vec qw(:terse);
241 @line = ([0,1],[1,0]);
242 my ($a, $b) = map({V(@$_)} @line);
243 $unit = U($b - $a);
244 $left = $unit x -Z();
245 Length of a cross product
247 $length = abs($va x $vb);
248 Vectors as coordinate axes
250 This is useful in drawing eliptical arcs using dxf data.
251 $val = 3.14159; # the 'start parameter'
253 @c = (14.15973317961194, 6.29684276451746); # codes 10, 20, 30
254 @e = (6.146127847120538, 0); # codes 11, 21, 31
255 @ep = @{V(@c) + \@e}; # that's the axis endpoint
256 $ux = U(@e); # unit on our x' axis
257 $uy = U($ux x -Z()); # y' is left of x'
258 $center = V(@c);
259 # autodesk gives you this:
260 @pt = ($a * cos($val), $b * sin($val));
261 # but they don't tell you about the major/minor axis issue:
262 @pt = @{$center + $ux * $pt[0] + $uy * $pt[1]};;
263
265 The operator precedence is going to be whatever perl wants it to be. I
266 have not yet investigated this to see if it matches standard vector
267 arithmetic notation. If in doubt, use parentheses.
268 One item of note here is that the 'x' and '*' operators have the same
270 precedence, so the leftmost wins. In the following example, you can
271 get away without parentheses if you have the cross-product first.
272 # dot product of a cross product:
274 $v1 x $v2 * $v3
275 ($v1 x $v2) * $v3
276 # scalar crossed with a vector (illegal!)
278 $v3 * $v1 x $v2
279
281 The typical theme is that methods require array references and return
282 lists. This means that you can choose whether to create an anonymous
283 array ref for use in feeding back into another function call, or you
284 can simply use the list as-is. Methods which return a scalar or list
285 of scalars (in the mathematical sense, not the Perl SV sense) are
286 exempt from this theme, but methods which return what could become one
287 vector will return it as a list.
288 If you want to chain calls together, either use the NewVec constructor,
290 or enclose the call in square brackets to make an anonymous array out
291 of the result.
292 my $vec = NewVec(@pt);
294 my $doubled = NewVec($vec->ScalarMult(0.5));
295 my $other = NewVec($vec->Plus([0,2,1], [4,2,3]));
296 my @result = $other->Minus($doubled);
297 $unit = NewVec(NewVec(@result)->UnitVector());
298 The vector objects are simply blessed array references. This makes for
300 a fairly limited amount of manipulation, but vector math is not
301 complicated stuff. Hopefully, you can save at least two lines of code
302 per calculation using this module.
303 Dot
305 Returns the dot product of $vec 'dot' $othervec.
306 $vec->Dot($othervec);
308 DotProduct
310 Alias to Dot()
311 $number = $vec->DotProduct($othervec);
313 Cross
315 Returns $vec x $other_vec
316 @list = $vec->Cross($other_vec);
318 # or, to use the result as a vec:
319 $cvec = NewVec($vec->Cross($other_vec));
320 CrossProduct
322 Alias to Cross() (should really strip out all of this clunkiness and go
323 to operator overloading, but that gets into other hairiness.)
324 $vec->CrossProduct();
326 Length
328 Returns the length of $vec
329 $length = $vec->Length();
331 Magnitude
333 $vec->Magnitude();
334 UnitVector
336 $vec->UnitVector();
337 ScalarMult
339 Factors each element of $vec by $factor.
340 @new = $vec->ScalarMult($factor);
342 Minus
344 Subtracts an arbitrary number of vectors.
345 @result = $vec->Minus($other_vec, $another_vec?);
347 This would be equivelant to:
349 @result = $vec->Minus([$other_vec->Plus(@list_of_vectors)]);
351 VecSub
353 Alias to Minus()
354 $vec->VecSub();
356 InnerAngle
358 Returns the acute angle (in radians) in the plane defined by the two
359 vectors.
360 $vec->InnerAngle($other_vec);
362 DirAngles
364 $vec->DirAngles();
365 Plus
367 Adds an arbitrary number of vectors.
368 @result = $vec->Plus($other_vec, $another_vec);
370 PlanarAngles
372 If called in list context, returns the angle of the vector in each of
373 the primary planes. If called in scalar context, returns only the
374 angle in the xy plane. Angles are returned in radians counter-
375 clockwise from the primary axis (the one listed first in the pairs
376 below.)
377 ($xy_ang, $xz_ang, $yz_ang) = $vec->PlanarAngles();
379 Ang
381 A simpler alias to PlanarAngles() which eliminates the concerns about
382 context and simply returns the angle in the xy plane.
383 $xy_ang = $vec->Ang();
385 VecAdd
387 $vec->VecAdd();
388 UnitVectorPoints
390 Returns a unit vector which points from $A to $B.
391 $A->UnitVectorPoints($B);
393 InnerAnglePoints
395 Returns the InnerAngle() between the three points. $Vert is the vertex
396 of the points.
397 $Vert->InnerAnglePoints($endA, $endB);
399 PlaneUnitNormal
401 Returns a unit vector normal to the plane described by the three
402 points. The sense of this vector is according to the right-hand rule
403 and the order of the given points. The $Vert vector is taken as the
404 vertex of the three points. e.g. if $Vert is the origin of a
405 coordinate system where the x-axis is $A and the y-axis is $B, then the
406 return value would be a unit vector along the positive z-axis.
407 $Vert->PlaneUnitNormal($A, $B);
409 TriAreaPoints
411 Returns the angle of the triangle formed by the three points.
412 $A->TriAreaPoints($B, $C);
414 Comp
416 Returns the scalar projection of $B onto $A (also called the component
417 of $B along $A.)
418 $A->Comp($B);
420 Proj
422 Returns the vector projection of $B onto $A.
423 $A->Proj($B);
425 PerpFoot
427 Returns a point on line $A,$B which is as close to $pt as possible (and
428 therefore perpendicular to the line.)
429 $pt->PerpFoot($A, $B);
431
433 The following have yet to be translated into this interface. They are
434 shown here simply because I intended to fully preserve the function
435 names from the original Math::Vector module written by Wayne M.
436 Syvinski.
437 TripleProduct
439 $vec->TripleProduct();
440 IJK
442 $vec->IJK();
443 OrdTrip
445 $vec->OrdTrip();
446 STV
448 $vec->STV();
449 Equil
451 $vec->Equil();
452perl v5.38.0 2023-07-20 Math::Vec(3pm)