NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
SEE ALSO
NOTES
DIAGNOSTICS
RESTRICTIONS
AUTHOR
HISTORY
COPYRIGHT

NAME

Rotate - geographic rotation functionality in Perl.

SYNOPSIS

    # be smart
    use strict;
    # import required symbols
    use Rotate qw(:tag func $scalar);
    # your code goes here

DESCRIPTION

Rotate is a Perl module that provides basic functionality for rotations on a sphere.

CONSTANTS

Rotate 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.

YEAR(): The number of seconds in one year.
MA(): The number of seconds in one Ma.
DEG_MA(): The factor necessary to convert angular velocities from deg/Ma to rad/s (division) and vice versa (multiplication).

VARIABLES

Rotate defines the following variables.

$VERBOSE: 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.

SUBROUTINES

sec2ma($seconds): Convert a time in seconds to a time in Ma. Returns the time.
ma2sec($mega-annum): Convert a time in Ma to a time in seconds. Returns the time.
calc_pole($lon, $lat, $angle): Calculate a rotation pole from a lon-lat pair in degrees and an angular velocity in deg/Ma. Returns a Carth3 vector.
rotate_x($angle): Calculate the matrix for a mathematically positive rotation around the x (E1) axis. Returns the rotation matrix, or an empty list.
rotate_y($angle): Calculate the matrix for a mathematically positive rotation around the y (E2) axis. Returns the rotation matrix, or an empty list.
rotate_z($angle): Calculate the matrix for a mathematically positive rotation around the z (E3) axis. Returns the rotation matrix, or an empty list.
verbose($flag): 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.

EXAMPLE

    #!/usr/bin/perl
    # Rotate test bed

    use strict;
    # import required symbols
    use Carth3 qw(:CONSTANTS :FUNCTIONS);
    use Coords qw(:FUNCTIONS);
    use Rotate qw(:CONSTANTS :FUNCTIONS);

    $, = "\t"; # get decent alignment

    # location of Lampedusa
    my @loc = &calc_loc_vec(12.57, 35.34);
    # NUVEL-1A pole for Africa - Eurasia
    my @pole = &calc_pole(-20.6, 21.0, 0.12); 
    # calculate the velocity in m/s
    my @vel = &outer(@pole, @loc);
    # transformation to (east, north, up) coordinates
    my @local = &calc_local_mat(&calc_lon_lat(@loc));
    # transform to local coordinates
    my @local_vel = &m_vec_mul(@local, @vel);
    # scale to mm/yr
    @local_vel = &scale(@local_vel, 1000 * YEAR());
    # show the results
    print   "the velocity of Lampedusa relative to Eurasia is\n",
            $local_vel[NORM()], "mm/yr, and the azimuth and dip are\n",
            &calc_azm_dip(@local_vel), "deg\n";

NOTES

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.

DIAGNOSTICS

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.

RESTRICTIONS

I've run across a problem with Perl 5.004_02, where trigonometric functions return incorrect results. I can't put my finger on the exact origin, but to be on the safe side, this module requires Perl 5.004_04 or better.

AUTHOR

Joor Loohuis, loohuis@geo.uu.nl

HISTORY

You can determine which version of Rotate you are using, by printing the $Rotate::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.