home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _87b75847dee73e5ea39b8d192c0b7c4d < prev    next >
Text File  |  2000-03-23  |  16KB  |  330 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Math::Trig - trigonometric functions</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Math::Trig - trigonometric functions</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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">GREAT CIRCLE DISTANCES</A></LI>
  41.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  42.     <LI><A HREF="#bugs">BUGS</A></LI>
  43.     <LI><A HREF="#authors">AUTHORS</A></LI>
  44. </UL>
  45. <!-- INDEX END -->
  46.  
  47. <HR>
  48. <P>
  49. <HR>
  50. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  51. <UL>
  52. <LI>Linux</LI>
  53. <LI>Solaris</LI>
  54. <LI>Windows</LI>
  55. </UL>
  56. <HR>
  57. <H1><A NAME="name">NAME</A></H1>
  58. <P>Math::Trig - trigonometric functions</P>
  59. <P>
  60. <HR>
  61. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  62. <PRE>
  63.         use Math::Trig;</PRE>
  64. <PRE>
  65.         $x = tan(0.9);
  66.         $y = acos(3.7);
  67.         $z = asin(2.4);</PRE>
  68. <PRE>
  69.         $halfpi = pi/2;</PRE>
  70. <PRE>
  71.         $rad = deg2rad(120);</PRE>
  72. <P>
  73. <HR>
  74. <H1><A NAME="description">DESCRIPTION</A></H1>
  75. <P><CODE>Math::Trig</CODE> defines many trigonometric functions not defined by the
  76. core Perl which defines only the <A HREF="../../lib/Pod/perlfunc.html#item_sin"><CODE>sin()</CODE></A> and <A HREF="../../lib/Pod/perlfunc.html#item_cos"><CODE>cos()</CODE></A>.  The constant
  77. <STRONG>pi</STRONG> is also defined as are a few convenience functions for angle
  78. conversions.</P>
  79. <P>
  80. <HR>
  81. <H1><A NAME="trigonometric functions">TRIGONOMETRIC FUNCTIONS</A></H1>
  82. <P>The tangent</P>
  83. <DL>
  84. <DT><STRONG><A NAME="item_tan"><STRONG>tan</STRONG></A></STRONG><BR>
  85. <DD>
  86. </DL>
  87. <P>The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
  88. are aliases)</P>
  89. <P><STRONG>csc</STRONG>, <STRONG>cosec</STRONG>, <STRONG>sec</STRONG>, <STRONG>sec</STRONG>, <STRONG>cot</STRONG>, <STRONG>cotan</STRONG></P>
  90. <P>The arcus (also known as the inverse) functions of the sine, cosine,
  91. and tangent</P>
  92. <P><STRONG>asin</STRONG>, <STRONG>acos</STRONG>, <STRONG>atan</STRONG></P>
  93. <P>The principal value of the arc tangent of y/x</P>
  94. <P><STRONG>atan2</STRONG>(y, x)</P>
  95. <P>The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
  96. and acotan/acot are aliases)</P>
  97. <P><STRONG>acsc</STRONG>, <STRONG>acosec</STRONG>, <STRONG>asec</STRONG>, <STRONG>acot</STRONG>, <STRONG>acotan</STRONG></P>
  98. <P>The hyperbolic sine, cosine, and tangent</P>
  99. <P><STRONG>sinh</STRONG>, <STRONG>cosh</STRONG>, <STRONG>tanh</STRONG></P>
  100. <P>The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
  101. and cotanh/coth are aliases)</P>
  102. <P><STRONG>csch</STRONG>, <STRONG>cosech</STRONG>, <STRONG>sech</STRONG>, <STRONG>coth</STRONG>, <STRONG>cotanh</STRONG></P>
  103. <P>The arcus (also known as the inverse) functions of the hyperbolic
  104. sine, cosine, and tangent</P>
  105. <P><STRONG>asinh</STRONG>, <STRONG>acosh</STRONG>, <STRONG>atanh</STRONG></P>
  106. <P>The arcus cofunctions of the hyperbolic sine, cosine, and tangent
  107. (acsch/acosech and acoth/acotanh are aliases)</P>
  108. <P><STRONG>acsch</STRONG>, <STRONG>acosech</STRONG>, <STRONG>asech</STRONG>, <STRONG>acoth</STRONG>, <STRONG>acotanh</STRONG></P>
  109. <P>The trigonometric constant <STRONG>pi</STRONG> is also defined.</P>
  110. <P>$pi2 = 2 * <STRONG>pi</STRONG>;</P>
  111. <P>
  112. <H2><A NAME="errors due to division by zero">ERRORS DUE TO DIVISION BY ZERO</A></H2>
  113. <P>The following functions</P>
  114. <PRE>
  115.         acoth
  116.         acsc
  117.         acsch
  118.         asec
  119.         asech
  120.         atanh
  121.         cot
  122.         coth
  123.         csc
  124.         csch
  125.         sec
  126.         sech
  127.         tan
  128.         tanh</PRE>
  129. <P>cannot be computed for all arguments because that would mean dividing
  130. by zero or taking logarithm of zero. These situations cause fatal
  131. runtime errors looking like this</P>
  132. <PRE>
  133.         cot(0): Division by zero.
  134.         (Because in the definition of cot(0), the divisor sin(0) is 0)
  135.         Died at ...</PRE>
  136. <P>or</P>
  137. <PRE>
  138.         atanh(-1): Logarithm of zero.
  139.         Died at...</PRE>
  140. <P>For the <CODE>csc</CODE>, <CODE>cot</CODE>, <CODE>asec</CODE>, <CODE>acsc</CODE>, <CODE>acot</CODE>, <CODE>csch</CODE>, <CODE>coth</CODE>,
  141. <CODE>asech</CODE>, <CODE>acsch</CODE>, the argument cannot be <CODE>0</CODE> (zero).  For the
  142. <CODE>atanh</CODE>, <CODE>acoth</CODE>, the argument cannot be <CODE>1</CODE> (one).  For the
  143. <CODE>atanh</CODE>, <CODE>acoth</CODE>, the argument cannot be <CODE>-1</CODE> (minus one).  For the
  144. <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 *
  145. pi</EM>, where <EM>k</EM> is any integer.</P>
  146. <P>
  147. <H2><A NAME="simple (real) arguments, complex results">SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS</A></H2>
  148. <P>Please note that some of the trigonometric functions can break out
  149. from the <STRONG>real axis</STRONG> into the <STRONG>complex plane</STRONG>. For example
  150. <CODE>asin(2)</CODE> has no definition for plain real numbers but it has
  151. definition for complex numbers.</P>
  152. <P>In Perl terms this means that supplying the usual Perl numbers (also
  153. known as scalars, please see <A HREF="../../lib/Pod/perldata.html">the perldata manpage</A>) as input for the
  154. trigonometric functions might produce as output results that no more
  155. are simple real numbers: instead they are complex numbers.</P>
  156. <P>The <CODE>Math::Trig</CODE> handles this by using the <CODE>Math::Complex</CODE> package
  157. which knows how to handle complex numbers, please see <A HREF="../../lib/Math/Complex.html">the Math::Complex manpage</A>
  158. for more information. In practice you need not to worry about getting
  159. complex numbers as results because the <CODE>Math::Complex</CODE> takes care of
  160. details like for example how to display complex numbers. For example:</P>
  161. <PRE>
  162.         print asin(2), "\n";</PRE>
  163. <P>should produce something like this (take or leave few last decimals):</P>
  164. <PRE>
  165.         1.5707963267949-1.31695789692482i</PRE>
  166. <P>That is, a complex number with the real part of approximately <CODE>1.571</CODE>
  167. and the imaginary part of approximately <CODE>-1.317</CODE>.</P>
  168. <P>
  169. <HR>
  170. <H1><A NAME="plane angle conversions">PLANE ANGLE CONVERSIONS</A></H1>
  171. <P>(Plane, 2-dimensional) angles may be converted with the following functions.</P>
  172. <PRE>
  173.         $radians  = deg2rad($degrees);
  174.         $radians  = grad2rad($gradians);</PRE>
  175. <PRE>
  176.         $degrees  = rad2deg($radians);
  177.         $degrees  = grad2deg($gradians);</PRE>
  178. <PRE>
  179.         $gradians = deg2grad($degrees);
  180.         $gradians = rad2grad($radians);</PRE>
  181. <P>The full circle is 2 <EM>pi</EM> radians or <EM>360</EM> degrees or <EM>400</EM> gradians.</P>
  182. <P>
  183. <HR>
  184. <H1><A NAME="radial coordinate conversions">RADIAL COORDINATE CONVERSIONS</A></H1>
  185. <P><STRONG>Radial coordinate systems</STRONG> are the <STRONG>spherical</STRONG> and the <STRONG>cylindrical</STRONG>
  186. systems, explained shortly in more detail.</P>
  187. <P>You can import radial coordinate conversion functions by using the
  188. <CODE>:radial</CODE> tag:</P>
  189. <PRE>
  190.     use Math::Trig ':radial';</PRE>
  191. <PRE>
  192.     ($rho, $theta, $z)     = cartesian_to_cylindrical($x, $y, $z);
  193.     ($rho, $theta, $phi)   = cartesian_to_spherical($x, $y, $z);
  194.     ($x, $y, $z)           = cylindrical_to_cartesian($rho, $theta, $z);
  195.     ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);
  196.     ($x, $y, $z)           = spherical_to_cartesian($rho, $theta, $phi);
  197.     ($rho_c, $theta, $z)   = spherical_to_cylindrical($rho_s, $theta, $phi);</PRE>
  198. <P><STRONG>All angles are in radians</STRONG>.</P>
  199. <P>
  200. <H2><A NAME="coordinate systems">COORDINATE SYSTEMS</A></H2>
  201. <P><STRONG>Cartesian</STRONG> coordinates are the usual rectangular <EM>(x, y,
  202. z)</EM>-coordinates.</P>
  203. <P>Spherical coordinates, <EM>(rho, theta, pi)</EM>, are three-dimensional
  204. coordinates which define a point in three-dimensional space.  They are
  205. based on a sphere surface.  The radius of the sphere is <STRONG>rho</STRONG>, also
  206. known as the <EM>radial</EM> coordinate.  The angle in the <EM>xy</EM>-plane
  207. (around the <EM>z</EM>-axis) is <STRONG>theta</STRONG>, also known as the <EM>azimuthal</EM>
  208. coordinate.  The angle from the <EM>z</EM>-axis is <STRONG>phi</STRONG>, also known as the
  209. <EM>polar</EM> coordinate.  The `North Pole' is therefore <EM>0, 0, rho</EM>, and
  210. the `Bay of Guinea' (think of the missing big chunk of Africa) <EM>0,
  211. pi/2, rho</EM>.  In geographical terms <EM>phi</EM> is latitude (northward
  212. positive, southward negative) and <EM>theta</EM> is longitude (eastward
  213. positive, westward negative).</P>
  214. <P><STRONG>BEWARE</STRONG>: some texts define <EM>theta</EM> and <EM>phi</EM> the other way round,
  215. some texts define the <EM>phi</EM> to start from the horizontal plane, some
  216. texts use <EM>r</EM> in place of <EM>rho</EM>.</P>
  217. <P>Cylindrical coordinates, <EM>(rho, theta, z)</EM>, are three-dimensional
  218. coordinates which define a point in three-dimensional space.  They are
  219. based on a cylinder surface.  The radius of the cylinder is <STRONG>rho</STRONG>,
  220. also known as the <EM>radial</EM> coordinate.  The angle in the <EM>xy</EM>-plane
  221. (around the <EM>z</EM>-axis) is <STRONG>theta</STRONG>, also known as the <EM>azimuthal</EM>
  222. coordinate.  The third coordinate is the <EM>z</EM>, pointing up from the
  223. <STRONG>theta</STRONG>-plane.</P>
  224. <P>
  225. <H2><A NAME="3d angle conversions">3-D ANGLE CONVERSIONS</A></H2>
  226. <P>Conversions to and from spherical and cylindrical coordinates are
  227. available.  Please notice that the conversions are not necessarily
  228. reversible because of the equalities like <EM>pi</EM> angles being equal to
  229. <EM>-pi</EM> angles.</P>
  230. <DL>
  231. <DT><STRONG><A NAME="item_cartesian_to_cylindrical">cartesian_to_cylindrical</A></STRONG><BR>
  232. <DD>
  233. <PRE>
  234.         ($rho, $theta, $z) = cartesian_to_cylindrical($x, $y, $z);</PRE>
  235. <DT><STRONG><A NAME="item_cartesian_to_spherical">cartesian_to_spherical</A></STRONG><BR>
  236. <DD>
  237. <PRE>
  238.         ($rho, $theta, $phi) = cartesian_to_spherical($x, $y, $z);</PRE>
  239. <DT><STRONG><A NAME="item_cylindrical_to_cartesian">cylindrical_to_cartesian</A></STRONG><BR>
  240. <DD>
  241. <PRE>
  242.         ($x, $y, $z) = cylindrical_to_cartesian($rho, $theta, $z);</PRE>
  243. <DT><STRONG><A NAME="item_cylindrical_to_spherical">cylindrical_to_spherical</A></STRONG><BR>
  244. <DD>
  245. <PRE>
  246.         ($rho_s, $theta, $phi) = cylindrical_to_spherical($rho_c, $theta, $z);</PRE>
  247. <P>Notice that when <CODE>$z</CODE> is not 0 <CODE>$rho_s</CODE> is not equal to <CODE>$rho_c</CODE>.</P>
  248. <DT><STRONG><A NAME="item_spherical_to_cartesian">spherical_to_cartesian</A></STRONG><BR>
  249. <DD>
  250. <PRE>
  251.         ($x, $y, $z) = spherical_to_cartesian($rho, $theta, $phi);</PRE>
  252. <DT><STRONG><A NAME="item_spherical_to_cylindrical">spherical_to_cylindrical</A></STRONG><BR>
  253. <DD>
  254. <PRE>
  255.         ($rho_c, $theta, $z) = spherical_to_cylindrical($rho_s, $theta, $phi);</PRE>
  256. <P>Notice that when <CODE>$z</CODE> is not 0 <CODE>$rho_c</CODE> is not equal to <CODE>$rho_s</CODE>.</P>
  257. </DL>
  258. <P>
  259. <HR>
  260. <H1><A NAME="great circle distances">GREAT CIRCLE DISTANCES</A></H1>
  261. <P>You can compute spherical distances, called <STRONG>great circle distances</STRONG>,
  262. by importing the <CODE>great_circle_distance</CODE> function:</P>
  263. <PRE>
  264.         use Math::Trig 'great_circle_distance'</PRE>
  265. <PRE>
  266.   $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);</PRE>
  267. <P>The <EM>great circle distance</EM> is the shortest distance between two
  268. points on a sphere.  The distance is in <CODE>$rho</CODE> units.  The <CODE>$rho</CODE> is
  269. optional, it defaults to 1 (the unit sphere), therefore the distance
  270. defaults to radians.</P>
  271. <P>If you think geographically the <EM>theta</EM> are longitudes: zero at the
  272. Greenwhich meridian, eastward positive, westward negative--and the
  273. <EM>phi</EM> are latitudes: zero at the North Pole, northward positive,
  274. southward negative.  <STRONG>NOTE</STRONG>: this formula thinks in mathematics, not
  275. geographically: the <EM>phi</EM> zero is at the North Pole, not at the
  276. Equator on the west coast of Africa (Bay of Guinea).  You need to
  277. subtract your geographical coordinates from <EM>pi/2</EM> (also known as 90
  278. degrees).</P>
  279. <PRE>
  280.   $distance = great_circle_distance($lon0, pi/2 - $lat0,
  281.                                     $lon1, pi/2 - $lat1, $rho);</PRE>
  282. <P>
  283. <HR>
  284. <H1><A NAME="examples">EXAMPLES</A></H1>
  285. <P>To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
  286. 139.8E) in kilometers:</P>
  287. <PRE>
  288.         use Math::Trig qw(great_circle_distance deg2rad);</PRE>
  289. <PRE>
  290.         # Notice the 90 - latitude: phi zero is at the North Pole.
  291.         @L = (deg2rad(-0.5), deg2rad(90 - 51.3));
  292.         @T = (deg2rad(139.8),deg2rad(90 - 35.7));</PRE>
  293. <PRE>
  294.         $km = great_circle_distance(@L, @T, 6378);</PRE>
  295. <P>The answer may be off by few percentages because of the irregular
  296. (slightly aspherical) form of the Earth.  The used formula</P>
  297. <PRE>
  298.         lat0 = 90 degrees - phi0
  299.         lat1 = 90 degrees - phi1
  300.         d = R * arccos(cos(lat0) * cos(lat1) * cos(lon1 - lon01) +
  301.                        sin(lat0) * sin(lat1))</PRE>
  302. <P>is also somewhat unreliable for small distances (for locations
  303. separated less than about five degrees) because it uses arc cosine
  304. which is rather ill-conditioned for values close to zero.</P>
  305. <P>
  306. <HR>
  307. <H1><A NAME="bugs">BUGS</A></H1>
  308. <P>Saying <CODE>use Math::Trig;</CODE> exports many mathematical routines in the
  309. caller environment and even overrides some (<A HREF="../../lib/Pod/perlfunc.html#item_sin"><CODE>sin</CODE></A>, <A HREF="../../lib/Pod/perlfunc.html#item_cos"><CODE>cos</CODE></A>).  This is
  310. construed as a feature by the Authors, actually... ;-)</P>
  311. <P>The code is not optimized for speed, especially because we use
  312. <CODE>Math::Complex</CODE> and thus go quite near complex numbers while doing
  313. the computations even when the arguments are not. This, however,
  314. cannot be completely avoided if we want things like <CODE>asin(2)</CODE> to give
  315. an answer instead of giving a fatal runtime error.</P>
  316. <P>
  317. <HR>
  318. <H1><A NAME="authors">AUTHORS</A></H1>
  319. <P>Jarkko Hietaniemi <<EM><A HREF="mailto:jhi@iki.fi">jhi@iki.fi</A></EM>> and 
  320. Raphael Manfredi <<EM><A HREF="mailto:Raphael_Manfredi@pobox.com">Raphael_Manfredi@pobox.com</A></EM>>.</P>
  321. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  322. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  323. <STRONG><P CLASS=block> Math::Trig - trigonometric functions</P></STRONG>
  324. </TD></TR>
  325. </TABLE>
  326.  
  327. </BODY>
  328.  
  329. </HTML>
  330.