1Math::Trig(3pm) Perl Programmers Reference Guide Math::Trig(3pm)
2
6 Math::Trig - trigonometric functions
7
9 use Math::Trig;
10 $x = tan(0.9);
12 $y = acos(3.7);
13 $z = asin(2.4);
14 $halfpi = pi/2;
16 $rad = deg2rad(120);
18 # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
20 use Math::Trig ':pi';
21 # Import the conversions between cartesian/spherical/cylindrical.
23 use Math::Trig ':radial';
24 # Import the great circle formulas.
26 use Math::Trig ':great_circle';
27
29 "Math::Trig" defines many trigonometric functions not defined by the
30 core Perl which defines only the "sin()" and "cos()". The constant pi
31 is also defined as are a few convenience functions for angle conver‐
32 sions, and great circle formulas for spherical movement.
33
35 The tangent
36 tan
38 The cofunctions of the sine, cosine, and tangent (cosec/csc and
40 cotan/cot are aliases)
41 csc, cosec, sec, sec, cot, cotan
43 The arcus (also known as the inverse) functions of the sine, cosine,
45 and tangent
46 asin, acos, atan
48 The principal value of the arc tangent of y/x
50 atan2(y, x)
52 The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc and
54 acotan/acot are aliases)
55 acsc, acosec, asec, acot, acotan
57 The hyperbolic sine, cosine, and tangent
59 sinh, cosh, tanh
61 The cofunctions of the hyperbolic sine, cosine, and tangent
63 (cosech/csch and cotanh/coth are aliases)
64 csch, cosech, sech, coth, cotanh
66 The arcus (also known as the inverse) functions of the hyperbolic sine,
68 cosine, and tangent
69 asinh, acosh, atanh
71 The arcus cofunctions of the hyperbolic sine, cosine, and tangent
73 (acsch/acosech and acoth/acotanh are aliases)
74 acsch, acosech, asech, acoth, acotanh
76 The trigonometric constant pi is also defined.
78 $pi2 = 2 * pi;
80 ERRORS DUE TO DIVISION BY ZERO
82 The following functions
84 acoth
86 acsc
87 acsch
88 asec
89 asech
90 atanh
91 cot
92 coth
93 csc
94 csch
95 sec
96 sech
97 tan
98 tanh
99 cannot be computed for all arguments because that would mean dividing
101 by zero or taking logarithm of zero. These situations cause fatal run‐
102 time errors looking like this
103 cot(0): Division by zero.
105 (Because in the definition of cot(0), the divisor sin(0) is 0)
106 Died at ...
107 or
109 atanh(-1): Logarithm of zero.
111 Died at...
112 For the "csc", "cot", "asec", "acsc", "acot", "csch", "coth", "asech",
114 "acsch", the argument cannot be 0 (zero). For the "atanh", "acoth",
115 the argument cannot be 1 (one). For the "atanh", "acoth", the argument
116 cannot be "-1" (minus one). For the "tan", "sec", "tanh", "sech", the
117 argument cannot be pi/2 + k * pi, where k is any integer. atan2(0, 0)
118 is undefined.
119 SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
121 Please note that some of the trigonometric functions can break out from
123 the real axis into the complex plane. For example asin(2) has no defi‐
124 nition for plain real numbers but it has definition for complex num‐
125 bers.
126 In Perl terms this means that supplying the usual Perl numbers (also
128 known as scalars, please see perldata) as input for the trigonometric
129 functions might produce as output results that no more are simple real
130 numbers: instead they are complex numbers.
131 The "Math::Trig" handles this by using the "Math::Complex" package
133 which knows how to handle complex numbers, please see Math::Complex for
134 more information. In practice you need not to worry about getting com‐
135 plex numbers as results because the "Math::Complex" takes care of
136 details like for example how to display complex numbers. For example:
137 print asin(2), "\n";
139 should produce something like this (take or leave few last decimals):
141 1.5707963267949-1.31695789692482i
143 That is, a complex number with the real part of approximately 1.571 and
145 the imaginary part of approximately "-1.317".
146
148 (Plane, 2-dimensional) angles may be converted with the following func‐
149 tions.
150 $radians = deg2rad($degrees);
152 $radians = grad2rad($gradians);
153 $degrees = rad2deg($radians);
155 $degrees = grad2deg($gradians);
156 $gradians = deg2grad($degrees);
158 $gradians = rad2grad($radians);
159 The full circle is 2 pi radians or 360 degrees or 400 gradians. The
161 result is by default wrapped to be inside the [0, {2pi,360,400}[ cir‐
162 cle. If you don't want this, supply a true second argument:
163 $zillions_of_radians = deg2rad($zillions_of_degrees, 1);
165 $negative_degrees = rad2deg($negative_radians, 1);
166 You can also do the wrapping explicitly by rad2rad(), deg2deg(), and
168 grad2grad().
169
171 Radial coordinate systems are the spherical and the cylindrical sys‐
172 tems, explained shortly in more detail.
173 You can import radial coordinate conversion functions by using the
175 ":radial" tag:
176 use Math::Trig ':radial';
178 ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
180 ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
181 ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
182 ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
183 ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
184 ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
185 All angles are in radians.
187 COORDINATE SYSTEMS
189 Cartesian coordinates are the usual rectangular (x, y, z)-coordinates.
191 Spherical coordinates, (rho, theta, pi), are three-dimensional coordi‐
193 nates which define a point in three-dimensional space. They are based
194 on a sphere surface. The radius of the sphere is rho, also known as
195 the radial coordinate. The angle in the xy-plane (around the z-axis)
196 is theta, also known as the azimuthal coordinate. The angle from the
197 z-axis is phi, also known as the polar coordinate. The North Pole is
198 therefore 0, 0, rho, and the Gulf of Guinea (think of the missing big
199 chunk of Africa) 0, pi/2, rho. In geographical terms phi is latitude
200 (northward positive, southward negative) and theta is longitude (east‐
201 ward positive, westward negative).
202 BEWARE: some texts define theta and phi the other way round, some texts
204 define the phi to start from the horizontal plane, some texts use r in
205 place of rho.
206 Cylindrical coordinates, (rho, theta, z), are three-dimensional coordi‐
208 nates which define a point in three-dimensional space. They are based
209 on a cylinder surface. The radius of the cylinder is rho, also known
210 as the radial coordinate. The angle in the xy-plane (around the
211 z-axis) is theta, also known as the azimuthal coordinate. The third
212 coordinate is the z, pointing up from the theta-plane.
213 3-D ANGLE CONVERSIONS
215 Conversions to and from spherical and cylindrical coordinates are
217 available. Please notice that the conversions are not necessarily
218 reversible because of the equalities like pi angles being equal to -pi
219 angles.
220 cartesian_to_cylindrical
222 ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);
223 cartesian_to_spherical
225 ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);
226 cylindrical_to_cartesian
228 ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);
229 cylindrical_to_spherical
231 ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
232 Notice that when $z is not 0 $rho_s is not equal to $rho_c.
234 spherical_to_cartesian
236 ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);
237 spherical_to_cylindrical
239 ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);
240 Notice that when $z is not 0 $rho_c is not equal to $rho_s.
242
244 You can compute spherical distances, called great circle distances, by
245 importing the great_circle_distance() function:
246 use Math::Trig 'great_circle_distance';
248 $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
250 The great circle distance is the shortest distance between two points
252 on a sphere. The distance is in $rho units. The $rho is optional, it
253 defaults to 1 (the unit sphere), therefore the distance defaults to
254 radians.
255 If you think geographically the theta are longitudes: zero at the
257 Greenwhich meridian, eastward positive, westward negative--and the phi
258 are latitudes: zero at the North Pole, northward positive, southward
259 negative. NOTE: this formula thinks in mathematics, not geographi‐
260 cally: the phi zero is at the North Pole, not at the Equator on the
261 west coast of Africa (Bay of Guinea). You need to subtract your geo‐
262 graphical coordinates from pi/2 (also known as 90 degrees).
263 $distance = great_circle_distance($lon0, pi/2 - $lat0,
265 $lon1, pi/2 - $lat1, $rho);
266 The direction you must follow the great circle (also known as bearing)
268 can be computed by the great_circle_direction() function:
269 use Math::Trig 'great_circle_direction';
271 $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);
273 (Alias 'great_circle_bearing' is also available.) The result is in
275 radians, zero indicating straight north, pi or -pi straight south, pi/2
276 straight west, and -pi/2 straight east.
277 You can inversely compute the destination if you know the starting
279 point, direction, and distance:
280 use Math::Trig 'great_circle_destination';
282 # thetad and phid are the destination coordinates,
284 # dird is the final direction at the destination.
285 ($thetad, $phid, $dird) =
287 great_circle_destination($theta, $phi, $direction, $distance);
288 or the midpoint if you know the end points:
290 use Math::Trig 'great_circle_midpoint';
292 ($thetam, $phim) =
294 great_circle_midpoint($theta0, $phi0, $theta1, $phi1);
295 The great_circle_midpoint() is just a special case of
297 use Math::Trig 'great_circle_waypoint';
299 ($thetai, $phii) =
301 great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);
302 Where the $way is a value from zero ($theta0, $phi0) to one ($theta1,
304 $phi1). Note that antipodal points (where their distance is pi radi‐
305 ans) do not have waypoints between them (they would have an an "equa‐
306 tor" between them), and therefore "undef" is returned for antipodal
307 points. If the points are the same and the distance therefore zero and
308 all waypoints therefore identical, the first point (either point) is
309 returned.
310 The thetas, phis, direction, and distance in the above are all in radi‐
312 ans.
313 You can import all the great circle formulas by
315 use Math::Trig ':great_circle';
317 Notice that the resulting directions might be somewhat surprising if
319 you are looking at a flat worldmap: in such map projections the great
320 circles quite often do not look like the shortest routes-- but for
321 example the shortest possible routes from Europe or North America to
322 Asia do often cross the polar regions.
323
325 To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
326 139.8E) in kilometers:
327 use Math::Trig qw(great_circle_distance deg2rad);
329 # Notice the 90 - latitude: phi zero is at the North Pole.
331 sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
332 my @L = NESW( -0.5, 51.3);
333 my @T = NESW(139.8, 35.7);
334 my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.
335 The direction you would have to go from London to Tokyo (in radians,
337 straight north being zero, straight east being pi/2).
338 use Math::Trig qw(great_circle_direction);
340 my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.
342 The midpoint between London and Tokyo being
344 use Math::Trig qw(great_circle_midpoint);
346 my @M = great_circle_midpoint(@L, @T);
348 or about 68.11N 24.74E, in the Finnish Lapland.
350 CAVEAT FOR GREAT CIRCLE FORMULAS
352 The answers may be off by few percentages because of the irregular
354 (slightly aspherical) form of the Earth. The errors are at worst about
355 0.55%, but generally below 0.3%.
356
358 Saying "use Math::Trig;" exports many mathematical routines in the
359 caller environment and even overrides some ("sin", "cos"). This is
360 construed as a feature by the Authors, actually... ;-)
361 The code is not optimized for speed, especially because we use
363 "Math::Complex" and thus go quite near complex numbers while doing the
364 computations even when the arguments are not. This, however, cannot be
365 completely avoided if we want things like asin(2) to give an answer
366 instead of giving a fatal runtime error.
367 Do not attempt navigation using these formulas.
369
371 Jarkko Hietaniemi <jhi@iki.fi> and Raphael Manfredi <Raphael_Man‐
372 fredi@pobox.com>.
373perl v5.8.8 2001-09-21 Math::Trig(3pm)