Detailed Description

This module contains general purpose algebraic and geometric methods.

This module contains general purpose algebraic and geometric methods that are expected to be used by a wide variety of IMP modules.

Geometric primitives

IMP has a number of geometry primitives. They support the following namespace functions as appropriate

In addition, they cannot be compared against one another due to floating point implementation issues (eg Vector3D v=v2 does not imply v==v2).

Geometry and dimensions: Many of the geometric primitives and operations in IMP are written to work in any dimension. In C++, this is implemented via templates (such as IMP::algebra::VectorD). In the python side, the different dimensions are named explicitly instead. That means, a 2-D point is IMP::algebra::VectorD<2> in C++, and IMP::algbra::Vector2D in python and the function IMP::algebra::get_basis_vector_d<3>() in C++ becomes IMP.algebra.get_basis_vector_3d() in Python. Similarly, a collection of 2D points is std::vector<IMP::algebra::VectorD<2> > in C++ and IMP.algebra.Vector2Ds in python, which as with all collections, look like python lists. For convenience, we provide typedefs in C++ to the IMP::algbra::Vector2D and IMP::algebra::Vector2Ds style names.

Generic geometry: Geometry in IMP can be stored in a variety of ways. For example, a point in 3D can be stored using an IMP::algebra::VectorD<3> or using an IMP::core::XYZ particle. It is often useful to be able to write algorithms that work on sets of points without worring how they are stored, the Generic Geometry layer provides that. It works using a set of functions get_vector_3d() and set_vector_3d() which manipulate the geometetry in terms of the IMP::algebra representation of the geometry in question. That is, get_vector_3d() returns a IMP::algebra::VectorD<3> for both an IMP::algebra::Vector3D and a IMP::core::XYZ. Algorithms take their arguments as C++ templates and use the generic geometry methods to manipulate the geometry. And versions of the function for both types of storage are exported to python, so one could also write generic functions in python.

For example, IMP::atom::get_rmsd() takes any combination of IMP::algebra::Vector3Ds or IMP::core::XYZs or IMP::core::XYZsTemp as arguments. Versions for all combinations of those are exported to python.

Uninitialized default values

Some geometric primitives are not put into a defined state by their constructor. Such classes mimic POD types (int, float etc) in C++ and are optimized for efficiency. All operations on a default initialized instance other than assigning to it from a non-default initialized instance should be assumed to be invalid.

IMP::algebra::VectorD<3> v0, v1;
v0 != v1;
// only legal operations initialize v0, eg
v0= IMP::algebra::VectorD<3>(1,2,3);

CGAL: Certain functionality provided in IMP requires or benefits from using CGAL. CGAL is a library of geometry-related algorithms and data structures written in C++. The relevant parts of CGAL are licensed under LGPL and QPL and commercial licenses are available if needed. More information can be found on the CGAL license page.

Examples:

Author(s)

Daniel Russel, Keren Lasker, Ben Webb, Javier Angel Velazquez-Muriel

Version

SVN 8931:8936 with ANN, cgal

License:

LGPL. This 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 of the License, or (at your option) any later version.

Publications:

Daniel Russel, Keren Lasker, Ben Webb, Dina Schneidman, Javier Velázquez-Muriel, Andrej Sali, “Integrative assembly modeling using IMP”, submitted, 2010. This paper provides an overview of the key concepts in IMP and how to apply them to biological problems.
Frank Alber, Friedrich Foerster, Dmitry Korkin, Maya Topf, Andrej Sali, “Integrating diverse data for structure determination of macromolecular assemblies”, Annual Review of Biochemistry, 2008. This paper provides a review of the integrative structure determination methodology and various data sources that can be used.

Namespaces
namespace	grids
	Implementation for parameterized grids.
Data Structures
class	BoundingBoxD
	An axis-aligned bounding box. More...
class	Cone3D
class	Cylinder3D
struct	DenseGrid3D
class	Ellipsoid3D
class	FixedXYZ
	A simple class for returning XYZ Euler angles. More...
class	FixedZYZ
	A simple class for returning ZYZ Euler angles. More...
class	LinearFit
	Calculate line that fits best the input data points. More...
class	Matrix2D
class	Matrix3D
class	MultiArray
class	NearestNeighborD
class	ParabolicFit
	Calculate parabola that fits best the input data points. More...
class	Plane3D
class	PrincipalComponentAnalysis
class	ReferenceFrame3D
	A reference frame in 3D. More...
class	Reflection3D
	Reflect about a plane in 3D. More...
class	Rotation2D
	Stores a 2D rotation matrix. More...
class	Rotation3D
	3D rotation class. More...
class	Segment3D
struct	SparseGrid3D
struct	SparseUnboundedGrid3D
struct	SparseUnboundedGridD
class	SphereD
class	SpherePatch3D
class	SphericalVector3D
	Class to represent a 3D point in spherical coordinates. More...
class	Transformation2D
	Simple 2D transformation class. More...
class	Transformation3D
	Simple 3D transformation class. More...
class	Triangle3D
class	VectorD
	A Cartesian vector in D-dimensions. More...
Python Only
The following functions are only availale in Python as the equivalent C++ functionality is provided via template functions or in other ways that don't directly map to python.
typedef Grid3D< int, SparseGridStorage3D< int, BoundedGridStorage3D > >	SparseIntGrid3D
typedef Grid3D< int, SparseGridStorage3D< int, UnboundedGridStorage3D > >	SparseUnboundedIntGrid3D
typedef Grid3D< double, DenseGridStorage3D< double > >	DenseDoubleGrid3D
typedef Grid3D< float, DenseGridStorage3D< float > >	DenseFloatGrid3D
Transformation3D	get_transformation_aligning_first_to_second (Vector3Ds a, Vector3Ds b)
Typedefs
typedef std::pair< VectorD < 3 >, double >	AxisAnglePair
typedef BoundingBoxD< 3 >	BoundingBoxD< 3 >
typedef Matrix2D< std::complex < double > >	Matrix2D_c
typedef Matrix2D< double >	Matrix2D_d
typedef Matrix2D< int >	Matrix2D_i
typedef VectorOfRefCounted < Matrix2D_c * >	Matrix2Ds_c
typedef VectorOfRefCounted < Matrix2D_d * >	Matrix2Ds_d
	A vector of reference counted pointers to 2D Matrices of doubles.
typedef VectorD< 1 >	Vector1D
typedef std::vector< VectorD< 1 > >	Vector1Ds
typedef VectorD< 2 >	Vector2D
typedef std::vector< VectorD< 2 > >	Vector2Ds
typedef VectorD< 3 >	Vector3D
typedef std::vector< VectorD< 3 > >	Vector3Ds
typedef VectorD< 4 >	Vector4D
typedef std::vector< VectorD< 4 > >	Vector4Ds
typedef VectorD< 5 >	Vector5D
typedef std::vector< VectorD< 5 > >	Vector5Ds
typedef VectorD< 6 >	Vector6D
typedef std::vector< VectorD< 6 > >	Vector6Ds
typedef VectorD<-1 >	VectorKD
typedef std::vector< VectorD<-1 > >	VectorKDs
Functions
template<int D>
int	compare (const VectorD< D > &a, const VectorD< D > &b)
	lexicographic comparison of two vectors
Rotation2D	compose (const Rotation2D &a, const Rotation2D &b)
	compose two rotations a and b
Transformation2D	compose (const Transformation2D &a, const Transformation2D &b)
	compose two transformations
Transformation3D	compose (const Transformation3D &a, const Transformation3D &b)
	compose two transformations
Rotation3D	compose (const Rotation3D &a, const Rotation3D &b)
Transformation3Ds	get_alignments_from_first_to_second (const PrincipalComponentAnalysis pca1, const PrincipalComponentAnalysis pca2)
bool	get_are_almost_equal (const double a, const double b, const double epsilon)
	Compares two values (intended for doubles)
template<class Geometry >
double	get_area (const Geometry &)
	Compute the area of any surface object.
std::pair< VectorD< 3 >, double >	get_axis_and_angle (const Rotation3D &rot)
	Decompose a Rotation3D object into a rotation around an axis.
double	get_ball_radius_from_volume_3d (double volume)
	Return the radius of a sphere with a given volume.
template<int D>
VectorD< D >	get_basis_vector_d (unsigned int coordinate)
	Return the basis vector for the given coordinate.
VectorD<-1 >	get_basis_vector_kd (int D, unsigned int coordinate)
	Return a dynamically sized basis vector.
template<int D, class Storage , class Value >
BoundingBoxD< D >	get_bounding_box (const grids::GridD< D, Storage, Value > &g)
template<class Geometry >
BoundingBoxD< 3 >	get_bounding_box (const Geometry &)
	Compute the bounding box of any geometric object.
double	get_closer_power_of_2 (double x)
	Closest power of 2 for a number, not necessarily higher.
template<typename T >
T	get_constrained (const T x, const T x0, const T xF)
	Constrains a value between two given limits.
std::string	get_data_path (std::string file_name)
	Return the path to installed data for this module.
double	get_distance (const Segment3D &s, const VectorD< 3 > &p)
	Get the distance between a segment and a point.
double	get_distance (const Segment3D &a, const Segment3D &b)
	Get the distance between two segments.
template<int D>
double	get_distance (const SphereD< D > &a, const SphereD< D > &b)
	Return the distance between the two spheres if they are disjoint.
double	get_distance (const Rotation3D &r0, const Rotation3D &r1)
	Return a distance between the two rotations.
double	get_distance (const Plane3D &pln, const VectorD< 3 > &p)
	Return the distance between a plane and a point in 3D.
template<int D>
double	get_distance (const VectorD< D > &v1, const VectorD< D > &v2)
	compute the distance between two vectors
IntPairs	get_edges (const BoundingBoxD< 3 > &)
	Return the edges of the box as indices into the vertices list.
SphereD< 3 >	get_enclosing_sphere (const std::vector< SphereD< 3 > > &ss)
	Return a sphere containing the listed spheres.
SphereD< 3 >	get_enclosing_sphere (const std::vector< VectorD< 3 > > &ss)
	Return a sphere containing the listed spheres.
std::string	get_example_path (std::string file_name)
	Return the path to installed example data for this module.
Rotation2D	get_identity_rotation_2d ()
	Builds an identity rotation in 2D.
Rotation3D	get_identity_rotation_3d ()
	Return a rotation that does not do anything.
Transformation2D	get_identity_transformation_2d ()
	Returns a transformation that does not do anything.
Transformation3D	get_identity_transformation_3d ()
	Return a transformation that does not do anything.
template<int D>
bool	get_interiors_intersect (const SphereD< D > &a, const SphereD< D > &b)
	Return true if the two balls bounded by the two spheres interesect.
template<int D>
bool	get_interiors_intersect (const BoundingBoxD< D > &a, const BoundingBoxD< D > &b)
	Return true if they intersect.
Rotation3D	get_interpolated (const Rotation3D &a, const Rotation3D &b, double f)
	Interpolate between two rotations.
template<int D>
BoundingBoxD< D >	get_intersection (const BoundingBoxD< D > &a, const BoundingBoxD< D > &b)
	Return the intersecting bounding box.
Triangle3D	get_largest_triangle (const Vector3Ds &points)
	Return the largest triangle defined by 3 points from the input.
template<int D>
double	get_maximum_length (const BoundingBoxD< D > &a)
	Return the maximum axis aligned extent.
std::string	get_module_name ()
const VersionInfo &	get_module_version_info ()
float	get_next_larger_power_of_2 (float x)
	Closest power of 2 that can contain a number x.
double	get_next_larger_power_of_2 (double x)
	Closest power of 2 that can contain a number x.
template<int D>
VectorD< D >	get_ones_vector_d (double v=1)
	Return a vector of ones (or another constant)
VectorD<-1 >	get_ones_vector_kd (int D, double v=1)
	Return a vector of ones (or another constant)
template<int D>
double	get_power_distance (const SphereD< D > &a, const SphereD< D > &b)
	Return the power distance between the two spheres.
PrincipalComponentAnalysis	get_principal_components (const std::vector< VectorD< 3 > > &ps)
	Perform principle components analysis on a set of vectors.
Transformation3D	get_random_local_transformation (Vector3D origin, float max_translation=5., float max_angle_in_rad=0.26)
	Get a local transformation.
Rotation2D	get_random_rotation_2d ()
	Builds an identity rotation in 2D.
Rotation3D	get_random_rotation_3d (const Rotation3D &center, double distance)
	Pick a rotation at random near the provided one.
Rotation3D	get_random_rotation_3d ()
	Pick a rotation at random from all possible rotations.
VectorD< 3 >	get_reflected (const Plane3D &pln, const VectorD< 3 > &p)
	return the point reflected about the plane
Rotation3D	get_rotation_about_axis (const VectorD< 3 > &axis, double angle)
	Generate a Rotation3D object from a rotation around an axis.
Transformation2D	get_rotation_about_point (const Vector2D &point, const Rotation2D &rotation)
	Generates a Transformation2D object from a rotation around a point.
Transformation3D	get_rotation_about_point (const VectorD< 3 > &point, const Rotation3D &rotation)
	Generate a Transformation3D object from a rotation around a point.
Rotation3D	get_rotation_from_matrix (double m00, double m01, double m02, double m10, double m11, double m12, double m20, double m21, double m22)
	Generate a Rotation3D object from a rotation matrix.
Rotation3D	get_rotation_from_vector4d (const VectorD< 4 > &v)
	Compute a rotatation from an unnormalized quaternion.
Rotation3D	get_rotation_from_x_y_axes (const VectorD< 3 > &x, const VectorD< 3 > &y)
Rotation3D	get_rotation_taking_first_to_second (const VectorD< 3 > &v1, const VectorD< 3 > &v2)
	Create a rotation from the first vector to the second one.
Rotation2D	get_rotation_to_x_axis (const VectorD< 2 > &v)
template<typename T >
int	get_rounded (const T &x)
	Rounds a number to next integer.
template<typename T >
int	get_sign (const T &x)
	Sign of a number. 1 if the number is higher or equal to 0 and -1 otherwise.
template<int D>
double	get_squared_distance (const VectorD< D > &v1, const VectorD< D > &v2)
	compute the squared distance between two vectors
template<class Geometry >
double	get_surface_area (const Geometry &)
	Compute the surface area of any volumetric object.
Transformation3D	get_transformation_3d (const Transformation2D &t2d)
	Builds a 3D transformation from a 2D one.
template<class Vector3DsOrXYZs0 , class Vector3DsOrXYZs1 >
IMP::algebra::Transformation3D	get_transformation_aligning_first_to_second (IMP_RESTRICT const Vector3DsOrXYZs0 &from, IMP_RESTRICT const Vector3DsOrXYZs1 &to)
	Compute the rigid transform bringing the first point set to the second.
Transformation2D	get_transformation_aligning_pair (const std::vector< VectorD< 2 > > &set_from, const std::vector< VectorD< 2 > > &set_to)
Transformation3D	get_transformation_from_first_to_second (const ReferenceFrame3D &a, const ReferenceFrame3D &b)
Transformation3D	get_transformation_from_first_triangle_to_second (Triangle3D first_tri, Triangle3D second_tri)
	Return a transformation between two triangles.
BoundingBoxD< 3 >	get_transformed (const BoundingBoxD< 3 > &bb, const Transformation3D &tr)
	Return a bounding box containing the transformed box.
ReferenceFrame3D	get_transformed (const ReferenceFrame3D &rf, const Transformation3D &tr)
template<class Storage >
const Storage::Value	get_trilinearly_interpolated (const grids::GridD< 3, Storage > &g, const VectorD< 3 > &v, const typename Storage::Value &outside=0)
	Use trilinear interpolation to compute a smoothed value at v.
Rotation3Ds	get_uniform_cover_rotations_3d (unsigned int num_points)
	Cover the space of rotations evenly.
template<unsigned int D>
BoundingBoxD< D >	get_unit_bounding_box_d ()
template<unsigned int D>
SphereD< D >	get_unit_sphere_d ()
SphereD<-1 >	get_unit_sphere_kd (unsigned int d)
template<int D>
const VectorD< D > &	get_vector_d_geometry (const VectorD< D > &g)
std::vector< VectorD< 3 > >	get_vertices (const BoundingBoxD< 3 > &bb)
	Return a list of the 8 bounding points for the bounding box.
template<class Geometry >
double	get_volume (const Geometry &)
	Compute the volume of any volumetric object.
template<int D>
VectorD< D >	get_zero_vector_d ()
	Return a vector of zeros.
VectorD<-1 >	get_zero_vector_kd (int D)
	Return a dynamically sized vector of zeros.
template<int D>
VectorD< D >	operator* (double s, const VectorD< D > &o)
template<int D>
void	set_vector_d_geometry (VectorD< D > &g, const VectorD< D > &v)
Euler Angles
There are many conventions for how to define Euler angles, based on choices of which of the x,y,z axis to use in what order and whether the rotation axis is in the body frame (and hence affected by previous rotations) or in in a fixed frame. See http://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles for a general description. All Euler angles are specified in radians. The names are all `rotation_from_{fixed/body}_abc()` where abc is the ordering of x,y,z.
Rotation3D	get_rotation_from_fixed_xyz (double xr, double yr, double zr)
	Initialize a rotation in x-y-z order from three angles.
Rotation3D	get_rotation_from_fixed_zxz (double phi, double theta, double psi)
	Initialize a rotation from euler angles.
Rotation3D	get_rotation_from_fixed_zyz (double Rot, double Tilt, double Psi)
	Generate a rotation object from Euler Angles.
FixedZYZ	get_fixed_zyz_from_rotation (const Rotation3D &r)
	The inverse of rotation_from_fixed_zyz()
FixedXYZ	get_fixed_xyz_from_rotation (const Rotation3D &r)
	The inverse of rotation_from_fixed_xyz()
3D Vectors
We provide a specialization of VectorD for 3-space and several additional functions on it.
VectorD< 3 >	get_vector_product (const VectorD< 3 > &p1, const VectorD< 3 > &p2)
	Returns the vector product (cross product) of two vectors.
VectorD< 3 >	get_orthogonal_vector (const VectorD< 3 > &v)
	Return a vector that is perpendicular to the given vector.
VectorD< 3 >	get_centroid (const std::vector< VectorD< 3 > > &ps)
	Returns the centroid of a set of vectors.
double	get_radius_of_gyration (const std::vector< VectorD< 3 > > &ps)
	Return the radius of gyration of a set of points.
Norms
We define a number of standard, , norms on VectorD. is the Manhattan distance, the sum of the components is the standard Euclidean length $L^{\inf}$ is the maximum of the components
template<int D>
double	get_l2_norm (const VectorD< D > &v)
template<int D>
double	get_l1_norm (const VectorD< D > &v)
template<int D>
double	get_linf_norm (const VectorD< D > &v)
Endian
`IMP` provides a variety of functionality to manage byte order in input and output data.
void	reversed_read (void *dest, size_t size, size_t nitems, std::ifstream &f, bool reverse)
	Reads from file in normal or reverse order.
void	reversed_write (const void *src, size_t size, size_t nitems, std::ofstream &f, bool reverse=false)
	Writes to a file in normal or reversed order.
template<class T >
void	get_swapped_endian (T &x)
	Conversion between little and big endian. Goes both ways.
bool	get_is_big_endian ()
	Returns 1 if machine is big endian else 0.
bool	get_is_little_endian ()
	Returns 1 if machine is little endian else 0.
Simple geometric IO
These functions write geometry to text files, one line per geometric primitive. Each line has the form “x y z” for points or “x y z r” for spheres. We can easily add general dimension support if requested.. Lines beginning with "" are treated as comments.
void	write_pts (const std::vector< VectorD< 3 > > &vs, TextOutput out)
	Write a set of 3D vectors to a file.
std::vector< VectorD< 3 > >	read_pts (TextInput in)
	Read a set of 3D vectors from a file.
void	write_spheres (const std::vector< VectorD< 3 > > &vs, TextOutput out)
	Write a set of 3d spheres to a file.
std::vector< SphereD< 3 > >	read_spheres (TextInput in)
	Read a set of 3d spheres from a file.
Shortest segments
These methods return the shortest segment connecting two geometric objects. Such segments can be used to give the direction of the derivative of the distance between the two objects. The 0 point on the segment is in the first passed object and the 1 point is in the second.
Segment3D	get_shortest_segment (const Segment3D &s, const VectorD< 3 > &p)
Segment3D	get_shortest_segment (const Segment3D &sa, const Segment3D &sb)
Vector Generators
These functions generate vector objects. Some of the methods, those with random in their name, generate a single vector chosen uniformly from the specified domain. Others, the cover methods, generate a set of points distributed (somewhat) evenly over the domain.
template<int D>
VectorD< D >	get_random_vector_in (const BoundingBoxD< D > &bb)
	Generate a random vector in a box with uniform density.
template<int D>
VectorD< D >	get_random_vector_on (const BoundingBoxD< D > &bb)
	Generate a random vector on a box with uniform density.
template<int D>
VectorD< D >	get_random_vector_in (const SphereD< D > &s)
	Generate a random vector in a sphere with uniform density.
template<int D>
VectorD< D >	get_random_vector_on (const SphereD< D > &s)
	Generate a random vector on a sphere with uniform density.
template<int D>
std::vector< VectorD< D > >	get_uniform_surface_cover (const SphereD< D > &s, unsigned int n)
	Generate a set of vectors which covers a sphere uniformly.
std::vector< VectorD< 3 > >	get_uniform_surface_cover (const Cylinder3D &cyl, int number_of_points)
	Generate a set of 3d points that uniformly cover a cylinder.
template<int D>
std::vector< VectorD< D > >	get_uniform_upper_hemisphere_cover (const SphereD< D > &s, unsigned int n)
	Generate a set of 3D points that uniformly cover a hemisphere.
std::vector< VectorD< 3 > >	get_grid_surface_cover (const Cylinder3D &cyl, int number_of_cycles, int number_of_points_on_cycle)
	Generate a grid of 3d points on a cylinder surface.
std::vector< VectorD< 3 > >	get_uniform_surface_cover (const SpherePatch3D &sph, unsigned int number_of_points)
	Generate a set of 3d points that uniformly cover a patch of a sphere.
std::vector< VectorD< 3 > >	get_uniform_surface_cover (const Cone3D &cone, unsigned int number_of_points)
template<int D>
std::vector< VectorD< D > >	get_grid_volume_cover_by_spacing (const BoundingBoxD< D > &bb, double s)
std::vector< VectorD< 3 > >	get_random_chain (unsigned int n, double r, const VectorD< 3 > &start=Vector3D(0, 0, 0), const std::vector< SphereD< 3 > > &obstacles=Sphere3Ds())
	Generate a random chain with no collisions.

Typedef Documentation

typedef BoundingBoxD<3> IMP::algebra::BoundingBoxD< 3 >

See BoundingBoxD.

typedef Grid3D<double, DenseGridStorage3D<double> > IMP::algebra::DenseDoubleGrid3D

A grid of doubles over a region of space.

typedef Grid3D<float, DenseGridStorage3D<float> > IMP::algebra::DenseFloatGrid3D

A grid of floats over a region of space.

typedef Grid3D<int, SparseGridStorage3D<int, BoundedGridStorage3D> > IMP::algebra::SparseIntGrid3D

A sparse grid of integers over a bounded region of space.

typedef Grid3D<int, SparseGridStorage3D<int, UnboundedGridStorage3D> > IMP::algebra::SparseUnboundedIntGrid3D

A sparse grid of integers over all of space.

Function Documentation

template<int D>

int compare	(	const VectorD< D > &	a,
		const VectorD< D > &	b
	)

lexicographic comparison of two vectors

Note that this is not very reliable and probably should not be used.

Rotation2D IMP::algebra::compose	(	const Rotation2D &	a,
		const Rotation2D &	b
	)

compose two rotations a and b

For any vector v (a*b)*v = a*(b*v).

Transformation2D compose	(	const Transformation2D &	a,
		const Transformation2D &	b
	)

compose two transformations

For any vector v (a*b)*v = a*(b*v).

Transformation3D compose	(	const Transformation3D &	a,
		const Transformation3D &	b
	)

compose two transformations

For any vector v (a*b)*v = a*(b*v).

Transformation3Ds IMP::algebra::get_alignments_from_first_to_second	(	const PrincipalComponentAnalysis	pca1,
		const PrincipalComponentAnalysis	pca2
	)

Get all possible alignments of the first principle component system to the second one

bool IMP::algebra::get_are_almost_equal	(	const double	a,
		const double	b,
		const double	epsilon
	)

Compares two values (intended for doubles)

epsilon is the tolerance allowed to consider the values as equal

std::pair< VectorD< 3 >, double > get_axis_and_angle ( const Rotation3D & rot )

Decompose a Rotation3D object into a rotation around an axis.

Note:: http://en.wikipedia.org/wiki/Rotation_matrix; www.euclideanspace.com/maths/geometry/rotations/conversions/ angleToQuaternion/index.htm

double get_ball_radius_from_volume_3d ( double volume )

Return the radius of a sphere with a given volume.

<3>

template<int D>

VectorD< D > get_basis_vector_d ( unsigned int coordinate )

Return the basis vector for the given coordinate.

Return the unit vector pointing in the direction of the requested coordinate. That is

    get_basis_vector_d<3>(2)== VectorD<3>(0,0,1);

VectorD< 3 > get_centroid ( const std::vector< VectorD< 3 > > & ps )

Returns the centroid of a set of vectors.

<3>

std::string IMP::algebra::get_data_path ( std::string file_name )

Return the path to installed data for this module.

Each module has its own data directory, so be sure to use the version of this function in the correct module. To read the data file "data_library" that was placed in the data directory of module "mymodule", do something like

    std::ifstream in(IMP::mymodule::get_data_path("data_library"));

This will ensure that the code works when IMP is installed or used via the tools/imppy.sh script.

double get_distance	(	const Segment3D &	a,
		const Segment3D &	b
	)

Get the distance between two segments.

double get_distance	(	const Segment3D &	s,
		const VectorD< 3 > &	p
	)

Get the distance between a segment and a point.

double get_distance	(	const Rotation3D &	r0,
		const Rotation3D &	r1
	)

Return a distance between the two rotations.

The distance runs between 0 and 1. More precisely, the distance returned is distance between the two quaternion vectors properly normalized, divided by sqrt(2).

A vector with distance d from the unit vector represents a rotation of

$\theta= \cos^{-1}\left(1-\sqrt{2}d\right)$

template<int D>

double get_distance	(	const SphereD< D > &	a,
		const SphereD< D > &	b
	)

Return the distance between the two spheres if they are disjoint.

If they intersect, the distances are not meaningful.

double get_distance	(	const Plane3D &	pln,
		const VectorD< 3 > &	p
	)

Return the distance between a plane and a point in 3D.

SphereD< 3 > get_enclosing_sphere ( const std::vector< SphereD< 3 > > & ss )

Return a sphere containing the listed spheres.

<3>

Note:: This method produces tighter bounding spheres if CGAL is used.

SphereD< 3 > get_enclosing_sphere ( const std::vector< VectorD< 3 > > & ss )

Return a sphere containing the listed spheres.

<3> <3>

Note:: This method produces tighter bounding spheres if CGAL is used.

std::string IMP::algebra::get_example_path ( std::string file_name )

Return the path to installed example data for this module.

Each module has its own example directory, so be sure to use the version of this function in the correct module. For example to read the file example_protein.pdb located in the examples directory of the IMP::atom module, do

    IMP::atom::read_pdb(IMP::atom::get_example_path("example_protein.pdb", model));

This will ensure that the code works when IMP is installed or used via the tools/imppy.sh script.

FixedXYZ IMP::algebra::get_fixed_xyz_from_rotation ( const Rotation3D & r )

The inverse of rotation_from_fixed_xyz()

See also:: rotation_from_fixed_xyz()

FixedZYZ get_fixed_zyz_from_rotation ( const Rotation3D & r )

The inverse of rotation_from_fixed_zyz()

See also:: rotation_from_fixed_zyz()

Rotation3D get_identity_rotation_3d ( )

Return a rotation that does not do anything.

Transformation3D get_identity_transformation_3d ( )

Return a transformation that does not do anything.

Rotation3D get_interpolated	(	const Rotation3D &	a,
		const Rotation3D &	b,
		double	f
	)

Interpolate between two rotations.

It f ==0, return b, if f==1 return a.

Triangle3D get_largest_triangle ( const Vector3Ds & points )

Return the largest triangle defined by 3 points from the input.

VectorD< 3 > get_orthogonal_vector ( const VectorD< 3 > & v )

Return a vector that is perpendicular to the given vector.

Or, if you are Israeli, it is a vertical vector. <3>

template<int D>

double get_power_distance	(	const SphereD< D > &	a,
		const SphereD< D > &	b
	)

Return the power distance between the two spheres.

The power distance is the square of the distance between the centers minus the sum of the square of the radii.

double IMP::algebra::get_radius_of_gyration ( const std::vector< VectorD< 3 > > & ps )

Return the radius of gyration of a set of points.

See also:: IMP::atom::get_radius_of_gyration()

std::vector<VectorD<3> > IMP::algebra::get_random_chain	(	unsigned int	n,
		double	r,
		const VectorD< 3 > &	start = `Vector3D(0, 0, 0)`,
		const std::vector< SphereD< 3 > > &	obstacles = `Sphere3Ds()`
	)

Generate a random chain with no collisions.

This function generates a random chain, starting at (0,0,0) with n particles each with radius r. Consecutive particles are approximately distance 2r apart and no pair of particles is closer than 2r.

If an obstacles parameter is provided then chain spheres also don't intersect the obstacle spheres.

Note:: The current implementation is not very clever and can be made more clever if needed.

Transformation3D IMP::algebra::get_random_local_transformation	(	Vector3D	origin,
		float	max_translation = `5.`,
		float	max_angle_in_rad = `0.26`
	)

Get a local transformation.

Note:: randomly select an axis that passes to the input point and rotate around it

Parameters:

[in]	origin	the origin of the rotation
[in]	max_translation	detault value is 5
[in]	max_angle_in_rad	default value is 15 degree in radians

Rotation3D get_random_rotation_3d ( )

Pick a rotation at random from all possible rotations.

Rotation3D get_random_rotation_3d	(	const Rotation3D &	center,
		double	distance
	)

Pick a rotation at random near the provided one.

This method generates a rotation that is within the provided distance of center.

Parameters:

[in]	center	The center of the rotational volume
[in]	distance	See get_distance(const Rotation3D&,const Rotation3D&) for a full definition.

Note:: The cost of this operation increases as distance goes to 0.

template<int D>

IMP::algebra::get_random_vector_in ( const SphereD< D > & s )

Generate a random vector in a sphere with uniform density.

Examples: kmeans, rigid body and excluded volume restraint, filter close pairs, rigid collisions, randomize rigid body, initialize chains, local fitting

template<int D>

IMP::algebra::get_random_vector_on ( const SphereD< D > & s )

Generate a random vector on a sphere with uniform density.

Examples: grid space, local fitting

Rotation3D get_rotation_about_axis	(	const VectorD< 3 > &	axis,
		double	angle
	)

Generate a Rotation3D object from a rotation around an axis.

Parameters:

[in]	axis	the rotation axis passes through (0,0,0)
[in]	angle	the rotation angle in radians in the clockwise direction

Note:: http://en.wikipedia.org/wiki/Rotation_matrix; www.euclideanspace.com/maths/geometry/rotations/conversions/ angleToQuaternion/index.htm

Transformation2D get_rotation_about_point	(	const Vector2D &	point,
		const Rotation2D &	rotation
	)

Generates a Transformation2D object from a rotation around a point.

Generates a Transformation2D to rotate about a point rather than the origin.

Parameters:

[in]	point	Center to rotate about
[in]	rotation	The rotation to perform (defined taking the origin as reference, not the new point).

Transformation3D get_rotation_about_point	(	const VectorD< 3 > &	point,
		const Rotation3D &	rotation
	)

Generate a Transformation3D object from a rotation around a point.

Rotate about a point rather than the origin.

Parameters:

[in]	point	Center to rotate about
[in]	rotation	The rotation to perform

Rotation3D get_rotation_from_fixed_xyz	(	double	xr,
		double	yr,
		double	zr
	)

Initialize a rotation in x-y-z order from three angles.

Parameters:

[in]	xr	Rotation around the X axis in radians
[in]	yr	Rotation around the Y axis in radians
[in]	zr	Rotation around the Z axis in radians

Note:: The three rotations are represented in the original (fixed) coordinate frame.

Rotation3D get_rotation_from_fixed_zxz	(	double	phi,
		double	theta,
		double	psi
	)

Initialize a rotation from euler angles.

Parameters:

[in]	phi	Rotation around the Z axis in radians
[in]	theta	Rotation around the X axis in radians
[in]	psi	Rotation around the Z axis in radians

Note:: The first rotation is by an angle phi about the z-axis. The second rotation is by an angle theta in [0,pi] about the former x-axis , and the third rotation is by an angle psi about the former z-axis.

Rotation3D get_rotation_from_fixed_zyz	(	double	Rot,
		double	Tilt,
		double	Psi
	)

Generate a rotation object from Euler Angles.

Note:: The first rotation is by an angle about the z-axis. The second rotation is by an angle about the new y-axis. The third rotation is by an angle about the new z-axis.

Parameters:

[in]	Rot	First Euler angle (radians) defining the rotation (Z axis)
[in]	Tilt	Second Euler angle (radians) defining the rotation (Y axis)
[in]	Psi	Third Euler angle (radians) defining the rotation (Z axis)

Rotation3D get_rotation_from_vector4d ( const VectorD< 4 > & v )

Compute a rotatation from an unnormalized quaternion.

Rotation3D IMP::algebra::get_rotation_from_x_y_axes	(	const VectorD< 3 > &	x,
		const VectorD< 3 > &	y
	)

Return the rotation which takes the native x and y axes to the given x and y axes. The two axis must be perpendicular unit vectors.

Rotation2D IMP::algebra::get_rotation_to_x_axis ( const VectorD< 2 > & v )

Builds the rotation that transforms the vector X of the origin of coordinates into the given vector

template<typename T >

int IMP::algebra::get_rounded ( const T & x )

Rounds a number to next integer.

The result is of type integer but the argument can be of any type. Some examples:

 a = round(-0.7); // a = -1
 a = round(-0.2); // a = 0
 a = round(0.2); // a = 0
 a = round(0.7); // a = 1

Segment3D get_shortest_segment	(	const Segment3D &	s,
		const VectorD< 3 > &	p
	)

<3>

Transformation3D IMP::algebra::get_transformation_3d ( const Transformation2D & t2d )

Builds a 3D transformation from a 2D one.

Note:: The 3D transformation is built with the 2D rotation becoming a rotation around the z axis.

Transformation3D IMP::algebra::get_transformation_aligning_first_to_second	(	Vector3Ds	a,
		Vector3Ds	b
	)

Equivalent to

IMP::algebra::get_transformation_aligning_first_to_second(a,b);

template<class Vector3DsOrXYZs0 , class Vector3DsOrXYZs1 >

IMP::algebra::Transformation3D get_transformation_aligning_first_to_second	(	IMP_RESTRICT const Vector3DsOrXYZs0 &	from,
		IMP_RESTRICT const Vector3DsOrXYZs1 &	to
	)

Compute the rigid transform bringing the first point set to the second.

The points are assumed to be corresponding (that is, from[0] is aligned to to[0] etc.). The alignment computed is that which minimized the sum of squared distances between corresponding points. Return the

$\operatornamewithlimits{argmin}_T \sum \left|T\left(f\left[i\right]\right)-t[i]\right|^2$

If the point sets lie in a 1 or 2 dimensional subspace, the alignment algorithm is unstable and not guaranteed to work. A warning is printed in this case.

See also:: VectorD<3>

Transformation2D IMP::algebra::get_transformation_aligning_pair	(	const std::vector< VectorD< 2 > > &	set_from,
		const std::vector< VectorD< 2 > > &	set_to
	)

Builds the transformation required to obtain a set of points from the first one

Note:: The function assumes that the relative distances between points are conserved.

template<class Storage >

const Storage::Value IMP::algebra::get_trilinearly_interpolated	(	const grids::GridD< 3, Storage > &	g,
		const VectorD< 3 > &	v,
		const typename Storage::Value &	outside = `0`
	)

Use trilinear interpolation to compute a smoothed value at v.

The voxel values are assumed to be at the center of the voxel and the passed outside value is used for voxels outside the grid. The type Voxel must support get_linearly_interpolated().

Rotation3Ds IMP::algebra::get_uniform_cover_rotations_3d ( unsigned int num_points )

Cover the space of rotations evenly.

If you care about the distance between samples instead of the number of samples, the "surface area" of the set of rotations is pi^2. If you allocate each sample a volume of 4/3 pi d^3 (to space them d apart), Then you want 3/4 pi/d^3 points.

Creates at least num_points rotations.

std::vector< VectorD< 3 > > get_uniform_surface_cover	(	const SpherePatch3D &	sph,
		unsigned int	number_of_points
	)

Generate a set of 3d points that uniformly cover a patch of a sphere.

Note:: the implementation can be improved

template<int D>

std::vector< VectorD< D > > get_uniform_surface_cover	(	const SphereD< D > &	s,
		unsigned int	n
	)

Generate a set of vectors which covers a sphere uniformly.

The function is currently pretty slow, especially in non-optimized builds. Complain if this bugs you. We might be able to do better, at least in 3D.

Creates at least the requested number of points.

Note:: This predicates will produce guaranteed correct results if the CGAL library is available (the results will be unreliable if it is not).

template<int D>

std::vector<VectorD<D> > IMP::algebra::get_uniform_upper_hemisphere_cover	(	const SphereD< D > &	s,
		unsigned int	n
	)

Generate a set of 3D points that uniformly cover a hemisphere.

The points all lie on the upper hemisphere, eg, all their z coordinates are greater than those of the center of the sphere.

VectorD< 3 > get_vector_product	(	const VectorD< 3 > &	p1,
		const VectorD< 3 > &	p2
	)

Returns the vector product (cross product) of two vectors.

<3>

template<int D>

VectorD< D > operator*	(	double	s,
		const VectorD< D > &	o
	)

std::vector< VectorD< 3 > > read_pts ( TextInput in )

Read a set of 3D vectors from a file.

See also:: write_pts

std::vector< SphereD< 3 > > read_spheres ( TextInput in )

Read a set of 3d spheres from a file.

See also:: write_pts

void IMP::algebra::reversed_read	(	void *	dest,
		size_t	size,
		size_t	nitems,
		std::ifstream &	f,
		bool	reverse
	)

Reads from file in normal or reverse order.

If the reverse parameter is true, the data will be read in reverse order.

void IMP::algebra::reversed_write	(	const void *	src,
		size_t	size,
		size_t	nitems,
		std::ofstream &	f,
		bool	reverse = `false`
	)

Writes to a file in normal or reversed order.

This function is the same as fread from C, but at the end there is a flag saying if data should be read in reverse order or not.

If the reverse parameter is true, the data will be written in reverse order.

void write_pts	(	const std::vector< VectorD< 3 > > &	vs,
		TextOutput	out
	)

Write a set of 3D vectors to a file.

See also:: read_pts

void write_spheres	(	const std::vector< VectorD< 3 > > &	vs,
		TextOutput	out
	)

Write a set of 3d spheres to a file.

See also:: read_pts

IMP::algebra Namespace Reference

Detailed Description

Author(s)

Version

License:

Publications:

Namespaces

Data Structures

Python Only

Typedefs

Functions

Typedef Documentation

Function Documentation