|
|
LGPL NOTICESThis library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library 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* Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
Originally conceived in 1973 to support computer graphics, Vector is a modest linear algebra package specifically written for 3-dimensions. Although most of the algorithms are not restrictive, no higher space is supported. The original version was Fortran, here included with little modification. The C++ version is largely a translation of the Fortran version. 3-D vector algebra is well supported, and Vector has been widely used in the crystallographic community for programs to support graphics, analysis, and structure construction.
This release provides a vector_3d.h and vector_3d.cpp, and a FORTRAN library, and Vector_3_Test.cpp, with example/test programs
The Vector package is available at www.sourceforge.net/projects/vector. A source zip is available at downloads.sourceforge.net/vector/vector-0.1.3.zip. Later tarballs may be available.
The C++ code includes 4 classes. Vector_3 and Matrix_3x3 comprise most of the code. Line_3 and Plane_3 are small, rather incomplete classes for use with the other two.
Included also is a group of random numbers functions derived from code originally written by Rob Harrison. The function RandomOrientation, which returns a random rotation matrix, is the likely main one for use with Vector.
The header vector_3d.h and definitions source code vector_3d.cpp should be in the directory of the program to be compiled.
The provided interface is:
#include "vector_3d.h"
FUNCTIONS IN Vector_3
Vector_3( void ); // constructor
Default constructor - x,y,z are all initialized to DBL_MAX
explicit Vector_3 ( const double arg); // constructor
arg is used to initialize each of x,y,z
Vector_3 ( const double ax, const double ay, const double az ); // constructor
x,y,z are initialized to ax,ay,az, respectively
Vector_3 ( const Vector_3& input_vector); // copy constructor
the copy constructor returns a copy of input_vector
virtual ~Vector_3( void ); // destructor
SCALAR OPERATIONS ON VECTORS
Vector_3 operator* ( const double arg ) const;
returns a vector that is the input multiplied by the floating point scaling factor, arg
Vector_3 operator/ ( const double arg ) const;
returns a vector that is the input divided by the floating point scaling factor, arg
OPERATIONS ONLY ON VECTORS
double Dot ( const Vector_3& ) const;
returns the dot product of two vectors
Vector_3 DyadProduct ( const Vector_3& ) const;
returns a vector x(result)=x1*x2, y(result)=y1*y2, z(result)=s1*z2
Vector_3 Cross ( const Vector_3& ) const;
typical cross product of two vectors (also known as "vector product")
Matrix_3x3 TensorProduct ( const Vector_3& ) const;
where the dot product is v1 times v2-transpose, this returns
v1-transpose times v2, populating a matrix with all pairs of
x,y,z(1) times x,y,z(2) (also known as "outer product")
Vector_3 operator+ ( const Vector_3& ) const;
returns the vector sum of two vectors
Vector_3 operator- ( const Vector_3& ) const;
returns the vector difference of two vectors
Vector_3 operator- ( void ) const;
unary minus operator for a vector
Vector_3& operator+= ( const Vector_3& );
in place vector sum of two vectors
Vector_3& operator-= ( const Vector_3& );
in place subtraction of two vectors
double Norm ( void ) const;
returns the length of a vector
double SquaredLength ( void ) const;
returns the squared length of a vector (avoids the square root computation
required by Norm(vector))
Vector_3 UnitV ( void ) const;
returns a unit vector with the same direction (therefore same
direction cosines) as the input vector
Vector_3& operator= ( const Vector_3& );
assignment operator of vectors
static Vector_3 GetCenterOfMass ( const Container& );
returns the vector to the center of mass of in input group of vectors
static Matrix_3x3 Pair
( const Vector_3& v1,
const Vector_3& v2,
const Vector_3& v3,
const Vector_3& v4 );
returns a matrix that will rotate v1 onto v3 and place v2 as close
as possible to v4 while maintaining the alignment of v1,v3
static Vector_3 GetXAxis ( void );
returns the vector (1,0,0)
static Vector_3 GetYAxis ( void );
returns the vector (0,1,0)
static Vector_3 GetZAxis ( void );
returns the vector (0,0,1)
static Vector_3 GetZeroVector (void );
returns the vector (0,0,0)
bool operator== ( const Vector_3& ) const;
bool operator!= ( const Vector_3& ) const;
static double Angle (
const Vector_3& v1;,
const Vector_3& v2,
const Vector_3& v3 );
returns the angle between the vector from v2 to v1
and the vector from v2 to v3. Torsion and Angle differ from
most of the functions in Vector_3 in that they use the ends of vectors
static double Torsion (
const Vector_3& v1,
const Vector_3& v2,
const Vector_3& v3,
const Vector_3& v4 );
returns the torsion angle from the sequence to the ends of
v1,v2,v3,v4, respectively. Torsion and
Angle differ from most of the functions in Vector_3 in that
they use the ends of vectors
double DistanceFromPlane ( const VPlane& ) const;
returns the distance of a point from a 3-space plane
double DistanceFromLine ( const VLine& ) const;
returns the distance of a point from a 3-space line
OPERATIONS USING MATRICES
Vector_3 MV ( const Matrix_3x3& ) const;
premultiply a vector by a matrix
COMPLEX OPERATIONS
Matrix_3x3 Rotmat ( const double angle ) const;
returns the matrix that will rotate points about the input vector
by the specified angle
Matrix_3x3 InertiaTensorForPoint ( const double weight ) const;
returns the inertia tensor for a point (used to compute best line and plane)
weight is used to weight the importance of the input points
ACCESS FUNCTIONS
double operator[] ( const int& n ) const;
for input values of 0,1,2, operator[] returns x,y,z, respectively
double at ( const int& ) const;
for input values of 0,1,2, at returns x,y,z, respectively
friend functions
Vector_3 operator* ( const double& value, const Vector_3& v );
returns a vector that is value times the input vector
VPlane_3 BestPlane ( const Container& );
returns the plane that best approximates the list of points in the input
container (which can be any container class, such as std::vector, that
has proper iterators)
VLine_3 BestLine ( const Container& );
returns the line that best approximates the list of points in the input
container (which can be any container class, such as std::vector, that
has proper iterators)
FUNCTIONS IN Matrix_3x3
Matrix_3x3 ( void ); // constructor
constructs a Matrix_3x3 with all entries initialized to DBL_MAX
Matrix_3x3 (
const double, const double, const double,
const double, const double, const double,
const double, const double, const double ); // constructor
returns a Matrix_3x3 with the elements equal to the 9 input values, in row order
Matrix_3x3 ( const Matrix_3x3& ); // copy constructor
virtual ~Matrix_3x3 ( void ); // destructor
MATRIX/VECTOR OPERATIONS
Vector_3 MV ( const Vector_3& ) const;
returns a vector that is the input vector premultiplied by the input matrix
OPERATIONS ON MATRICES ONLY
Matrix_3x3 operator* ( const Matrix_3x3& ) const;
returns the product of the two input matrices
Matrix_3x3 operator+ ( const Matrix_3x3& ) const;
returns the sum of the two input matrices
Matrix_3x3 operator- ( const Matrix_3x3& ) const;
returns the difference of the two input matrices
Matrix_3x3 operator* ( const double d) const;
returns a matrix that is multiplied by d
Matrix_3x3 operator/ ( const double d ) const;
returns a matrix that is divided by d
Matrix_3x3& operator+= ( const Matrix_3x3& );
in place sum of two matrices
Matrix_3x3& operator-= ( const Matrix_3x3& );
in place difference of two matrices
Matrix_3x3& operator*= ( const Matrix_3x3& );
in place product of two matrices
Matrix_3x3& operator= ( const Matrix_3x3& ); // copy constructor
Matrix_3x3 Transpose ( void ) const;
returns the transpose of the input matrix
Matrix_3x3 Inver ( void ) const;
returns the inverse of the input matrix
void UnitMatrix ( void );
in place convesion of the input matrix to a unit matrix
double Det ( void ) const;
returns the determinant of the input matrix
void Zero ( void );
converts the input matrix to a zero matrix
bool Eigen1 ( double& eigenvalue, Vector_3& eigenvector ) const;
returns the largest eigenvalue of the input matrix and its corresponding eigenvector
bool Eigen3 ( std::vector& eigenvalues, std::vector& eigenvectors ) const;
returns all 3 eigenvalues of the input matrix and their corresponding eigenvectors
double operator[] ( const int& ) const;
returns the n-th element of the input matrix (in row order)
Matrix_3x3 Cart( const double a, const double b, const double c,
const double alpha, const double beta, const double gamma )
Cart is used to generate a matrix that will convert from coordinates
in a non-orthogonal coordinate system to an orthogonal basis. This is the solution
for the common problem in crystallography, where coordinates are often reported in
coordinates that are measured using the unit cell dimensions. Cart will return
a matrix that when multiplied by a vector expressed in fractional coordinates will
generate the corresponding position in an orthonormal system. NOTE: VERY IMPORTANT:
The coordinates created by that operation may NOT be comparable to those generated
by some other conversion software. Each system assumes a particular relationship
between the two system, and they are ALL correct. Basically, the conversion matrix
can be multiplied by ANY rotation matrix at all, and the result will still generate
correct orthogonal coordinates, just different ones. The inverse of the matrix that
Cart generates will convert from orthogonal coordinates back to fractional ONLY IF
the orginal transformation was made with the same convention that Cart uses.
The convention used in Cart is that the a-crystallographic axis will be aligned
parallel to x, the b-axis as close as possible to y, and the c-axis by construction
of a right handed-coordinate system.
OTHER FUNCTIONS
static std::vector AB_BestRotation
const ContainerType& v1,
const ContainerType& v2,
Vector_3& centerOfMass1,
Vector_3& centerOfMass2,
Matrix_3x3& rotationMatrixFrom2To1,
double& rmsd,
const int pairCount=0 )
A common problem in crystallography is superimposing two similar structures. AB_BestRotation
is a new (2009) algorithm for solving this problem. Currently, this is a somewhat preliminary
version of the method. The transformations that it produces are nearly identical to the
standard Kabsch algorithm's results. Interest in it centers on its abilities to use
some interesting weighting schemes and possibly substructure determination. This early
version does not yet implement these. Its behavior for small numbers of input points
has not been fully investigated, but it seems quite stable for the number of atoms found
in a typical protein structure.
RETURN : the returned vector is a quaternion of four elements: cos(theta/2), sin(theta/2)*x,
sin(theta/2)*y, sin(theta/2)*z), where x,y,z are the direction cosines of the axis of rotation.
const ContainerType& v1
v1 is the list of input points for the first (reference) position. ContainerType
can be any STL container or other containers (e.g. NearTree) that have a resonable iterator
and a size() function.
const ContainerType& v2
Like v1, but this is the structure to be rotated onto v1. v2 and v1 must have exactly
the same number of points in corresponding positions.
Vector_3& centerOfMass1
The returned center of mass of the points in v1.
Vector_3& centerOfMass2
The returned center of mass of the points in v2.
Matrix_3x3& rotationMatrixFrom2To1
The returned rotation matrix that will rotate v2 onto v1 (as well as possible).
double& rmsd
The returned root mean square distance between the corresponding points of v1
and v2.
const int pairCount
pairCount controls the nature of the calculation. If pairCount is zero (the default
value), then every pair of atoms (that is in its original and rotated positions) is
used with every other pair in the computation (an O(n^2) process). If pairCount is greater
than zero, then each is compared with pairCount other pairs. If pairCount is one, then
the process is exactly O(n). Larger values have the potential to give more representative
output, but preliminary results seem to indicate that for a protein, this would not
make much difference. For small molecules, the exhaustive search is probably safer, and is quite fast.
For values of pairCount larger than 0, the other pairs are chosen by random selection.
FUNCTIONS IN Line_3
Line_3 ( void ); // constructor
Line_3 ( const Vector_3&; direction, const Vector_3& CenterOfMass );
constructs a Line_3 given a direction of the line and a point on the line
Vector_3 LineAxis ( void ) const;
returns the direction vector of a Line_3
Vector_3 BasePoint ( void ) const;
returns the point on a Line_3 that is closest to the coordinate system origin
virtual ~Line_3 ( void ); // destructor
double DistanceFromLine ( const Vector_3& v ) const;
for a given point, returns the distance of the point from the input line
FUNCTIONS IN Plane_3
Plane_3 ( void ); // constructor
Plane_3::Plane_3 ( const Vector_3& direction, const Vector_3& CenterOfMass);
constructs a plane given a vector perpendicular to the plane and a point in the plane
Vector_3 NormalVector ( void ) const;
returns the normal to the plane
Vector_3 BasePoint ( void ) const;
returns the point in the input plane that is closest to the origin
virtual ~Plane_3 ( void ); // destructor
double DistanceFromPlane ( const Vector_3& v ) const;
returns the distance of the input point v from the input plane
OTHER FUNCTIONS
Matrix_3x3 RandomOrientation( void )
returns a rotation matrix from a well-sampled distribution
Vector_3 RandomVector( void )
returns a vector that points in a random direction