matvec

1.1.1

The matvec package provides C/C++ preprocessor macros which perform matrix and vector operations in three dimensional space. There is support for 4-dimensional "homogeneous coordinates" which provide efficient combined rotation and translation operations.

The underlying macros are independent of the storage implementation. The package provides extractors to handle the most common storage implementations. Custom extractors are simple to construct.

Copyright

Copyright (C) 2006 Smithsonian Astrophysical Observatory

matvec is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

matvec is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA

Usage

Accessing the macros

To access the macros from code, ensure that the header file is included in the compilation unit:

#include <matvec/macros.h>

Matrix and Vector Storage

Matrices may be stored either as flat arrays or as C-style multi-dimensional arrays. Vectors may be flat arrays or structures. The underlying routines which perform the translations and rotations are fed the complete list of matrix and vector elements; they know nothing about how they are stored.

To isolate the caller from that interface, macros are provided which extract the elements from a particular storage type. These macros should be used whenever a macro parameter is listed as an "extractor". The list of extractors is available here.

For example, here's how to rotate and translate a vector stored in a structure using a matrix stored in a flat array:

#define MATRIX(mat_arr) MATVEC_MAT3X3_AS_ARRAY(matrix)
#define VECTOR(vector)  MATVEC_VEC_AS_STRUCT(vector,x,y,z)

  double matrix[9];
  struct { double x, y, z } va, ta, ra;
  MATVEC_VEC_ROTATE_TRANSLATE(MATRIX(mat_arr),
                               VECTOR(va),
                               VECTOR(ta),
                               VECTOR(ra));

(The definitions of MATRIX and VECTOR are not neccessary; they just clean up the code a bit.) Note that this interface allows mixing different vector implementations if necessary.

Implementation Subtleties

All of the facilities provided by this package are C/C++ preprocessor macros. Most of the error checking is provided by the compiler. However, there are some subtleties:

Rotation Matrix

A rotation matrix may represent either the rotation of a point within a coordinate frame, or the rotation of the coordinate frame. The convention used will dictate the interpretation of the result of applying the matrix to a vector -- it does not change how the rotation matrix is applied. Thus, the routines which populate a rotation matrix will follow a convention, but the routine which applies the matrix to a vector will work for either convention.

In this package the rotation matrice constructors create matrices which represent rotations of coordinate frames.


Generated on Wed Oct 28 15:10:01 2009 for matvec by  doxygen 1.4.7