Coords - geographic coordinate functionality in Perl
# be smart
use strict;
# import required symbols
use Coords qw(:tag func $scalar);
# your code goes here
Coords is a Perl module that provides some basic functionality for geographic applications, such as conversion between geographic coordinates and carthesian space, and some more.
Coords defines the following constants. Since use strict; limits the way in which barewords can be used, it is probably best to get
used to appending ()
to the constant identifiers, as is done here.
The Earth's radius in meters.
Coords defines the following variables.
The flag that indicates whether verbose messages should be printed. It can be directly modified, but the module also provides the &verbose() subroutine. Verbose mode is on by default. This variable is not exported, and can only be called through a full package reference.
A flag that controls the range of allowed longitudes in return values. When TRUE, longitudes are in the range (-180..180), and (0..360) otherwize. Only affects return values, input values remain unconstrained. Defaults to FALSE.
Typically, subroutines to not modify their parameters, but in stead return copies of the results. Paramaters with 'v' in the identifier are vectors, 'm' stands for matrix.
Modulates a longitude in degrees according to the value of NEGATIVE_LON. Returns the modulated longitude.
Calculate the angular distance between two points, represented by vectors. Returns the distance in radians, or undef. Of course, the angular distance is related to the distance along a greatcircle through the radius of the sphere in question.
Calculate the solid angle of the area spanned between the three given vertices. Returns the solid angle in steradians, or undef. The solid angle of a triangle on a sphere is related to its area through the square of the radius of the sphere in question.
Calculate the carthesian location vector from a longitude-latitude pair in degrees. Returns a Carth3 vector, or an empty list.
Calculate a longitude-latitude pair in degrees from a carthesian location vector. Returns a Perl array containing longitude and latitude in degrees, or an empty list.
Calculates the azimuth and dip in degrees of a vector in its current reference system. Returns the azimuth and dip in degrees, or an empty list.
The azimuth of a vector is defined as the angle between the positive y axis and the projection of the vector onto the horizontal (x, y) plane, in the mathematically negative direction. The dip of a vector is defined as the angle with the horizontal plane, and positive when pointing downward, or opposite to the z direction. In global coordinates the azimuth is 90 degrees minus the longitude, and the dip is the negation of the latitude. In local (east, north, up) coordinates, the azimuth is the angle with the north direction measured clockwize, and the dip is the downward angle with the horizontal plane.
Calculate a rotation matrix which transforms global carthesian vectors to local coordinates (local east, local north, local up). Returns a Carth3 matrix, or an empty list.
Sets verbose mode for this module to the logical value of the first parameter passed. If no argument is given, verbose mode is toggled. Returns true if verbose mode is set, false otherwize. Verbose mode is on by default. This subroutine is not exported, and can only be called through a full package reference.
#!/usr/bin/perl
# Coords test bed
use strict;
# import required symbols
use Carth3 qw(:FUNCTIONS);
use Coords qw(:CONSTANTS :VARIABLES :FUNCTIONS);
use Math::Trig qw(rad2deg);
$, = "\t"; # get decent alignment
$NEGATIVE_LON = 0; # default
my @loc = &calc_loc_vec(230, 45) or die "can't calculate vector";
print "NEGATIVE_LON is false\nlocation:",
&calc_lon_lat(@loc),
"\nNEGATIVE_LON is true\n";
$NEGATIVE_LON = 1;
my @other_loc = &calc_loc_vec(230, 44);
print "the distance between the two points\n",
&calc_lon_lat(@loc), " and \n",
&calc_lon_lat(@other_loc), "\n",
"is approx. ", &angle(@loc, @other_loc) * EARTH_RADIUS(), "meters.\n",
"angle: ", rad2deg(&angle(@loc, @other_loc)), "deg.\n\n",
"(note the numerical truncation error)\n";
perl(1), Math::Trig(3), Carth3(3).
Evangelization bit:
to avoid namespace clashes, typing errors and lots of other problems, I
strongly recommend using strict.
No symbols are exported into the caller's namespace, but in stead, all required symbols should be explicitly imported, or referred to by using the package name. For ease of use, the export tags CONSTANTS, VARIABLES, and FUNCTIONS are defined.
Most subroutines perform some level of error checking (vagueness intentional). Error messages are printed on STDERR if verbose mode is set, and should be self-explanatory. Furthermore, the value a subroutine returns is a good indication whether something went wrong, so check it.
Take care when passing vectors and matrices to subroutines. There is no way of checking in what order they are passed, which may lead to very nasty bugs. Also, directly modifying elements of vectors and matrices may lead to internal inconsistencies.
Joor Loohuis, loohuis@geo.uu.nl
You can determine which version of Coords you are using, by printing the
$Coords::VERSION variable from within your script.
Version numbering follows a scheme which is rapidly becoming accepted, in which the version minor (the first number after the first period) indicates whether a stable (even version minor) or a development version (odd version minor) is meant. Version majors (first number before first period) of 0 (zero) are all more in development than others.
Copyright (c) 1999 Joor Loohuis. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.