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

NAME

Carth3 - 3D carthesian vector/matrix functionality in Perl

SYNOPSIS

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

DESCRIPTION

Carth3 is a Perl module that provides 3D carthesian vector/matrix functionality in Perl, such as vector and matrix definitions and a few operations.

TYPES

Two 'types' of data are defined in Carth3, the first being a vector. Internally, it is a Perl array in which the vector norm, x, y, and z values are stored consecutively. Thus, the elements of a vector can be accessed through indices 1, 2, and 3. The matrix is a Perl array containing three vectors, representing the matrix rows and should be created as such. Indexing of individual matrix elements is provided through a subroutine or, alternatively, values can directly be accessed through indices 1..3 (row 1), 5..7 (row 2), and 9..11 (row 3). The latter is obviously harder to read.

CONSTANTS

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

NORM(): An alias for accessing the norm of a vector.
ZERO_VEC(): A carthesian vector with zero length.
E1(), E2(), E3(): Unit vectors in the (1, 0, 0), (0, 1, 0), and (0, 0, 1) directions.

VARIABLES

Carth3 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

Typically, subroutines to not modify their parameters, but in stead return copies of the results. For clarity, routines that operate on a matrix are identified with a 'm_' prefix. Paramaters with 'v' in the identifier are vectors, 'm' stands for matrix.

vector($x, $y, $z): Fill a vector, and set the norm. Returns the vector, or an empty list.
scale(@v, $scale): Scale a vector. Returns the scaled vector, or an empty list.
normalize(@v): Normalize a vector. Returns the normalized vector, or an empty list.
inner(@v1, @v2): Take the inner product of two vectors. Returns the inner product, or undef.
outer(@v1, @v2): Take the outer product of two vectors. Returns a vector, or an empty list.
add(@v1, @v2): Add two vectors. Returns a vector, or an empty list.
negate(@v): Negates a vector. Returns a vector, or an empty list.
m_index(@m, $row, $column): Return a matrix element, or undef.
m_add(@m1, @m2): Add two matrices together. Returns the sum, or an empty list.
m_scale(@m1, $scale): Scale a matrix. Returns the scaled matrix, or an empty list.
m_transpose(@m): Transpose a matrix. Returns the transposed matrix, or an empty list.
m_vec_mul(@m, @v): Perform a matrix vector multiplication. Returns the result vector, or an empty list.
m_mat_mul(@m1, @m2): Perform a matrix multiplication. Returns a matrix, or an empty list.
m_det(@m): Calculate the determinant of a matrix. Returns the determinant, or undef.
m_solve(@m, @v): Solve a matrix vector equation when coefficient matrix and right hand side are given. Returns the solution vector, or an empty list.
m_trace(@m): Calculates the trace of a matrix. Returns the trace, or undef.
m_invert(@m): Inverts a matrix. Returns the inverse, 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
    # Carth3 test bed

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

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

    my @mat = (
        &vector(0, 0, 1), 
        &vector(0, 1, 0), 
        &vector(1, 0, 0));
    my @rhs = &vector(4, 5, 6);

    print "\n", @mat[1..3], "\n", @mat[5..7], "\n", @mat[9..11], "\n";
    print "\n", @rhs[1..3], "\n";

    my @result = &m_solve(@mat, @rhs) or die "no solution exists\n";
    print "\n", @result[1..3], "\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

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.

AUTHOR

Joor Loohuis, loohuis@geo.uu.nl

HISTORY

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