org.biojava.nbio.structure.align.util

Class RotationAxis

java.lang.Object

org.biojava.nbio.structure.align.util.RotationAxis

public final class RotationAxis
extends Object

Calculates the rotation axis for an alignment

A superposition of two structures is generally represented as a rotation matrix plus a translation vector. However, it can also be represented as an axis of rotation plus some translation.

This class calculates the rotation axis and stores it as four properties:

• A unit vector parallel to the rotation axis (getRotationAxis())
• The angle of rotation (getAngle())
• A point on the rotation axis (getRotationPos())
• Some translation parallel to the axis (getScrewTranslation())

The axis of rotation is poorly defined and numerically unstable for small angles. Therefore it's direction is left as null for angles less than MIN_ANGLE.

Author:

Spencer Bliven

Constructor Summary

Constructors

Constructor and Description
RotationAxis(AFPChain afpChain) Calculate the rotation axis for the first block of an AFPChain
RotationAxis(Atom axis, Atom pos, double theta) Create a rotation axis from a vector, a point, and an angle.
RotationAxis(javax.vecmath.Matrix4d transform) Create a rotation axis from a Matrix4d containing a rotational component and a translational component.
RotationAxis(Matrix rotation, Atom translation) Determine the location of the rotation axis based on a rotation matrix and a translation vector

Method Summary

Modifier and Type	Method and Description
double	getAngle() The rotation angle
static double	getAngle(AFPChain afpChain) Calculate the rotation angle for a structure
static double	getAngle(Matrix rotation) Calculate the rotation angle for a given matrix
static double	getAngle(javax.vecmath.Matrix3d transform) Quickly compute the rotation angle from a rotation matrix.
static double	getAngle(javax.vecmath.Matrix4d transform) Quickly compute the rotation angle from a rotation matrix.
javax.vecmath.AxisAngle4d	getAxisAngle4d() Returns the rotation axis and angle in a single javax.vecmath.AxisAngle4d object
Pair<Atom>	getAxisEnds(Atom[] atoms) Find a segment of the axis that covers the specified set of atoms.
Matrix	getFullMatrix() Returns a matrix that describes both rotation and translation.
String	getJmolScript(Atom[] atoms) Returns a Jmol script which will display the axis of rotation.
String	getJmolScript(Atom[] atoms, int axisID) Returns a Jmol script which will display the axis of rotation.
double	getProjectedDistance(Atom point) Get the distance from a point to the axis of rotation
Atom	getProjectedPoint(Atom point) Projects a given point onto the axis of rotation
Atom	getRotationAxis() Get a unit vector along the rotation axis
Matrix	getRotationMatrix() Get the rotation matrix corresponding to this axis
Matrix	getRotationMatrix(double theta) Get the rotation matrix corresponding to a rotation about this axis
Atom	getRotationPos() Get a position on the rotation axis.
Atom	getScrewTranslation() Get the component of translation parallel to the axis of rotation
double	getTranslation()
javax.vecmath.Vector3d	getVector3dScrewTranslation()
int	guessOrderFromAngle(double threshold, int maxOrder) Returns the rotation order o that gives the lowest value of |2PI / o - theta, given that the value is strictly lower than threshold, for orders {@code o=1,...
boolean	isDefined()
void	rotate(Atom[] atoms, double theta)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RotationAxis

public RotationAxis(AFPChain afpChain)
             throws StructureException

Calculate the rotation axis for the first block of an AFPChain

Parameters:

afpChain -

Throws:

StructureException

NullPointerException - if afpChain does not contain a valid rotation matrix and shift vector

RotationAxis

public RotationAxis(Atom axis,
                    Atom pos,
                    double theta)

Create a rotation axis from a vector, a point, and an angle. The result will be a pure rotation, with no screw component.

Parameters:

axis - A vector parallel to the axis of rotation

pos - A point on the axis of rotation

theta - The angle to rotate (radians)

RotationAxis

public RotationAxis(Matrix rotation,
                    Atom translation)

Determine the location of the rotation axis based on a rotation matrix and a translation vector

Parameters:

rotation -

translation -

RotationAxis

public RotationAxis(javax.vecmath.Matrix4d transform)

Create a rotation axis from a Matrix4d containing a rotational component and a translational component.

Parameters:

transform -

Method Detail

getAngle

public double getAngle()

The rotation angle

Returns:

the angle, in radians

getRotationAxis

public Atom getRotationAxis()

Get a unit vector along the rotation axis

Returns:

rotationAxis

getAxisAngle4d

public javax.vecmath.AxisAngle4d getAxisAngle4d()

Returns the rotation axis and angle in a single javax.vecmath.AxisAngle4d object

Returns:

getRotationPos

public Atom getRotationPos()

Get a position on the rotation axis. Specifically, project the origin onto the rotation axis

Returns:

rotationPos

getScrewTranslation

public Atom getScrewTranslation()

Get the component of translation parallel to the axis of rotation

Returns:

getVector3dScrewTranslation

public javax.vecmath.Vector3d getVector3dScrewTranslation()

getTranslation

public double getTranslation()

getRotationMatrix

public Matrix getRotationMatrix()

Get the rotation matrix corresponding to this axis

Returns:

A 3x3 rotation matrix

getRotationMatrix

public Matrix getRotationMatrix(double theta)

Get the rotation matrix corresponding to a rotation about this axis

Parameters:

theta - The amount to rotate

Returns:

A 3x3 rotation matrix

guessOrderFromAngle

public int guessOrderFromAngle(double threshold,
                               int maxOrder)

Returns the rotation order o that gives the lowest value of |2PI / o - theta, given that the value is strictly lower than threshold, for orders o=1,...,maxOrder.

getFullMatrix

public Matrix getFullMatrix()

Returns a matrix that describes both rotation and translation.

getJmolScript

public String getJmolScript(Atom[] atoms)

Returns a Jmol script which will display the axis of rotation. This consists of a cyan arrow along the axis, plus an arc showing the angle of rotation.

As the rotation angle gets smaller, the axis of rotation becomes poorly defined and would need to get farther and farther away from the protein. This is not particularly useful, so we arbitrarily draw it parallel to the translation and omit the arc.

Parameters:

atoms - Some atoms from the protein, used for determining the bounds of the axis.

Returns:

The Jmol script, suitable for calls to jmol.evalString()

getAxisEnds

public Pair<Atom> getAxisEnds(Atom[] atoms)

Find a segment of the axis that covers the specified set of atoms.

Projects the input atoms onto the rotation axis and returns the bounding points.

In the case of a pure translational axis, the axis location is undefined so the center of mass will be used instead.

Parameters:

atoms -

Returns:

two points defining the axis segment

getJmolScript

public String getJmolScript(Atom[] atoms,
                            int axisID)

Returns a Jmol script which will display the axis of rotation. This consists of a cyan arrow along the axis, plus an arc showing the angle of rotation.

As the rotation angle gets smaller, the axis of rotation becomes poorly defined and would need to get farther and farther away from the protein. This is not particularly useful, so we arbitrarily draw it parallel to the translation and omit the arc.

Parameters:

atoms - Some atoms from the protein, used for determining the bounds of the axis.

axisID - in case of representing more than one axis in the same jmol panel, indicate the ID number.

Returns:

The Jmol script, suitable for calls to jmol.evalString()

getProjectedPoint

public Atom getProjectedPoint(Atom point)

Projects a given point onto the axis of rotation

Parameters:

point -

Returns:

An atom which lies on the axis, or null if the RotationAxis is purely translational

getProjectedDistance

public double getProjectedDistance(Atom point)

Get the distance from a point to the axis of rotation

Parameters:

point -

Returns:

The distance to the axis, or NaN if the RotationAxis is purely translational

rotate

public void rotate(Atom[] atoms,
                   double theta)

getAngle

public static double getAngle(AFPChain afpChain)
                       throws StructureException

Calculate the rotation angle for a structure

Parameters:

afpChain -

Returns:

The rotation angle, in radians

Throws:

StructureException - If the alignment doesn't contain any blocks

NullPointerException - If the alignment doesn't have a rotation matrix set

getAngle

public static double getAngle(Matrix rotation)

Calculate the rotation angle for a given matrix

Parameters:

rotation - Rotation matrix

Returns:

The angle, in radians

isDefined

public boolean isDefined()

Returns:

If the rotation axis is well defined, rather than purely translational

getAngle

public static double getAngle(javax.vecmath.Matrix4d transform)

Quickly compute the rotation angle from a rotation matrix.

Parameters:

transform - 4D transformation matrix. Translation components are ignored.

Returns:

Angle, from 0 to PI

getAngle

public static double getAngle(javax.vecmath.Matrix3d transform)

Quickly compute the rotation angle from a rotation matrix.

Parameters:

transform - 3D rotation matrix

Returns:

Angle, from 0 to PI