Package 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:

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
    Description
    RotationAxis(javax.vecmath.Matrix4d transform)
    Create a rotation axis from a Matrix4d containing a rotational component and a translational component.
    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(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
    Description
    double
    getAngle()
    The rotation angle
    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.
    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
    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 o=1,...,maxOrder.
    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 Details

    • 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 Details

    • 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

    • 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

    • 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