org.proteinshader.structure
Class Segment

java.lang.Object
  org.proteinshader.structure.Drawable
      org.proteinshader.structure.Segment

All Implemented Interfaces:

Visitable

public class Segment
extends Drawable

When a protein is drawn as a tube-like structure, a Segment is a length of the tube that corresponds to an AminoAcid.

Region objects (Helix, BetaStrand, and Loop) are drawn as tube-like structures to obtain a schematic or cartoon-like representation of a protein. The tube is drawn by sweeping a waist polygon along a spline (a series of control points along a set of cubic equations, where each cubic equation runs from the center of one alpha-carbon to the center of the next alpha-carbon). In addition to the xyz-coordinates for each point along the spline, a rotation (equivalent to a Frenet frame) needs to be specified so that the waist polygon can be oriented in the right direction.

The center of a Segment is the alpha-carbon of the AminoAcid the Segment cooresponds to, and the Segment runs from approximately the center of the peptide bond before the alpha-carbon to the center of the peptide bond after the alpha-carbon. The xyz-coordinates of the alpha-carbon will be the world-space translation of the Segment. In object-space, the center of the Segment is (0, 0, 0), as objects are usually drawn about the origin and then afterwards translated to some position in world-space. The rotation associated with the center of the Segment should be based on local protein structure, and will vary depending on whether the Segment is a Helix, BetaStrand, or Loop. The rotation will be calculated by the SegmentFactory.

A Segment object will hold on to two Hermite objects (hermite1 and hermite2) and three Quaternion objects (startRotation, middleRotation, and endRotation). These objects will be created by the SegmentFactory and then plugged in to the Segment contstructor.

The hermite1 object holds the cubic equation from the center of the previous Segment object to the center of this Segment object, while the hermite2 object holds the cubic equation from the center of this Segment object to the center of the next Segment object. If a previous or next Segment does not exist, then a cubic equation to some imaginary next or previous Segment will have to be used (this issue will be dealt with by the SegmentFactory). The hermite1 object will be used for finding xyz-points on the spline in the first half of the Segment object, while the hermite2 object will be used for finding xyz-points on the spline in the second half of the Segment object. These xyz-points are the object-space translation component of a LocalFrame object.

The startRotation and endRotation correspond to the middleRotation for the previous (i-1) and next (i+1) Segments, respectively. If there is no previous or next Segment, then some reasonable rotation will need to be made up by the SegmentFactory. The startRotation and the middleRotation will be used for finding the rotation for any point along the spline in the first half of the Segment object, while the middleRotation and the endRotation will be used for finding the rotation for any point along the spline in the second half of the Segment object. Because the rotations are stored as Quaternion objects, the rotation interpolations can be done with SLERP (Spherical Linear intERPolation), which should give a nice smooth transition between rotations.

By combining the Hermite and SLERP interpolations, a Segment will be able to produce a LocalFrame object for any point along the spline from the beginning to the end of the Segment. A LocalFrame contains a rotation (as a Quaternion) and a translation (as a Vec3d) that can be used to position a waist polygon when rendering the Segment. To obtain an individual LocalFrame, the getLocalFrame() method takes as an argument a paramter t, where 0.0 <= t <= 1.0. If t = 0 is plugged in, a LocalFrame corresponding to a point on the spline at the very beginning of the Segment is returned. If t = 0.5 is plugged in, the LocalFrame returned will correspond to the center of the Segment (where the alpha-carbon is located on the spline). If t = 1.0 is plugged in, the LocalFrame will correspond to the very end of the Segment. To obtain an array of LocalFrames, the getLocalFrames() method takes an argument n, where n is the total number of frames from the first to the last frame of the Segment.

Field Summary

static DecorationEnum	DECORATION The default decoration is HALFTONING.
static double	MAX_BEND The maximum bend is the cosine of the smallest expected bend angle for a Segment.

Fields inherited from class org.proteinshader.structure.Drawable

DEFAULT_ALPHA, DEFAULT_BLUE, DEFAULT_GREEN, DEFAULT_RADIUS, DEFAULT_RED, DEFAULT_SPECULAR_EXP

Constructor Summary

Segment(AminoAcid aminoAcid, Hermite hermite1, Hermite hermite2, Quaternion startRotation, Quaternion middleRotation, Quaternion endRotation, boolean alwaysCapStart, boolean alwaysCapEnd)
Creates a Segment.

Method Summary

void	accept(Visitor visitor) Accepts a Visitor and does a callback.
boolean	displayAlphaCarbon() Returns true if the alpha-carbon should be displayed.
AminoAcid	getAminoAcid() Returns the a reference to the AminoAcid that this Segment corresponds to.
AminoAcidEnum	getAminoAcidType() Returns the type of AminoAcid that this Sement represents.
float	getBendFactor() Returns the bend factor, which is calculated using the tangent at the very beginning of the segment and the tangent at the very end of the segment.
int	getBendTexture() Returns the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used as a second texture for adding extra lines in the middle of segments that have a sharp bend to them.
DecorationEnum	getDecoration() Returns the decoration type for this Segment (PLAIN, WIREFRAME, TEXT_LABEL, PATTERNS, or HALFTONING).
Quaternion	getEndRotation() Returns a clone of the Quaternion for the end rotation of this Segment.
String	getFullName() Returns the full name of the Segment, which is a concatenation of the structureID, modelID, regionID, and residueID (with a single blank space between IDs).
int	getHalftoningTexture() Returns the name (an integer) of an OpenGL texure object that can be used for real-time halftoning (or returns zero if no such texture object is associated with this Segment).
Hermite	getHermite1() Creates a clone of the hermite1 object and returns it.
Hermite	getHermite2() Creates a clone of the hermite2 object and returns it.
LocalFrame	getLocalFrame(double t) Creates a LocalFrame along the Segment spline by using Hermite interpolation and SLERP (Spherical Linear intERPolation).
LocalFrame[]	getLocalFrames(int n) Uses SLERP (Spherical Linear intERPolation) and Hermite interpolation to generate the requested number of LocalFrames from the start frame to the end frame, inclusive.
Vec3d	getMiddleBinormal() Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the third column vector, the Binormal.
Vec3d	getMiddleNormal() Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the first column vector, the Normal.
Quaternion	getMiddleRotation() Returns a clone of the Quaternion for the middle rotation of this Segment.
Vec3d	getMiddleTangent() Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the third column vector, the Tangent.
Vec3d	getMiddleXYZ() Copies the xyz-coordinates for the center of this Segment into a new Vec3d and returns it.
Segment	getNextSegment() Returns a reference to the next Segment with the same region so that the visiblity status of the next Segment can be checked before deciding to render a start cap for the current tube or ribbon segment.
int	getPatternsTexture() Returns the name (an integer) of an OpenGL texure object that can be used for applying a pattern onto the surface of this Segment (or returns zero if there is no texture object for applying a pattern).
Segment	getPrevSegment() Returns a reference to the previous Segment with the same region so that the visiblity status of the previous Segment can be checked before deciding to render a start cap for the current tube or ribbon segment.
RegionEnum	getRegionType() Returns the type of Region that this Segment belongs to.
String	getSegmentID() Returns the Segment ID, which is the same as the Residue ID of the AminoAcid this Segment represents.
SideChainEnum	getSideChainStyle() Gets the side chain style (NONE, SPACE_FILLING, STICK_AND_BALLS, or STICKS).
Quaternion	getStartRotation() Returns a clone of the Quaternion for the start rotation of this Segment.
boolean	isEndCapped() Returns a boolean value to indicate if the end of the Segment should be capped when it is drawn.
boolean	isStartCapped() Returns a boolean value to indicate if the start of the Segment should be capped when it is drawn.
void	reverseXYAxesOfMiddleRotation() Modifies the middle rotation quaternion such that if it is converted to the matrix [N B T], the N (x-axis) and B (y-axis) column vectors are inverted.
void	setBendTexture(int bendTexture) Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used as a second texture for adding extra lines in the middle of segments that have a sharp bend to them.
void	setCapEnd(boolean alwaysCapEnd) Sets a boolean value to remember if the end of the Segment should always be capped when it is drawn.
void	setCapStart(boolean alwaysCapStart) Sets a boolean value to remember if the start of the Segment should be always be capped when it is drawn.
void	setDecoration(DecorationEnum decoration) Sets the decoration type for this Segment (PLAIN, WIREFRAME, TEXT_LABEL, or HALFTONING).
void	setHalftoningTexture(int halftoningTexture) Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used for real-time halftoning with the Segment.
void	setNextSegment(Segment next) Stores a reference to the next Segment within the same Region.
void	setPatternsTexture(int patternsTexture) Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used for applying a pattern to the surface of this Segment.
void	setPrevSegment(Segment prev) Stores a reference to the previous Segment within the same Region.
void	setSideChainStyle(SideChainEnum style, boolean alphaCarbon) Sets the side chain style (NONE, SPACE_FILLING, STICK_AND_BALLS, or STICKS) and determines whether the alpha-carbon should be shown.
void	setToAminoAcidColor() Sets the Segment color to the AAColorEnum for the AminoAcid this Segment corresponds to.
void	setToRegionColor() Sets the Segment color to the RegionColorEnum for the type of Region this Segment belongs to.
String	toString() Returns the ID of this Segment.

Methods inherited from class org.proteinshader.structure.Drawable

distance, getAlpha, getAngstromsPerPixel, getBlue, getCameraDepth, getCameraDistance, getColor, getDrawableType, getGreen, getPoint, getRadius, getRed, getSpecularExp, getTranslation, getVisibility, getX, getY, getZ, minus, scaleRadius, setAlpha, setAlphaToDefault, setAngstromsPerPixel, setCameraDepth, setCameraDistance, setColor, setColor, setColor, setRadius, setRadiusToDefault, setRGBAToDefault, setRGBToDefault, setSpecularExp, setSpecularExpToDefault, setVisibility

Methods inherited from class java.lang.Object

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

Field Detail

DECORATION

public static final DecorationEnum DECORATION

The default decoration is HALFTONING.

MAX_BEND

public static final double MAX_BEND

The maximum bend is the cosine of the smallest expected bend angle for a Segment. The bend angle is determined by placing the tangent at the beginning of the Segment tail to tail with the tangent at the end of the Segment and using the dot product. The maximum bend is currently set to 0.59, which is the cosine of 53 degrees. Bends greater than that are rare.

See Also:

Constant Field Values

Constructor Detail

Segment

public Segment(AminoAcid aminoAcid,
               Hermite hermite1,
               Hermite hermite2,
               Quaternion startRotation,
               Quaternion middleRotation,
               Quaternion endRotation,
               boolean alwaysCapStart,
               boolean alwaysCapEnd)

Creates a Segment. If the AminoAcid argument is null, then a null pointer exception would be thrown right away. If any of the other arguments are null, then getLocalFrame() or getLocalFrames() would return only LocalFrames with the multiplication identity rotation and a translation of (0, 0, 0). The SegmentFactory should do all of the error checking to make sure that a complete Segment can be created (no arguments to the constructor should be null).

The segmentID will be the same as the residueID of the AminoAcid that the Segment cooresponds to. The Segment will also be assigned a full name, which will be the concatenation of the modelID, chainID, and residueID (with a blank space between IDs).

Parameters:

aminoAcid - the AminoAcid the Segment corresponds to.

hermite1 - cubic equation for first half of the Segment.

hermite2 - cubic equation for second half of the Segment.

startRotation - the middleRotation of the previous Segment.

middleRotation - the rotation at the center of this Segment.

endRotation - the middleRotation of the previous Segment.

alwaysCapStart - indicates if the start should always be capped.

alwaysCapEnd - indicates if the end should be always capped.

Method Detail

accept

public void accept(Visitor visitor)
            throws VisitorException

Accepts a Visitor and does a callback.

Specified by:

accept in interface Visitable

Specified by:

accept in class Drawable

Parameters:

visitor - the Visitor to do a callback with.

Throws:

VisitorException - if an error occurs while an object is being visited.

getSegmentID

public String getSegmentID()

Returns the Segment ID, which is the same as the Residue ID of the AminoAcid this Segment represents.

Returns:

The Segment ID as a String.

getFullName

public String getFullName()

Returns the full name of the Segment, which is a concatenation of the structureID, modelID, regionID, and residueID (with a single blank space between IDs).

Returns:

The full name as a String.

getAminoAcid

public AminoAcid getAminoAcid()

Returns the a reference to the AminoAcid that this Segment corresponds to.

Returns:

The AminoAcid this Segment represents.

getAminoAcidType

public AminoAcidEnum getAminoAcidType()

Returns the type of AminoAcid that this Sement represents.

Returns:

The type as an AminoAcidEnum

getRegionType

public RegionEnum getRegionType()

Returns the type of Region that this Segment belongs to.

Returns:

The type of Region this Segment belongs to.

getDecoration

public DecorationEnum getDecoration()

Returns the decoration type for this Segment (PLAIN, WIREFRAME, TEXT_LABEL, PATTERNS, or HALFTONING).

The return type will never be null because if an argument of null is given to the setDecoration() method the value will be set to DecorationEnum.PLAIN.

Returns:

The decoration type as a DecorationEnum.

setDecoration

public void setDecoration(DecorationEnum decoration)

Sets the decoration type for this Segment (PLAIN, WIREFRAME, TEXT_LABEL, or HALFTONING).

If an argument of null is given, the decoration type will be set to PLAIN.

Parameters:

decoration - the decoration type for this Segment.

getPatternsTexture

public int getPatternsTexture()

Returns the name (an integer) of an OpenGL texure object that can be used for applying a pattern onto the surface of this Segment (or returns zero if there is no texture object for applying a pattern).

Returns:

The name (an integer) of an OpenGL texture.

setPatternsTexture

public void setPatternsTexture(int patternsTexture)

Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used for applying a pattern to the surface of this Segment.

Setting the texture name to zero means that there is no texture assigned.

Parameters:

patternsTexture - the name (an integer) of an OpenGL texture.

getHalftoningTexture

public int getHalftoningTexture()

Returns the name (an integer) of an OpenGL texure object that can be used for real-time halftoning (or returns zero if no such texture object is associated with this Segment).

Returns:

The name (an integer) of an OpenGL texture.

setHalftoningTexture

public void setHalftoningTexture(int halftoningTexture)

Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used for real-time halftoning with the Segment.

Setting the texture name to zero means that there is no such texture object associated with this Segment.

Parameters:

halftoningTexture - the name (an integer) of an OpenGL texture.

getBendTexture

public int getBendTexture()

Returns the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used as a second texture for adding extra lines in the middle of segments that have a sharp bend to them.

Returns:

The name (an integer) of an OpenGL texture.

setBendTexture

public void setBendTexture(int bendTexture)

Sets the name (an integer) of an OpenGL texture object (stored on the graphics card) that can be used as a second texture for adding extra lines in the middle of segments that have a sharp bend to them.

Setting the texture name to zero means that there is no such texture object associated with this Segment.

Parameters:

bendTexture - the name (an integer) of an OpenGL texture.

getBendFactor

public float getBendFactor()

Returns the bend factor, which is calculated using the tangent at the very beginning of the segment and the tangent at the very end of the segment.

Returns:

The bend factor.

getLocalFrames

public LocalFrame[] getLocalFrames(int n)

Uses SLERP (Spherical Linear intERPolation) and Hermite interpolation to generate the requested number of LocalFrames from the start frame to the end frame, inclusive.

Parameters:

n - the total number of LocalFrames requested.

Returns:

An array of n LocalFrames.

getLocalFrame

public LocalFrame getLocalFrame(double t)

Creates a LocalFrame along the Segment spline by using Hermite interpolation and SLERP (Spherical Linear intERPolation).

t = 0.0 gives the LocalFrame at the beginning of the Segment. t = 0.5 gives the LocalFrame at the middle of the Segment. t = 1.0 gives the LocalFrame at the end of the Segment.

Although Hermit interpolation and SLERP are intended for interpolating, it is possible to use them to extrapolate by plugging in values of t that are less than zero or greater than one.

PRECONDITIONS: hermite1, hermite2, startRotation, middleRotation, and endRotation must all be set before this method can be called. Otherwise, the LocalFrame returned will have the multiplication identity quaternion and a translation of (0, 0, 0).

Parameters:

t - a parameter from 0.0 to 1.0, inclusive.

Returns:

A LocalFrame at position t.

getHermite1

public Hermite getHermite1()

Creates a clone of the hermite1 object and returns it. The hermite1 object holds the cubic equation for doing Hermite interpolation for the first half of the Segment object.

Returns:

A clone of the hermite1 object.

getHermite2

public Hermite getHermite2()

Creates a clone of the hermite2 object and returns it. The hermite2 object holds the cubic equation for doing Hermite interpolation for the first half of the Segment object.

Returns:

A clone of the hermite2 object.

getMiddleNormal

public Vec3d getMiddleNormal()

Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the first column vector, the Normal.

Returns:

The Normal vector (N.x, N.y, N.z).

getMiddleBinormal

public Vec3d getMiddleBinormal()

Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the third column vector, the Binormal.

Returns:

The Binormal vector (B.x, B.y, B.z).

getMiddleTangent

public Vec3d getMiddleTangent()

Converts the middle rotation (a Quaternion) into a 3 x 3 rotation matrix and then returns the third column vector, the Tangent.

Returns:

The Tangent vector (T.x, T.y, T.z).

getMiddleXYZ

public Vec3d getMiddleXYZ()

Copies the xyz-coordinates for the center of this Segment into a new Vec3d and returns it. The xyz-coordinates can be thought of as the world-space translation of the Segment object, and they are the same as the xyz-coordinates for the alpha-carbon of the AminoAcid that this Segment refers to. A reference to the Vec3d is not kept by this object.

Returns:

A Vec3d with the xyz-center of this Drawable object.

getStartRotation

public Quaternion getStartRotation()

Returns a clone of the Quaternion for the start rotation of this Segment. The "start" rotation is actually the middle rotation of the previous Segment.

Returns:

The start rotation as a Quaternion.

getMiddleRotation

public Quaternion getMiddleRotation()

Returns a clone of the Quaternion for the middle rotation of this Segment.

Returns:

The middle rotation as a Quaternion.

getEndRotation

public Quaternion getEndRotation()

Returns a clone of the Quaternion for the end rotation of this Segment. The "end" rotation is actually the middle rotation of the next Segment.

Returns:

The end rotation as a Quaternion.

isStartCapped

public boolean isStartCapped()

Returns a boolean value to indicate if the start of the Segment should be capped when it is drawn.

This method will return true if any of the following is true:
1. The alwaysCapStart argument given to the constructor was true.
2. This Segment is OPAQUE, and the previous Segment is not OPAQUE.
3. This Segment is TRANSLUCENT, and the previous Segment is INVISIBLE.

Returns:

A boolean indicating if the start should be capped.

isEndCapped

public boolean isEndCapped()

Returns a boolean value to indicate if the end of the Segment should be capped when it is drawn.

This method will return true if any of the following is true:
1. The alwaysCapEnd argument given to the constructor was true.
2. This Segment is OPAQUE, and the next Segment is not OPAQUE.
3. This Segment is TRANSLUCENT, and the next Segment is INVISIBLE.

Returns:

A boolean indicating if the end should be capped.

reverseXYAxesOfMiddleRotation

public void reverseXYAxesOfMiddleRotation()

Modifies the middle rotation quaternion such that if it is converted to the matrix [N B T], the N (x-axis) and B (y-axis) column vectors are inverted.

This method is needed by the BetaStrandSegmentFactory so that it can adjust the x-axis and y-axis of the Frenet frame for every second Segment object so that the x-axes all end up on the same side of the ribbon and that the y-axes all end up on the same side of the ribbon.

setCapStart

public void setCapStart(boolean alwaysCapStart)

Sets a boolean value to remember if the start of the Segment should be always be capped when it is drawn.

Parameters:

alwaysCapStart - a boolean indicating if the start should be capped.

setCapEnd

public void setCapEnd(boolean alwaysCapEnd)

Sets a boolean value to remember if the end of the Segment should always be capped when it is drawn.

Parameters:

alwaysCapEnd - a boolean indicating if the end should be capped.

setToAminoAcidColor

public void setToAminoAcidColor()

Sets the Segment color to the AAColorEnum for the AminoAcid this Segment corresponds to.

setToRegionColor

public void setToRegionColor()

Sets the Segment color to the RegionColorEnum for the type of Region this Segment belongs to.

getSideChainStyle

public SideChainEnum getSideChainStyle()

Gets the side chain style (NONE, SPACE_FILLING, STICK_AND_BALLS, or STICKS). The side chain style will never be null because NONE will be used if null is given as an argument to the setSideChainStyle() method.

Returns:

The side chain style.

setSideChainStyle

public void setSideChainStyle(SideChainEnum style,
                              boolean alphaCarbon)

Sets the side chain style (NONE, SPACE_FILLING, STICK_AND_BALLS, or STICKS) and determines whether the alpha-carbon should be shown. If null is given as an argument, the side chain style will be set to NONE.

Parameters:

style - the desired style for side chains.

alphaCarbon - boolean to determine if alpha-carbon is shown.

displayAlphaCarbon

public boolean displayAlphaCarbon()

Returns true if the alpha-carbon should be displayed.

Returns:

True if the alpha-carbon should be displayed.

setPrevSegment

public void setPrevSegment(Segment prev)

Stores a reference to the previous Segment within the same Region. If the previous Segment does not exist (or is in the previous Region), the value here should be null.

Parameters:

prev - the previous Segment in the same Region.

getPrevSegment

public Segment getPrevSegment()

Returns a reference to the previous Segment with the same region so that the visiblity status of the previous Segment can be checked before deciding to render a start cap for the current tube or ribbon segment.

Returns:

A reference to the previous Segment.

setNextSegment

public void setNextSegment(Segment next)

Stores a reference to the next Segment within the same Region. If the next Segment does not exist (or is in the previous Region), the value here should be null.

Parameters:

next - the next Segment in the same Region.

getNextSegment

public Segment getNextSegment()

Returns a reference to the next Segment with the same region so that the visiblity status of the next Segment can be checked before deciding to render a start cap for the current tube or ribbon segment.

Returns:

A reference to the next Segment.

toString

public String toString()

Returns the ID of this Segment.

The Segment ID is the same as the Residue ID of the AminoAcid the Segment corresponds to.

Overrides:

toString in class Object

Returns:

The Segment ID as a String.