net.talvi.puffinplot.data
Class Vec3

java.lang.Object
  extended by net.talvi.puffinplot.data.Vec3

public class Vec3
extends java.lang.Object

An immutable three-dimensional cartesian vector. The class contains many methods for manipulating vectors and collections of vectors.


Field Summary
static Vec3 DOWN
          a unit vector pointing down
static Vec3 EAST
          a unit vector pointing east
static Vec3 NORTH
          a unit vector pointing north
static Vec3 ORIGIN
          the origin vector (zero along each axis)
 double x
          the x component of the vector
 double y
          the y component of the vector
 double z
          the z component of the vector
 
Constructor Summary
Vec3(double x, double y, double z)
          Creates a vector with the specified components.
 
Method Summary
 Vec3 addDecRad(double angle)
          Returns a new vector equal to this vector with the specified angle added to the declination.
 Vec3 addIncRad(double angle)
          Returns a new vector equal to this vector with the specified angle added to the inclination.
 double angleTo(Vec3 v)
          Returns the angle between this vector and another vector.
 Vec3 correctForm(double az, double dip)
          Applies a sample correction to this vector.
 Vec3 correctSample(double az, double dip)
          Applies a sample correction to this vector.
 Vec3 cross(Vec3 v)
          Returns the cross product of this vector and another vector.
 Vec3 divideBy(double a)
          Divides this vector by a scalar value.
 Vec3 divideBy(Vec3 v)
          Divides the components of this vector individually by the corresponding components of another vector.
 double dot(Vec3 v)
          Returns the dot product of this vector and another vector.
static Vec3 equatorPoint(Vec3 v0, Vec3 v1)
          Returns the unit vector on the intersection of the equator (z=0 line) and the great circle between the supplied points.
static Vec3 fromPolarDegrees(double mag, double inc, double dec)
          Creates a vector from a polar specification in degrees.
static Vec3 fromPolarRadians(double mag, double inc, double dec)
          Creates a vector from a polar specification in radians.
 double getComponent(MeasurementAxis component)
          Returns a specified component of this vector.
 double getDecDeg()
          Returns this vector's declination in degrees.
 double getDecRad()
          Returns this vector's declination in radians.
static double[][] getFormationCorrectionMatrix(double az, double dip)
          Returns a matrix to correct a vector for a given formation orientation.
 double getIncDeg()
          Returns this vector's inclination in degrees.
 double getIncRad()
          Returns this vector's inclination in radians.
static double[][] getSampleCorrectionMatrix(double az, double dip)
          Returns a matrix to correct a vector for a given sample orientation.
 java.util.List<Vec3> greatCirclePoints(int n, boolean closed)
          Returns a list of equally spaced points around a great circle having this vector as its pole.
static java.util.List<java.util.List<Vec3>> interpolateEquatorPoints(java.util.List<Vec3> vs)
          Given a list of points, return a a list of lists containing the same points plus possible extras.
 Vec3 invert()
          Returns the inverse of this vector.
 double mag()
          Returns the magnitude of this vector.
static java.util.List<Vec3> makeEllipse(KentParams kentParams)
          Returns a list of points outlining the confidence ellipse for a supplied set of Kent statistical parameters.
 java.util.List<Vec3> makeSmallCircle(double radiusDegrees)
          Returns a list of vectors defining a small circle around this vector's direction.
static Vec3 mean(java.util.Collection<Vec3> vectors)
          Returns the mean of a collection of vectors.
static Vec3 meanDirection(java.util.Collection<Vec3> points)
          Returns the mean direction of a collection of unit vectors.
 Vec3 minus(Vec3 v)
          Subtracts another vector from this vector.
 Vec3 nearestOnCircle(Vec3 v)
          Using the enclosing vector to define the pole of a great circle G, this method accepts another unit vector v and returns the nearest unit vector to v which lies on G.
 Vec3 normalize()
          Normalizes this vector.
 Matrix oTensor()
          Returns the orientation tensor of this vector.
 Vec3 plus(Vec3 v)
          Adds this vector and another vector.
 Vec3 rot180(MeasurementAxis axis)
          Rotates the vector by180 degrees about the specified axis.
 Vec3 rotY(double angle)
          Rotates this vector about the y axis.
 Vec3 rotZ(double angle)
          Rotates this vector about the z axis.
 boolean sameHemisphere(Vec3 v)
          Returns true if and only if the supplied vector is in the same (upper/lower) hemisphere as this one.
 Vec3 setX(double newX)
          Sets the x component of this vector.
 Vec3 setY(double newY)
          Sets the y component of this vector.
 Vec3 setZ(double newZ)
          Sets the z component of this vector.
static java.util.List<Vec3> spherInterpDir(Vec3 v0, Vec3 v1, Vec3 onPath, double stepSize)
          Interpolates a great-circle path in a chosen direction between two specified vectors.
static java.util.List<Vec3> spherInterpolate(Vec3 v0, Vec3 v1, double stepSize)
          Given two vectors, interpolates unit vectors along a great circle.
static Vec3 sum(java.util.Collection<Vec3> vectors)
          Returns the sum of a specified collection of vectors.
 Vec3 times(double a)
          Multiplies this vector by a scalar value.
 Vec3 times(Vec3 v)
          Multiplies the components of this vector individually by the corresponding components of another vector.
 java.lang.String toString()
          Returns a string representation of this vector.
 Vec3 transform(double[][] matrix)
          Multiplies this vector by a supplied matrix.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

x

public final double x
the x component of the vector


y

public final double y
the y component of the vector


z

public final double z
the z component of the vector


ORIGIN

public static final Vec3 ORIGIN
the origin vector (zero along each axis)


NORTH

public static final Vec3 NORTH
a unit vector pointing north


EAST

public static final Vec3 EAST
a unit vector pointing east


DOWN

public static final Vec3 DOWN
a unit vector pointing down

Constructor Detail

Vec3

public Vec3(double x,
            double y,
            double z)
Creates a vector with the specified components.

Parameters:
x - the x component of the new vector
y - the y component of the new vector
z - the z component of the new vector
Method Detail

addDecRad

public Vec3 addDecRad(double angle)
Returns a new vector equal to this vector with the specified angle added to the declination.

Parameters:
angle - the angle in radians to add to the declination
Returns:
a new vector equal to this vector with the specified angle added to the declination

addIncRad

public Vec3 addIncRad(double angle)
Returns a new vector equal to this vector with the specified angle added to the inclination.

Parameters:
angle - the angle in radians to add to the inclination
Returns:
a new vector equal to this vector with the specified angle added to the inclination

rot180

public Vec3 rot180(MeasurementAxis axis)
Rotates the vector by180 degrees about the specified axis. Since x is up in magnetometer co-ordinates, specifying the x axis corrects the data for a specimen placed in the magnetometer back-to-front.

Parameters:
axis - the axis about which to rotate
Returns:
a new vector equal to this vector rotated 180° about the specified axis

equatorPoint

public static Vec3 equatorPoint(Vec3 v0,
                                Vec3 v1)
Returns the unit vector on the intersection of the equator (z=0 line) and the great circle between the supplied points.

Parameters:
v0 - a vector specifying a direction
v1 - a vector specifying a direction
Returns:
a unit vector v for which v.z==0, which lies on the shortest great-circle path between the normalizations of v0 and v1

sameHemisphere

public boolean sameHemisphere(Vec3 v)
Returns true if and only if the supplied vector is in the same (upper/lower) hemisphere as this one.

Parameters:
v - a vector
Returns:
true if and only if the supplied vector is in the same (upper/lower) hemisphere as this one.

interpolateEquatorPoints

public static java.util.List<java.util.List<Vec3>> interpolateEquatorPoints(java.util.List<Vec3> vs)
Given a list of points, return a a list of lists containing the same points plus possible extras. Each sublist of the returned list is guaranteed only to contain points in one hemisphere. Where the original list crosses the equator, an extra point is interpolated exactly on the equator.

Parameters:
vs - a list of vectors specifying directions
Returns:
a list of lists of vectors which in sequence define the same path as vs; none of the sub-lists crosses the equator

spherInterpolate

public static java.util.List<Vec3> spherInterpolate(Vec3 v0,
                                                    Vec3 v1,
                                                    double stepSize)
Given two vectors, interpolates unit vectors along a great circle. Uses Shoemake's Slerp algorithm.

Parameters:
v0 - a vector
v1 - a vector
stepSize - the step size for interpolation in radians
Returns:
a set of vectors describing a great-circle path between v0 and v1

spherInterpDir

public static java.util.List<Vec3> spherInterpDir(Vec3 v0,
                                                  Vec3 v1,
                                                  Vec3 onPath,
                                                  double stepSize)
Interpolates a great-circle path in a chosen direction between two specified vectors. Of the two possible arcs, the result will be the arc which passes closer to onPath.

Parameters:
v0 - a vector
v1 - a vector
onPath - arc direction indicator
stepSize -
Returns:
a list of points defining a great-circle arc between v0 and v1, passing as close as possible to onPath

rotY

public Vec3 rotY(double angle)
Rotates this vector about the y axis.

Parameters:
angle - an angle in radians
Returns:
a new vector equal to this vector rotated angle radians about the y axis

rotZ

public Vec3 rotZ(double angle)
Rotates this vector about the z axis.

Parameters:
angle - an angle in radians
Returns:
a new vector equal to this vector rotated angle radians about the z axis

getSampleCorrectionMatrix

public static double[][] getSampleCorrectionMatrix(double az,
                                                   double dip)
Returns a matrix to correct a vector for a given sample orientation.

Parameters:
az - the sample dip azimuth in radians
dip - the sample dip angle in radians
Returns:
a matrix to transform vectors from sample co-ordinates to geographic co-ordinates

correctSample

public Vec3 correctSample(double az,
                          double dip)
Applies a sample correction to this vector. This transforms the data from sample (laboratory) co-ordinates to geographic (field) co-ordinates.

Parameters:
az - the sample dip azimuth in radians
dip - the sample dip angle in radians
Returns:
this vector, transformed from sample co-ordinates to geographic co-ordinates

correctForm

public Vec3 correctForm(double az,
                        double dip)
Applies a sample correction to this vector. This transforms the data from geographic (field) co-ordinates to tectonic (pre-tilting) co-ordinates.

Parameters:
az - the formation dip azimuth in radians
dip - the formation dip angle in radians
Returns:
this vector, transformed from geographic co-ordinates to tectonic co-ordinates

getFormationCorrectionMatrix

public static double[][] getFormationCorrectionMatrix(double az,
                                                      double dip)
Returns a matrix to correct a vector for a given formation orientation.

Parameters:
az - the formation dip azimuth in radians
dip - the formation dip angle in radians
Returns:
a matrix to transform vectors from geographic co-ordinates to tectonic co-ordinates

greatCirclePoints

public java.util.List<Vec3> greatCirclePoints(int n,
                                              boolean closed)
Returns a list of equally spaced points around a great circle having this vector as its pole. Assumes that this is a unit vector.

Parameters:
n - number of points to return
closed - if true, first point will also be appended to end of list, giving n+1 points, but only n unique ones, creating a closed circle.
Returns:
list of points on great circle

transform

public Vec3 transform(double[][] matrix)
Multiplies this vector by a supplied matrix.

Parameters:
matrix - a three-by-three matrix
Returns:
the product of this vector and the supplied matrix

nearestOnCircle

public Vec3 nearestOnCircle(Vec3 v)
Using the enclosing vector to define the pole of a great circle G, this method accepts another unit vector v and returns the nearest unit vector to v which lies on G. Algorithm from McFadden and McElhinny 1988, p. 165.

Parameters:
v - a unit vector
Returns:
the nearest point to v which lies on this great circle

normalize

public Vec3 normalize()
Normalizes this vector.

Returns:
a unit vector with the same direction as this vector

getComponent

public double getComponent(MeasurementAxis component)
Returns a specified component of this vector.

Parameters:
component - the component to return
Returns:
the value of the specified component

mag

public double mag()
Returns the magnitude of this vector.

Returns:
the magnitude of this vector

plus

public Vec3 plus(Vec3 v)
Adds this vector and another vector.

Parameters:
v - a vector
Returns:
a vector equal to the sum of this vector and v

minus

public Vec3 minus(Vec3 v)
Subtracts another vector from this vector.

Parameters:
v - a vector
Returns:
a vector equal to this vector minus v

times

public Vec3 times(double a)
Multiplies this vector by a scalar value.

Parameters:
a - a number
Returns:
a vector equal to this vector multiplied by a

times

public Vec3 times(Vec3 v)
Multiplies the components of this vector individually by the corresponding components of another vector. Note that this is neither the dot nor cross product, and is seldom used.

Parameters:
v - a vector
Returns:
a vector with the elements (this.x*v.x, this.y*v.y, this.z*v.z)

divideBy

public Vec3 divideBy(double a)
Divides this vector by a scalar value.

Parameters:
a - a number
Returns:
a vector equal to this vector divided by a

divideBy

public Vec3 divideBy(Vec3 v)
Divides the components of this vector individually by the corresponding components of another vector.

Parameters:
v - a vector
Returns:
a vector with the elements (this.x/v.x, this.y/v.y, this.z/v.z)

dot

public double dot(Vec3 v)
Returns the dot product of this vector and another vector.

Parameters:
v - a vector
Returns:
the dot product of this vector and v

cross

public Vec3 cross(Vec3 v)
Returns the cross product of this vector and another vector.

Parameters:
v - a vector
Returns:
the cross product of this vector and v

invert

public Vec3 invert()
Returns the inverse of this vector. This is produced by negating each component.

Returns:
the inverse of this vector

oTensor

public Matrix oTensor()
Returns the orientation tensor of this vector. The orientation tensor is defined in Scheidegger (1965).

Returns:
the orientation tensor of this vector

angleTo

public double angleTo(Vec3 v)
Returns the angle between this vector and another vector.

Parameters:
v - a vector
Returns:
the angle between this vector and v

fromPolarDegrees

public static Vec3 fromPolarDegrees(double mag,
                                    double inc,
                                    double dec)
Creates a vector from a polar specification in degrees.

Parameters:
mag - magnitude for the new vector
inc - inclination for the new vector, in degrees
dec - declination for the new vector, in degrees
Returns:
the specified vector

fromPolarRadians

public static Vec3 fromPolarRadians(double mag,
                                    double inc,
                                    double dec)
Creates a vector from a polar specification in radians.

Parameters:
mag - magnitude for the new vector
inc - inclination for the new vector, in radians
dec - declination for the new vector, in radians
Returns:
the specified vector

getIncRad

public double getIncRad()
Returns this vector's inclination in radians.

Returns:
this vector's inclination in radians

getDecRad

public double getDecRad()

Returns this vector's declination in radians.

Returns:
this vector's declination in radians

getIncDeg

public double getIncDeg()
Returns this vector's inclination in degrees.

Returns:
this vector's inclination in degrees

getDecDeg

public double getDecDeg()
Returns this vector's declination in degrees.

Returns:
this vector's declination in degrees

sum

public static Vec3 sum(java.util.Collection<Vec3> vectors)
Returns the sum of a specified collection of vectors.

Parameters:
vectors - a collections of vectors
Returns:
the sum of the supplied vectors

meanDirection

public static Vec3 meanDirection(java.util.Collection<Vec3> points)
Returns the mean direction of a collection of unit vectors.

Parameters:
points - a collection of unit vectors
Returns:
a unit vector representing the mean direction of points

mean

public static Vec3 mean(java.util.Collection<Vec3> vectors)
Returns the mean of a collection of vectors.

Parameters:
vectors - a collections of vectors
Returns:
the mean vector of the supplied vectors

setX

public Vec3 setX(double newX)
Sets the x component of this vector.

Parameters:
newX - the new value for the x component
Returns:
a vector with the specified x component, and with the other components taken from this vector

setY

public Vec3 setY(double newY)
Sets the y component of this vector.

Parameters:
newY - the new value for the y component
Returns:
a vector with the specified y component, and with the other components taken from this vector

setZ

public Vec3 setZ(double newZ)
Sets the z component of this vector.

Parameters:
newZ - the new value for the z component
Returns:
a vector with the specified z component, and with the other components taken from this vector

makeSmallCircle

public java.util.List<Vec3> makeSmallCircle(double radiusDegrees)
Returns a list of vectors defining a small circle around this vector's direction.

Parameters:
radiusDegrees - the radius of the desired circle, in degrees
Returns:
a list of vectors defining a small circle around this vector's direction

makeEllipse

public static java.util.List<Vec3> makeEllipse(KentParams kentParams)
Returns a list of points outlining the confidence ellipse for a supplied set of Kent statistical parameters.

Parameters:
kentParams - a set of Kent parameters
Returns:
the confidence ellipse of the supplied parameters

toString

public java.lang.String toString()
Returns a string representation of this vector.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this vector