Vec3

java.lang.Object
- 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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`Vec3(double x, double y, double z)` Creates a vector with the specified components.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 signed 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.
`double`	`distance(Vec3 v)` Returns the distance between two vectors.
`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.
`boolean`	`equals(java.lang.Object o)`
`boolean`	`equals(Vec3 v, double precision)` Compares vectors for equality to a specified precision.
`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.
`double`	`getDipDeg()` Returns the strike of the plane normal this vector
`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.
`double`	`getStrikeDeg()` Returns the strike of the plane normal to this vector
`static double[][]`	`getZRotationMatrix(double angle)` Returns a matrix for a rotation about the z axis.
`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.
`int`	`hashCode()`
`static java.util.List<java.util.List<Vec3>>`	`interpolateEquatorPoints(java.util.List<Vec3> vs)` Given a list of points, return a list of lists containing the same points plus possible extras.
`Vec3`	`invert()` Returns the inverse of this vector.
`boolean`	`isFinite()` Checks that this vector contains no NaN or infinite values.
`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.
`Jama.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 by 180 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 path between them.
`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, finalize, getClass, 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 by 180 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. If an axis other than X, Y, or Z is specified, the original vector is returned.
    
    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. The supplied vectors must be finite. and in opposite hemispheres.
    
    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. Currently, the dividing place between the hemispheres (i.e. the plane defined by z=0) is treated as distinct from either hemisphere: that is, v1.sameHemisphere(v2) is true for any two points in this plane, but false if either point is anywhere outside this plane.
    
    Parameters:
    
    v - a non-null, finite vector
    
    Returns:
    
    true if and only if the supplied vector is in the same (upper/lower) hemisphere as this one.
    
    Throws:
    
    java.lang.IllegalArgumentException - if v is not finite
    
    java.lang.NullPointerException - if v is null
  - interpolateEquatorPoints
```
public static java.util.List<java.util.List<Vec3>> interpolateEquatorPoints(java.util.List<Vec3> vs)
```
    Given a list of points, return 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 path between them. The input vectors do not have to be unit vectors, but only their directions are considered. Interpolation is performed using Shoemake's Slerp algorithm.
    
    Parameters:
    
    v0 - a non-null, non-zero, finite vector
    
    v1 - a non-null, non-zero, finite vector
    
    stepSize - the step size for interpolation in radians, in the range (0, 2*PI)
    
    Returns:
    
    a set of vectors describing a great-circle path between v0 and v1
    
    Throws:
    
    java.lang.NullPointerException - if either of the input vectors is null
    
    java.lang.IllegalArgumentException - if any of the arguments are outside the specified ranges
  - 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. The supplied step size is only used as a guideline; the actual step size may at certain positions drop to 0 (i.e. a point is repeated) or increase to as much as 1.8*stepSize.
    
    Parameters:
    
    v0 - a non-null, non-zero, finite vector giving the first end-point of the arc
    
    v1 - a non-null, non-zero, finite vector giving the second end-point of the arc
    
    onPath - a non-null, non-zero, finite vector indicating the direction of the arc
    
    stepSize - approximate size of interpolation step in radians, in the range (0, 2*PI)
    
    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. The rotation direction is clockwise as viewed from above (i.e. from (0, 0, -∞). For example, rotZ(π/2) called on the eastward-pointing vector (0, 1, 0) would produce the southward-pointing vector (-1, 0, 0).
    
    Parameters:
    
    angle - an angle in radians
    
    Returns:
    
    a new vector equal to this vector rotated angle radians about the z axis
  - getZRotationMatrix
```
public static double[][] getZRotationMatrix(double angle)
```
    Returns a matrix for a rotation about the z axis. The rotation direction is clockwise as viewed from above (i.e. from (0, 0, -∞). For example, getZRotationMatrix(π/2) applied to the eastward-pointing vector (0, 1, 0) would produce the southward-pointing vector (-1, 0, 0).
    
    Parameters:
    
    angle - an angle in radians
    
    Returns:
    
    a matrix which rotates 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
  - 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
  - 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
  - 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. If this vector contains any non-finite components, the result of this method is undefined, but it will not throw an exception.
    
    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 product nor the 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 Jama.Matrix oTensor()
```
    Returns the orientation tensor of this vector. The orientation tensor is defined in Scheidegger, A E. (1965). On the statistics of the orientation of bedding planes, grain axes, and similar sedimentological data. US Geological Survey Professional Paper, 525, pp. 164–167
    
    Returns:
    
    the orientation tensor of this vector
  - angleTo
```
public double angleTo(Vec3 v)
```
    Returns the signed angle between this vector and another vector.
    
    Parameters:
    
    v - a vector
    
    Returns:
    
    the angle between this vector and v, in radians
  - 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
  - getStrikeDeg
```
public double getStrikeDeg()
```
    Returns the strike of the plane normal to this vector
    
    Returns:
    
    the strike of the plane normal to this vector, in degrees
  - getDipDeg
```
public double getDipDeg()
```
    Returns the strike of the plane normal this vector
    
    Returns:
    
    the strike of the plane normal this vector, 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
  - isFinite
```
public boolean isFinite()
```
    Checks that this vector contains no NaN or infinite values.
    
    Returns:
    
    true iff this vector contains no NaN or infinite values
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - distance
```
public double distance(Vec3 v)
```
    Returns the distance between two vectors.
    
    Parameters:
    
    v - the vector with which to compare this one
    
    Returns:
    
    the distance between this vector and v
  - equals
```
public boolean equals(Vec3 v,
                      double precision)
```
    Compares vectors for equality to a specified precision. Compares this vector with another one, returning true if they are sufficiently close. "Sufficiently close" is defined by a supplied precision parameter: for the method to return true, the distance between the vectors must be less than precision * max(m1, m2) where m1 and m2 are the lengths of the two vectors.
    
    Parameters:
    
    v - the vector with which to compare this one
    
    precision - the precision parameter for the comparison
    
    Returns:
    
    true iff the vectors are equal to within the specified precision

Class Vec3

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

x

y

z

ORIGIN

NORTH

EAST

DOWN

Constructor Detail

Vec3

Method Detail

addDecRad

addIncRad

rot180

equatorPoint

sameHemisphere

interpolateEquatorPoints

spherInterpolate

spherInterpDir

rotY

rotZ

getZRotationMatrix

getSampleCorrectionMatrix

correctSample

correctForm

greatCirclePoints

getFormationCorrectionMatrix

transform

nearestOnCircle

normalize

getComponent

mag

plus

minus

times

times

divideBy

divideBy

dot

cross

invert

oTensor

angleTo

fromPolarDegrees

fromPolarRadians

getIncRad

getDecRad

getIncDeg

getDecDeg

getStrikeDeg

getDipDeg

sum

meanDirection

mean

setX

setY

setZ

makeSmallCircle

makeEllipse

toString

isFinite

equals

hashCode

distance

equals