yet more multiline match cleanups (from Greg Bacon)

[p5sagit/p5-mst-13.2.git] / lib / Math / Trig.pm

diff --git a/lib/Math/Trig.pm b/lib/Math/Trig.pm
index b7b5d5d..68dcb94 100644 (file)
--- a/lib/Math/Trig.pm
+++ b/lib/Math/Trig.pm
@@ -7,13 +7,12 @@
 require Exporter;
 package Math::Trig;
 
+use 5.005_64;
 use strict;
 
 use Math::Complex qw(:trig);
 
-use vars qw($VERSION $PACKAGE
-           @ISA
-           @EXPORT @EXPORT_OK %EXPORT_TAGS);
+our($VERSION, $PACKAGE, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
 
 @ISA = qw(Exporter);
 
@@ -37,8 +36,8 @@ my @rdlcnv = qw(cartesian_to_cylindrical
 
 %EXPORT_TAGS = ('radial' => [ @rdlcnv ]);
 
-use constant pi2  => 2 * pi;
-use constant pip2 => pi / 2;
+sub pi2 () { 2 * pi }          # use constant generates warning
+sub pip2 () { pi / 2 }         # use constant generates warning
 use constant DR   => pi2/360;
 use constant RD   => 360/pi2;
 use constant DG   => 400/360;
@@ -314,9 +313,11 @@ known as the I<radial> coordinate.  The angle in the I<xy>-plane
 coordinate.  The angle from the I<z>-axis is B<phi>, also known as the
 I<polar> coordinate.  The `North Pole' is therefore I<0, 0, rho>, and
 the `Bay of Guinea' (think of the missing big chunk of Africa) I<0,
-pi/2, rho>.
+pi/2, rho>.  In geographical terms I<phi> is latitude (northward
+positive, southward negative) and I<theta> is longitude (eastward
+positive, westward negative).
 
-B<Beware>: some texts define I<theta> and I<phi> the other way round,
+B<BEWARE>: some texts define I<theta> and I<phi> the other way round,
 some texts define the I<phi> to start from the horizontal plane, some
 texts use I<r> in place of I<rho>.
 
@@ -374,13 +375,25 @@ by importing the C<great_circle_distance> function:
 
        use Math::Trig 'great_circle_distance'
 
-    $distance = great_circle_distance($theta0, $phi0, $theta1, $phi, [, $rho]);
+  $distance = great_circle_distance($theta0, $phi0, $theta1, $phi1, [, $rho]);
 
 The I<great circle distance> is the shortest distance between two
 points on a sphere.  The distance is in C<$rho> units.  The C<$rho> is
 optional, it defaults to 1 (the unit sphere), therefore the distance
 defaults to radians.
 
+If you think geographically the I<theta> are longitudes: zero at the
+Greenwhich meridian, eastward positive, westward negative--and the
+I<phi> are latitudes: zero at the North Pole, northward positive,
+southward negative.  B<NOTE>: this formula thinks in mathematics, not
+geographically: the I<phi> zero is at the North Pole, not at the
+Equator on the west coast of Africa (Bay of Guinea).  You need to
+subtract your geographical coordinates from I<pi/2> (also known as 90
+degrees).
+
+  $distance = great_circle_distance($lon0, pi/2 - $lat0,
+                                    $lon1, pi/2 - $lat1, $rho);
+
 =head1 EXAMPLES
 
 To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
@@ -394,8 +407,17 @@ To calculate the distance between London (51.3N 0.5W) and Tokyo (35.7N
 
         $km = great_circle_distance(@L, @T, 6378);
 
-The answer may be off by up to 0.3% because of the irregular (slightly
-aspherical) form of the Earth.
+The answer may be off by few percentages because of the irregular
+(slightly aspherical) form of the Earth.  The used formula
+
+       lat0 = 90 degrees - phi0
+       lat1 = 90 degrees - phi1
+       d = R * arccos(cos(lat0) * cos(lat1) * cos(lon1 - lon01) +
+                       sin(lat0) * sin(lat1))
+
+is also somewhat unreliable for small distances (for locations
+separated less than about five degrees) because it uses arc cosine
+which is rather ill-conditioned for values close to zero.
 
 =head1 BUGS
 
@@ -412,7 +434,7 @@ an answer instead of giving a fatal runtime error.
 =head1 AUTHORS
 
 Jarkko Hietaniemi <F<jhi@iki.fi>> and 
-Raphael Manfredi <F<Raphael_Manfredi@grenoble.hp.com>>.
+Raphael Manfredi <F<Raphael_Manfredi@pobox.com>>.
 
 =cut