1Math::Vec(3pm)        User Contributed Perl Documentation       Math::Vec(3pm)
2
3
4

NAME

6       Math::Vec - Object-Oriented Vector Math Methods in Perl
7

SYNOPSIS

9         use Math::Vec;
10         $v = Math::Vec->new(0,1,2);
11
12         or
13
14         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
20         or
21
22         use Math::Vec qw(:terse);
23         $v = V(0,1,2);
24         $q = ($v x [1,2.5,0]) * [0,1,0];
25

NOTICE

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

AUTHOR

32       Eric L. Wilhelm <ewilhelm at cpan dot org>
33
34       http://scratchcomputing.com
35

DESCRIPTION

37       This module was adapted from Math::Vector, written by Wayne M.
38       Syvinski.
39
40       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
44       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
51       portions Copyright 2003 Wayne M. Syvinski
52

NO WARRANTY

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
59       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

LICENSE

64       You may use this software under one of the following licenses:
65
66         (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

SEE ALSO

72         Math::Vector
73

Constructor

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
81       The z value is optional, (and so are x and y.)  Undefined values are
82       silently translated into zeros upon construction.
83
84         $vec = Math::Vec->new($x, $y, $z);
85
86   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
95       This function is exported as an option.  To use it, simply use
96       Math::Vec qw(NewVec); at the start of your code.
97
98         use Math::Vec qw(NewVec);
99         $vec = NewVec($x, $y, $z);
100         $diff = NewVec($vec->Minus([$ovec->ScalarMult(0.5)]));
101

Terse Functions

103       These are all one-letter shortcuts which are imported to your namespace
104       with the :terse flag.
105
106         use Math::Vec qw(:terse);
107
108   V
109       This is the same as Math::Vec->new($x,$y,$z).
110
111         $vec = V($x, $y, $z);
112
113   U
114       Shortcut to V($x,$y,$z)->UnitVector()
115
116         $unit = U($x, $y, $z);
117
118       This will also work if called with a vector object:
119
120         $unit = U($vector);
121
122   X
123       Returns an x-axis unit vector.
124
125         $xvec = X();
126
127   Y
128       Returns a y-axis unit vector.
129
130         $yvec = Y();
131
132   Z
133       Returns a z-axis unit vector.
134
135         $zvec = Z();
136

Overloading

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
145       The following sections contain equivelant expressions from the longhand
146       and terse interfaces, respectively.
147
148   Negation:
149         @a = NewVec->(0,1,1)->ScalarMult(-1);
150         @a = @{-V(0,1,1)};
151
152   Stringification:
153       This also performs concatenation and other string operations.
154
155         print join(", ", 0,1,1), "\n";
156
157         print V(0,1,1), "\n";
158
159         $v = V(0,1,1);
160         print "$v\n";
161         print "$v" . "\n";
162         print $v, "\n";
163
164   Addition:
165         @a = NewVec(0,1,1)->Plus([2,2]);
166
167         @a = @{V(0,1,1) + V(2,2)};
168
169         # only one argument needs to be blessed:
170         @a = @{V(0,1,1) + [2,2]};
171
172         # and which one is blessed doesn't matter:
173         @a = @{[0,1,1] + V(2,2)};
174
175   Subtraction:
176         @a = NewVec(0,1,1)->Minus([2,2]);
177
178         @a = @{[0,1,1] - V(2,2)};
179
180   Scalar Multiplication:
181         @a = NewVec(0,1,1)->ScalarMult(2);
182
183         @a = @{V(0,1,1) * 2};
184
185         @a = @{2 * V(0,1,1)};
186
187   Scalar Division:
188         @a = NewVec(0,1,1)->ScalarMult(1/2);
189
190         # order matters!
191         @a = @{V(0,1,1) / 2};
192
193   Cross Product:
194         @a = NewVec(0,1,1)->Cross([0,1]);
195
196         @a = @{V(0,1,1) x [0,1]};
197
198         @a = @{[0,1,1] x V(0,1)};
199
200   Dot Product:
201       Also known as the "Scalar Product".
202
203         $a = NewVec(0,1,1)->Dot([0,1]);
204
205         $a = V(0,1,1) * [0,1];
206
207       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
212   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
216   Length:
217         $a = NewVec(0,1,1)->Length();
218
219         $a = abs(V(0,1,1));
220
221   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
226         @a = NewVec(0,1,1)->Proj([0,0,1]);
227
228         @a = @{V(0,0,1)>>[0,1,1]};
229

Chaining Operations

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
237   Unit Vector left of a line
238       This comes from the CAD::Calc::line_to_rectangle() function.
239
240         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
246   Length of a cross product
247         $length = abs($va x $vb);
248
249   Vectors as coordinate axes
250       This is useful in drawing eliptical arcs using dxf data.
251
252         $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

Precedence

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
269       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
273         # dot product of a cross product:
274         $v1 x $v2 * $v3
275         ($v1 x $v2) * $v3
276
277         # scalar crossed with a vector (illegal!)
278         $v3 * $v1 x $v2
279

Methods

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
289       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
293         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
299       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
304   Dot
305       Returns the dot product of $vec 'dot' $othervec.
306
307         $vec->Dot($othervec);
308
309   DotProduct
310       Alias to Dot()
311
312         $number = $vec->DotProduct($othervec);
313
314   Cross
315       Returns $vec x $other_vec
316
317         @list = $vec->Cross($other_vec);
318         # or, to use the result as a vec:
319         $cvec = NewVec($vec->Cross($other_vec));
320
321   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
325         $vec->CrossProduct();
326
327   Length
328       Returns the length of $vec
329
330         $length = $vec->Length();
331
332   Magnitude
333         $vec->Magnitude();
334
335   UnitVector
336         $vec->UnitVector();
337
338   ScalarMult
339       Factors each element of $vec by $factor.
340
341         @new = $vec->ScalarMult($factor);
342
343   Minus
344       Subtracts an arbitrary number of vectors.
345
346         @result = $vec->Minus($other_vec, $another_vec?);
347
348       This would be equivelant to:
349
350         @result = $vec->Minus([$other_vec->Plus(@list_of_vectors)]);
351
352   VecSub
353       Alias to Minus()
354
355         $vec->VecSub();
356
357   InnerAngle
358       Returns the acute angle (in radians) in the plane defined by the two
359       vectors.
360
361         $vec->InnerAngle($other_vec);
362
363   DirAngles
364         $vec->DirAngles();
365
366   Plus
367       Adds an arbitrary number of vectors.
368
369         @result = $vec->Plus($other_vec, $another_vec);
370
371   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
378         ($xy_ang, $xz_ang, $yz_ang) = $vec->PlanarAngles();
379
380   Ang
381       A simpler alias to PlanarAngles() which eliminates the concerns about
382       context and simply returns the angle in the xy plane.
383
384         $xy_ang = $vec->Ang();
385
386   VecAdd
387         $vec->VecAdd();
388
389   UnitVectorPoints
390       Returns a unit vector which points from $A to $B.
391
392         $A->UnitVectorPoints($B);
393
394   InnerAnglePoints
395       Returns the InnerAngle() between the three points.  $Vert is the vertex
396       of the points.
397
398         $Vert->InnerAnglePoints($endA, $endB);
399
400   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
408         $Vert->PlaneUnitNormal($A, $B);
409
410   TriAreaPoints
411       Returns the angle of the triangle formed by the three points.
412
413         $A->TriAreaPoints($B, $C);
414
415   Comp
416       Returns the scalar projection of $B onto $A (also called the component
417       of $B along $A.)
418
419         $A->Comp($B);
420
421   Proj
422       Returns the vector projection of $B onto $A.
423
424         $A->Proj($B);
425
426   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
430         $pt->PerpFoot($A, $B);
431

Incomplete Methods

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
438   TripleProduct
439         $vec->TripleProduct();
440
441   IJK
442         $vec->IJK();
443
444   OrdTrip
445         $vec->OrdTrip();
446
447   STV
448         $vec->STV();
449
450   Equil
451         $vec->Equil();
452
453
454
455perl v5.38.0                      2023-07-20                    Math::Vec(3pm)
Impressum