org.proteinshader.math
Class Vec3d

java.lang.Object
  org.proteinshader.math.Vec3d

All Implemented Interfaces:

Cloneable

public class Vec3d
extends Object
implements Cloneable

This class is used to create a vector with 3 elements of type double. The Vec3f class is nearly identical, except that it happens to use floats rather than doubles.

Public instances variables are generally discouraged in Java, but can be justified here. The x, y, and z attributes will be used in numerous calculations, and v.x, v.y, and v.z are simply much shorter than v.getX(), v.getY(), and v.getZ(). Also, any value is allowed for an attribute of a Vec3d, so there doesn't seem to be any real advantage to making the xyz-coordinates of this data structure private.

Several of the methods in this class come in two versions: one that modifies the calling vector and one that returns a new vector instead of modifying the calling vector. For example, the add(Vec3d) method adds the respective xyz-values of the calling and argument vectors in order to create a new vector, and the original vectors are not modified. The addToMe(Vec3d) void method, however, modifies the xyz-values of the calling vector by adding to them the xyz-values of the vector given as an argument.

Field Summary

static String	DECIMAL_FORMAT As a convienence for debugging, the toString() method will return a representation of a vector in the general form "(x, y, z)", where the number of decimal places for each value will be determined this decimal format String, which is "0.000".
double	x The public x-coordinate of this three element vector.
double	y The public y-coordinate of this three element vector.
double	z The public z-coordinate of this three element vector.

Constructor Summary

Vec3d()
Constructs a vector of 3 elements {x, y, z} filled with zeros.

Vec3d(double x, double y, double z)
Constructs a vector with three public attributes: x, y, and z.

Method Summary

Vec3d	add(Vec3d vec) Creates a new vector by adding the vector given as an argument to the calling vector (the existing vectors are NOT modified).
void	addToMe(Vec3d vec) Modifies the calling vector by adding the xyz-values of the vector given as an argument to the xyz-values of the calling vector.
Vec3d	clone() Returns a clone of the calling vector.
Vec3d	cross(Vec3d vec) Creates a new vector by taking the cross product of the calling vector and the vector given as an argument.
void	crossMe(Vec3d vec) Modifies the calling vector by calculating the cross product of the calling vector and the vector given as an argument and storing the result in the calling vector.
double	dot(Vec3d vec) Returns the dot product of the calling vector and the vector given as an argument.
double	magnitude() Calculates the magnitude of the calling vector.
Vec3d	minus(Vec3d vec) Creates a new vector by subtracting the vector given as an argument from the calling vector (the existing vectors are NOT modified).
void	minusFromMe(Vec3d vec) The x, y, and z values of the vector given as an argument are subtracted from the x, y, and z values of the calling vector.
Vec3d	negate() Creates a new vector equal in magnitude but opposite in direction to the calling vector (the calling vector is NOT modified).
void	negateMe() The direction of the calling vector is reversed by setting x to -x, y to -y, and z to -z.
Vec3d	normalize() Creates a new vector that has the same direction as the calling vector, but is of unit length (the calling vector is NOT modified).
void	normalizeMe() Normalizes the calling vector by determining its length (magnitude) and then dividing x, y, and z by the length.
Vec3d	scale(double magnitude) Creates a new vector by scaling the calling vector by the magnitude given as an argument (the calling vector is NOT modified).
void	scaleMe(double magnitude) Scales the calling vector by the value given as an argument.
void	setXYZ(double x, double y, double z) Sets the xyz-values of the vector.
void	setXYZ(Vec3d vec) Sets the xyz-values of the vector to the xyz-values of the vector given as an argument.
String	toString() As a convenience for debugging, the toString() method returns the xyz-coordinates of the vector in the form "(x, y, z)".

Methods inherited from class java.lang.Object

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

Field Detail

DECIMAL_FORMAT

public static final String DECIMAL_FORMAT

As a convienence for debugging, the toString() method will return a representation of a vector in the general form "(x, y, z)", where the number of decimal places for each value will be determined this decimal format String, which is "0.000".

See Also:

Constant Field Values

x

public double x

The public x-coordinate of this three element vector.

y

public double y

The public y-coordinate of this three element vector.

z

public double z

The public z-coordinate of this three element vector.

Constructor Detail

Vec3d

public Vec3d()

Constructs a vector of 3 elements {x, y, z} filled with zeros.

Vec3d

public Vec3d(double x,
             double y,
             double z)

Constructs a vector with three public attributes: x, y, and z.

Parameters:

x - the x-coordinate

y - the y-coordinate

z - the z-coordinate

Method Detail

add

public Vec3d add(Vec3d vec)

Creates a new vector by adding the vector given as an argument to the calling vector (the existing vectors are NOT modified).

Parameters:

vec - the vector to add to the calling vector.

Returns:

A new vector equal to the vector given as an argument added to the calling vector.

addToMe

public void addToMe(Vec3d vec)

Modifies the calling vector by adding the xyz-values of the vector given as an argument to the xyz-values of the calling vector.

Parameters:

vec - the vector to add to the calling vector.

clone

public Vec3d clone()

Returns a clone of the calling vector.

The clone is a deep clone (in the sense of being completely independent of the original).

Overrides:

clone in class Object

Returns:

A clone of the calling vector.

cross

public Vec3d cross(Vec3d vec)

Creates a new vector by taking the cross product of the calling vector and the vector given as an argument.

(new vector) = (calling vector) x (argument vector)

If the calling vector and the argument vector are not parallel, then (calling vector), (argument vector), and (new vector) will form a right-handed system.

The commutative rule does not apply to the cross product, so it is important to be aware that 'vecA = v1.cross(v2)' and 'vecB = v2.cross(v1)' do not give the same result. Although vecA and vecB will both be on the same line (a line perpendicular to the plane defined by v1 and v2), vecA and vecB will be facing opposite directions.

The direction of the cross product can be found by using the right-hand rule. Imagine that vecA is on a line perpendicular to the plane defined by v1 and v2, and that theta is the direction of the angle from v1 to v2 (for v1 x v2). To find the direction of vecA, you need to wrap your hand around the imaginary line in such a way that your fingertips are pointing in the same direction as the angle theta and you thumb is resting on the line. Your thumb will be pointing in the direction of vecA, the v1 x v2 cross product.

Parameters:

vec - the second vector in the cross product.

Returns:

The result of the cross product, a vector perpendicular to both the calling vector and the argument vector.

crossMe

public void crossMe(Vec3d vec)

Modifies the calling vector by calculating the cross product of the calling vector and the vector given as an argument and storing the result in the calling vector.

(modified calling vector) = (calling vector) x (argument vector)

If the calling vector and the argument vector are not parallel, then (calling vector), (argument vector), and (modified calling vector) will form a right-handed system.

The cross product is anticommutative: (vec1 x vec2) = -(vec2 x vec1)

The direction of the cross product can be determined using the right-rule, which is explained above in the comments for the cross() method.

Parameters:

vec - the second vector in the cross product.

dot

public double dot(Vec3d vec)

Returns the dot product of the calling vector and the vector given as an argument.

Parameters:

vec - the vector to multiply the calling vector by.

Returns:

The dot product value (a scalar) as a double.

magnitude

public double magnitude()

Calculates the magnitude of the calling vector.

Returns:

The length of the vector.

minus

public Vec3d minus(Vec3d vec)

Creates a new vector by subtracting the vector given as an argument from the calling vector (the existing vectors are NOT modified).

Parameters:

vec - the vector to subtract from the calling vector.

Returns:

A new vector equal to the calling vector minus the vector given as an argument.

minusFromMe

public void minusFromMe(Vec3d vec)

The x, y, and z values of the vector given as an argument are subtracted from the x, y, and z values of the calling vector.

Parameters:

vec - the vector to subtract from the calling vector.

negate

public Vec3d negate()

Creates a new vector equal in magnitude but opposite in direction to the calling vector (the calling vector is NOT modified).

Returns:

The negative of the calling vector.

negateMe

public void negateMe()

The direction of the calling vector is reversed by setting x to -x, y to -y, and z to -z.

normalize

public Vec3d normalize()

Creates a new vector that has the same direction as the calling vector, but is of unit length (the calling vector is NOT modified). If the calling vector is the zero vector, then normalization cannot be done (so the vector returned will still have length 0.0).

Returns:

The new vector of length 1.

normalizeMe

public void normalizeMe()

Normalizes the calling vector by determining its length (magnitude) and then dividing x, y, and z by the length. If the calling vector is the zero vector, then it cannot be normalized, so the zero vector will remain unchanged.

scale

public Vec3d scale(double magnitude)

Creates a new vector by scaling the calling vector by the magnitude given as an argument (the calling vector is NOT modified).

Parameters:

magnitude - the scalar to multiple the vector by.

Returns:

A new vector equal to the calling vector scaled by the magnitude argument.

scaleMe

public void scaleMe(double magnitude)

Scales the calling vector by the value given as an argument.

Parameters:

magnitude - the scalar to multiple the vector by.

setXYZ

public void setXYZ(double x,
                   double y,
                   double z)

Sets the xyz-values of the vector.

Parameters:

x - the x-coordinate

y - the y-coordinate

z - the z-coordinate

setXYZ

public void setXYZ(Vec3d vec)

Sets the xyz-values of the vector to the xyz-values of the vector given as an argument.

Parameters:

vec - the vector to copy xyz-values from.

toString

public String toString()

As a convenience for debugging, the toString() method returns the xyz-coordinates of the vector in the form "(x, y, z)". The number of digits after the decimal place will be determined by the DECIMAL_FORMAT constant for this class.

Overrides:

toString in class Object

Returns:

A String representation of this vector.