mingw/html/lib/Math/Trig.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Math::Trig - trigonometric functions</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Math::Trig - trigonometric functions</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#trigonometric_functions">TRIGONOMETRIC FUNCTIONS</a></li>
  26         <ul>
  27
  28                 <li><a href="#errors_due_to_division_by_zero">ERRORS DUE TO DIVISION BY ZERO</a></li>
  29                 <li><a href="#simple__real__arguments__complex_results">SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS</a></li>
  30         </ul>
  31
  32         <li><a href="#plane_angle_conversions">PLANE ANGLE CONVERSIONS</a></li>
  33         <li><a href="#radial_coordinate_conversions">RADIAL COORDINATE CONVERSIONS</a></li>
  34         <ul>
  35
  36                 <li><a href="#coordinate_systems">COORDINATE SYSTEMS</a></li>
  37                 <li><a href="#3d_angle_conversions">3-D ANGLE CONVERSIONS</a></li>
  38         </ul>
  39
  40         <li><a href="#great_circle_distances_and_directions">GREAT CIRCLE DISTANCES AND DIRECTIONS</a></li>
  41         <li><a href="#examples">EXAMPLES</a></li>
  42         <ul>
  43
  44                 <li><a href="#caveat_for_great_circle_formulas">CAVEAT FOR GREAT CIRCLE FORMULAS</a></li>
  45         </ul>
  46
  47         <li><a href="#bugs">BUGS</a></li>
  48         <li><a href="#authors">AUTHORS</a></li>
  49 </ul>
  50 <!-- INDEX END -->
  51
  52 <hr />
  53 <p>
  54 </p>
  55 <h1><a name="name">NAME</a></h1>
  56 <p>Math::Trig - trigonometric functions</p>
  57 <p>
  58 </p>
  59 <hr />
  60 <h1><a name="synopsis">SYNOPSIS</a></h1>
  61 <pre>
  62         use Math::Trig;</pre>
  63 <pre>
  64         $x = tan(0.9);
  65         $y = acos(3.7);
  66         $z = asin(2.4);</pre>
  67 <pre>
  68         $halfpi = pi/2;</pre>
  69 <pre>
  70         $rad = deg2rad(120);</pre>
  71 <pre>
  72         # Import constants pi2, pip2, pip4 (2*pi, pi/2, pi/4).
  73         use Math::Trig ':pi';</pre>
  74 <pre>
  75         # Import the conversions between cartesian/spherical/cylindrical.
  76         use Math::Trig ':radial';</pre>
  77 <pre>
  78         # Import the great circle formulas.
  79         use Math::Trig ':great_circle';</pre>
  80 <p>
  81 </p>
  82 <hr />
  83 <h1><a name="description">DESCRIPTION</a></h1>
  84 <p><code>Math::Trig</code> defines many trigonometric functions not defined by the
  85 core Perl which defines only the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_sin"><code>sin()</code></a> and <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_cos"><code>cos()</code></a>.  The constant
  86 <strong>pi</strong> is also defined as are a few convenience functions for angle
  87 conversions, and <em>great circle formulas</em> for spherical movement.</p>
  88 <p>
  89 </p>
  90 <hr />
  91 <h1><a name="trigonometric_functions">TRIGONOMETRIC FUNCTIONS</a></h1>
  92 <p>The tangent</p>
  93 <dl>
  94 <dt><strong><a name="item_tan"><strong>tan</strong></a></strong>
  95
  96 </dl>
  97 <p>The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
  98 are aliases)</p>
  99 <p><strong>csc</strong>, <strong>cosec</strong>, <strong>sec</strong>, <strong>sec</strong>, <strong>cot</strong>, <strong>cotan</strong></p>
 100 <p>The arcus (also known as the inverse) functions of the sine, cosine,
 101 and tangent</p>
 102 <p><strong>asin</strong>, <strong>acos</strong>, <strong>atan</strong></p>
 103 <p>The principal value of the arc tangent of y/x</p>
 104 <p><strong>atan2</strong>(y, x)</p>
 105 <p>The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
 106 and acotan/acot are aliases)</p>
 107 <p><strong>acsc</strong>, <strong>acosec</strong>, <strong>asec</strong>, <strong>acot</strong>, <strong>acotan</strong></p>
 108 <p>The hyperbolic sine, cosine, and tangent</p>
 109 <p><strong>sinh</strong>, <strong>cosh</strong>, <strong>tanh</strong></p>
 110 <p>The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
 111 and cotanh/coth are aliases)</p>
 112 <p><strong>csch</strong>, <strong>cosech</strong>, <strong>sech</strong>, <strong>coth</strong>, <strong>cotanh</strong></p>
 113 <p>The arcus (also known as the inverse) functions of the hyperbolic
 114 sine, cosine, and tangent</p>
 115 <p><strong>asinh</strong>, <strong>acosh</strong>, <strong>atanh</strong></p>
 116 <p>The arcus cofunctions of the hyperbolic sine, cosine, and tangent
 117 (acsch/acosech and acoth/acotanh are aliases)</p>
 118 <p><strong>acsch</strong>, <strong>acosech</strong>, <strong>asech</strong>, <strong>acoth</strong>, <strong>acotanh</strong></p>
 119 <p>The trigonometric constant <strong>pi</strong> is also defined.</p>
 120 <p>$pi2 = 2 * <strong>pi</strong>;</p>
 121 <p>
 122 </p>
 123 <h2><a name="errors_due_to_division_by_zero">ERRORS DUE TO DIVISION BY ZERO</a></h2>
 124 <p>The following functions</p>
 125 <pre>
 126         acoth
 127         acsc
 128         acsch
 129         asec
 130         asech
 131         atanh
 132         cot
 133         coth
 134         csc
 135         csch
 136         sec
 137         sech
 138         tan
 139         tanh</pre>
 140 <p>cannot be computed for all arguments because that would mean dividing
 141 by zero or taking logarithm of zero. These situations cause fatal
 142 runtime errors looking like this</p>
 143 <pre>
 144         cot(0): Division by zero.
 145         (Because in the definition of cot(0), the divisor sin(0) is 0)
 146         Died at ...</pre>
 147 <p>or</p>
 148 <pre>
 149         atanh(-1): Logarithm of zero.
 150         Died at...</pre>
 151 <p>For the <code>csc</code>, <code>cot</code>, <code>asec</code>, <code>acsc</code>, <code>acot</code>, <code>csch</code>, <code>coth</code>,
 152 <code>asech</code>, <code>acsch</code>, the argument cannot be <code>0</code> (zero).  For the
 153 <code>atanh</code>, <code>acoth</code>, the argument cannot be <code>1</code> (one).  For the
 154 <code>atanh</code>, <code>acoth</code>, the argument cannot be <code>-1</code> (minus one).  For the
 155 <a href="#item_tan"><code>tan</code></a>, <code>sec</code>, <code>tanh</code>, <code>sech</code>, the argument cannot be <em>pi/2 + k *
 156 pi</em>, where <em>k</em> is any integer.  atan2(0, 0) is undefined.</p>
 157 <p>
 158 </p>
 159 <h2><a name="simple__real__arguments__complex_results">SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS</a></h2>
 160 <p>Please note that some of the trigonometric functions can break out
 161 from the <strong>real axis</strong> into the <strong>complex plane</strong>. For example
 162 <code>asin(2)</code> has no definition for plain real numbers but it has
 163 definition for complex numbers.</p>
 164 <p>In Perl terms this means that supplying the usual Perl numbers (also
 165 known as scalars, please see <a href="file://C|\msysgit\mingw\html/pod/perldata.html">the perldata manpage</a>) as input for the
 166 trigonometric functions might produce as output results that no more
 167 are simple real numbers: instead they are complex numbers.</p>
 168 <p>The <code>Math::Trig</code> handles this by using the <code>Math::Complex</code> package
 169 which knows how to handle complex numbers, please see <a href="file://C|\msysgit\mingw\html/lib/Math/Complex.html">the Math::Complex manpage</a>
 170 for more information. In practice you need not to worry about getting
 171 complex numbers as results because the <code>Math::Complex</code> takes care of
 172 details like for example how to display complex numbers. For example:</p>
 173 <pre>
 174         print asin(2), &quot;\n&quot;;</pre>
 175 <p>should produce something like this (take or leave few last decimals):</p>
 176 <pre>
 177         1.5707963267949-1.31695789692482i</pre>
 178 <p>That is, a complex number with the real part of approximately <code>1.571</code>
 179 and the imaginary part of approximately <code>-1.317</code>.</p>
 180 <p>
 181 </p>
 182 <hr />
 183 <h1><a name="plane_angle_conversions">PLANE ANGLE CONVERSIONS</a></h1>
 184 <p>(Plane, 2-dimensional) angles may be converted with the following functions.</p>
 185 <pre>
 186         $radians  = deg2rad($degrees);
 187         $radians  = grad2rad($gradians);</pre>
 188 <pre>
 189         $degrees  = rad2deg($radians);
 190         $degrees  = grad2deg($gradians);</pre>
 191 <pre>
 192         $gradians = deg2grad($degrees);
 193         $gradians = rad2grad($radians);</pre>
 194 <p>The full circle is 2 <em>pi</em> radians or <em>360</em> degrees or <em>400</em> gradians.
 195 The result is by default wrapped to be inside the [0, {2pi,360,400}[ circle.
 196 If you don't want this, supply a true second argument:</p>
 197 <pre>
 198         $zillions_of_radians  = deg2rad($zillions_of_degrees, 1);
 199         $negative_degrees     = rad2deg($negative_radians, 1);</pre>
 200 <p>You can also do the wrapping explicitly by rad2rad(), deg2deg(), and
 201 grad2grad().</p>
 202 <p>
 203 </p>
 204 <hr />
 205 <h1><a name="radial_coordinate_conversions">RADIAL COORDINATE CONVERSIONS</a></h1>
 206 <p><strong>Radial coordinate systems</strong> are the <strong>spherical</strong> and the <strong>cylindrical</strong>
 207 systems, explained shortly in more detail.</p>
 208 <p>You can import radial coordinate conversion functions by using the
 209 <code>:radial</code> tag:</p>
 210 <pre>
 211     use Math::Trig ':radial';</pre>
 212 <pre>
 213     ($rho, $theta, $z)     = cartesian_to_cylindrical($x, $y, $z);
 214     ($rho, $theta, $phi)   = cartesian_to_spherical($x, $y, $z);
 215     ($x, $y, $z)           = cylindrical_to_cartesian($rho, $theta, $z);
 216     ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
 217     ($x, $y, $z)           = spherical_to_cartesian($rho, $theta, $phi);
 218     ($rho_c, $theta, $z)   = spherical_to_cylindrical($rho_s, $theta, $phi);</pre>
 219 <p><strong>All angles are in radians</strong>.</p>
 220 <p>
 221 </p>
 222 <h2><a name="coordinate_systems">COORDINATE SYSTEMS</a></h2>
 223 <p><strong>Cartesian</strong> coordinates are the usual rectangular <em>(x, y, z)</em>-coordinates.</p>
 224 <p>Spherical coordinates, <em>(rho, theta, pi)</em>, are three-dimensional
 225 coordinates which define a point in three-dimensional space.  They are
 226 based on a sphere surface.  The radius of the sphere is <strong>rho</strong>, also
 227 known as the <em>radial</em> coordinate.  The angle in the <em>xy</em>-plane
 228 (around the <em>z</em>-axis) is <strong>theta</strong>, also known as the <em>azimuthal</em>
 229 coordinate.  The angle from the <em>z</em>-axis is <strong>phi</strong>, also known as the
 230 <em>polar</em> coordinate.  The North Pole is therefore <em>0, 0, rho</em>, and
 231 the Gulf of Guinea (think of the missing big chunk of Africa) <em>0,
 232 pi/2, rho</em>.  In geographical terms <em>phi</em> is latitude (northward
 233 positive, southward negative) and <em>theta</em> is longitude (eastward
 234 positive, westward negative).</p>
 235 <p><strong>BEWARE</strong>: some texts define <em>theta</em> and <em>phi</em> the other way round,
 236 some texts define the <em>phi</em> to start from the horizontal plane, some
 237 texts use <em>r</em> in place of <em>rho</em>.</p>
 238 <p>Cylindrical coordinates, <em>(rho, theta, z)</em>, are three-dimensional
 239 coordinates which define a point in three-dimensional space.  They are
 240 based on a cylinder surface.  The radius of the cylinder is <strong>rho</strong>,
 241 also known as the <em>radial</em> coordinate.  The angle in the <em>xy</em>-plane
 242 (around the <em>z</em>-axis) is <strong>theta</strong>, also known as the <em>azimuthal</em>
 243 coordinate.  The third coordinate is the <em>z</em>, pointing up from the
 244 <strong>theta</strong>-plane.</p>
 245 <p>
 246 </p>
 247 <h2><a name="3d_angle_conversions">3-D ANGLE CONVERSIONS</a></h2>
 248 <p>Conversions to and from spherical and cylindrical coordinates are
 249 available.  Please notice that the conversions are not necessarily
 250 reversible because of the equalities like <em>pi</em> angles being equal to
 251 <em>-pi</em> angles.</p>
 252 <dl>
 253 <dt><strong><a name="item_cartesian_to_cylindrical">cartesian_to_cylindrical</a></strong>
 254
 255 <dd>
 256 <pre>
 257         ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);</pre>
 258 </dd>
 259 <dt><strong><a name="item_cartesian_to_spherical">cartesian_to_spherical</a></strong>
 260
 261 <dd>
 262 <pre>
 263         ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);</pre>
 264 </dd>
 265 <dt><strong><a name="item_cylindrical_to_cartesian">cylindrical_to_cartesian</a></strong>
 266
 267 <dd>
 268 <pre>
 269         ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);</pre>
 270 </dd>
 271 <dt><strong><a name="item_cylindrical_to_spherical">cylindrical_to_spherical</a></strong>
 272
 273 <dd>
 274 <pre>
 275         ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);</pre>
 276 </dd>
 277 <dd>
 278 <p>Notice that when <code>$z</code> is not 0 <code>$rho_s</code> is not equal to <code>$rho_c</code>.</p>
 279 </dd>
 280 <dt><strong><a name="item_spherical_to_cartesian">spherical_to_cartesian</a></strong>
 281
 282 <dd>
 283 <pre>
 284         ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);</pre>
 285 </dd>
 286 <dt><strong><a name="item_spherical_to_cylindrical">spherical_to_cylindrical</a></strong>
 287
 288 <dd>
 289 <pre>
 290         ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);</pre>
 291 </dd>
 292 <dd>
 293 <p>Notice that when <code>$z</code> is not 0 <code>$rho_c</code> is not equal to <code>$rho_s</code>.</p>
 294 </dd>
 295 </dl>
 296 <p>
 297 </p>
 298 <hr />
 299 <h1><a name="great_circle_distances_and_directions">GREAT CIRCLE DISTANCES AND DIRECTIONS</a></h1>
 300 <p>You can compute spherical distances, called <strong>great circle distances</strong>,
 301 by importing the <code>great_circle_distance()</code> function:</p>
 302 <pre>
 303   use Math::Trig 'great_circle_distance';</pre>
 304 <pre>
 305   $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);</pre>
 306 <p>The <em>great circle distance</em> is the shortest distance between two
 307 points on a sphere.  The distance is in <code>$rho</code> units.  The <code>$rho</code> is
 308 optional, it defaults to 1 (the unit sphere), therefore the distance
 309 defaults to radians.</p>
 310 <p>If you think geographically the <em>theta</em> are longitudes: zero at the
 311 Greenwhich meridian, eastward positive, westward negative--and the
 312 <em>phi</em> are latitudes: zero at the North Pole, northward positive,
 313 southward negative.  <strong>NOTE</strong>: this formula thinks in mathematics, not
 314 geographically: the <em>phi</em> zero is at the North Pole, not at the
 315 Equator on the west coast of Africa (Bay of Guinea).  You need to
 316 subtract your geographical coordinates from <em>pi/2</em> (also known as 90
 317 degrees).</p>
 318 <pre>
 319   $distance = great_circle_distance($lon0, pi/2 - $lat0,
 320                                     $lon1, pi/2 - $lat1, $rho);</pre>
 321 <p>The direction you must follow the great circle (also known as <em>bearing</em>)
 322 can be computed by the <code>great_circle_direction()</code> function:</p>
 323 <pre>
 324   use Math::Trig 'great_circle_direction';</pre>
 325 <pre>
 326   $direction = great_circle_direction($theta0, $phi0, $theta1, $phi1);</pre>
 327 <p>(Alias 'great_circle_bearing' is also available.)
 328 The result is in radians, zero indicating straight north, pi or -pi
 329 straight south, pi/2 straight west, and -pi/2 straight east.</p>
 330 <p>You can inversely compute the destination if you know the
 331 starting point, direction, and distance:</p>
 332 <pre>
 333   use Math::Trig 'great_circle_destination';</pre>
 334 <pre>
 335   # thetad and phid are the destination coordinates,
 336   # dird is the final direction at the destination.</pre>
 337 <pre>
 338   ($thetad, $phid, $dird) =
 339     great_circle_destination($theta, $phi, $direction, $distance);</pre>
 340 <p>or the midpoint if you know the end points:</p>
 341 <pre>
 342   use Math::Trig 'great_circle_midpoint';</pre>
 343 <pre>
 344   ($thetam, $phim) =
 345     great_circle_midpoint($theta0, $phi0, $theta1, $phi1);</pre>
 346 <p>The <code>great_circle_midpoint()</code> is just a special case of</p>
 347 <pre>
 348   use Math::Trig 'great_circle_waypoint';</pre>
 349 <pre>
 350   ($thetai, $phii) =
 351     great_circle_waypoint($theta0, $phi0, $theta1, $phi1, $way);</pre>
 352 <p>Where the $way is a value from zero ($theta0, $phi0) to one ($theta1,
 353 $phi1).  Note that antipodal points (where their distance is <em>pi</em>
 354 radians) do not have waypoints between them (they would have an an
 355 ``equator'' between them), and therefore <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned for
 356 antipodal points.  If the points are the same and the distance
 357 therefore zero and all waypoints therefore identical, the first point
 358 (either point) is returned.</p>
 359 <p>The thetas, phis, direction, and distance in the above are all in radians.</p>
 360 <p>You can import all the great circle formulas by</p>
 361 <pre>
 362   use Math::Trig ':great_circle';</pre>
 363 <p>Notice that the resulting directions might be somewhat surprising if
 364 you are looking at a flat worldmap: in such map projections the great
 365 circles quite often do not look like the shortest routes-- but for
 366 example the shortest possible routes from Europe or North America to
 367 Asia do often cross the polar regions.</p>
 368 <p>
 369 </p>
 370 <hr />
 371 <h1><a name="examples">EXAMPLES</a></h1>
 372 <p>To calculate the distance between London (51.3N 0.5W) and Tokyo
 373 (35.7N 139.8E) in kilometers:</p>
 374 <pre>
 375         use Math::Trig qw(great_circle_distance deg2rad);</pre>
 376 <pre>
 377         # Notice the 90 - latitude: phi zero is at the North Pole.
 378         sub NESW { deg2rad($_[0]), deg2rad(90 - $_[1]) }
 379         my @L = NESW( -0.5, 51.3);
 380         my @T = NESW(139.8, 35.7);
 381         my $km = great_circle_distance(@L, @T, 6378); # About 9600 km.</pre>
 382 <p>The direction you would have to go from London to Tokyo (in radians,
 383 straight north being zero, straight east being pi/2).</p>
 384 <pre>
 385         use Math::Trig qw(great_circle_direction);</pre>
 386 <pre>
 387         my $rad = great_circle_direction(@L, @T); # About 0.547 or 0.174 pi.</pre>
 388 <p>The midpoint between London and Tokyo being</p>
 389 <pre>
 390         use Math::Trig qw(great_circle_midpoint);</pre>
 391 <pre>
 392         my @M = great_circle_midpoint(@L, @T);</pre>
 393 <p>or about 68.11N 24.74E, in the Finnish Lapland.</p>
 394 <p>
 395 </p>
 396 <h2><a name="caveat_for_great_circle_formulas">CAVEAT FOR GREAT CIRCLE FORMULAS</a></h2>
 397 <p>The answers may be off by few percentages because of the irregular
 398 (slightly aspherical) form of the Earth.  The errors are at worst
 399 about 0.55%, but generally below 0.3%.</p>
 400 <p>
 401 </p>
 402 <hr />
 403 <h1><a name="bugs">BUGS</a></h1>
 404 <p>Saying <code>use Math::Trig;</code> exports many mathematical routines in the
 405 caller environment and even overrides some (<a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_sin"><code>sin</code></a>, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_cos"><code>cos</code></a>).  This is
 406 construed as a feature by the Authors, actually... ;-)</p>
 407 <p>The code is not optimized for speed, especially because we use
 408 <code>Math::Complex</code> and thus go quite near complex numbers while doing
 409 the computations even when the arguments are not. This, however,
 410 cannot be completely avoided if we want things like <code>asin(2)</code> to give
 411 an answer instead of giving a fatal runtime error.</p>
 412 <p>Do not attempt navigation using these formulas.</p>
 413 <p>
 414 </p>
 415 <hr />
 416 <h1><a name="authors">AUTHORS</a></h1>
 417 <p>Jarkko Hietaniemi &lt;<em><a href="mailto:jhi@iki.fi">jhi@iki.fi</a></em>&gt; and
 418 Raphael Manfredi &lt;<em><a href="mailto:Raphael_Manfredi@pobox.com">Raphael_Manfredi@pobox.com</a></em>&gt;.</p>
 419 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 420 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 421 <big><strong><span class="block">&nbsp;Math::Trig - trigonometric functions</span></strong></big>
 422 </td></tr>
 423 </table>
 424
 425 </body>
 426
 427 </html>