Vector3 (CML Euclid 2.9 API)

java.lang.Object
- org.xmlcml.euclid.Vector3

All Implemented Interfaces:

EuclidConstants
```
public class Vector3
extends Object
implements EuclidConstants
```
3-dimensional vector A vector has thre components giving it a length and a direction (whose sign is important),but no position. Vectors are often normalised to unit length.
Vectors and points are very closely related and some people use them interchangeably. A Point3 has a position and cannot be normalised. In very many routines, however, Vectors and Points can either be used interchangeably, or there are equivalent routines or they can be converted using cross-constructors. (They cannot be interconverted through casts).
The default vector is 0.0, 0.0, 0.0. Some operations on this will result in ZerolengthVector Exceptions.

Author:

(C) P. Murray-Rust, 1996

Field Summary

Fields
Modifier and Type Field and Description

static Vector3 XV
X axis

static Vector3 YV
Y axis

static Vector3 ZEROV
zero-length vector

static Vector3 ZV
Z axis
- Fields inherited from interface org.xmlcml.euclid.EuclidConstants
  C_AMP, C_APOS, C_ATSIGN, C_BACKSLASH, C_BACKSPACE, C_CARET, C_COLON, C_COMMA, C_DEL, C_DOLLAR, C_EQUALS, C_FORMFEED, C_HASH, C_LANGLE, C_LBRAK, C_LCURLY, C_LSQUARE, C_MINUS, C_NBSP, C_NEWLINE, C_NL, C_PERCENT, C_PERIOD, C_PIPE, C_PLUS, C_POUND, C_QUERY, C_QUOT, C_RANGLE, C_RBRAK, C_RCURLY, C_RETURN, C_RSQUARE, C_SEMICOLON, C_SHRIEK, C_SLASH, C_SPACE, C_STAR, C_TAB, C_TILDE, C_UNDER, EPS, F_S, NONWHITEPUNC, NONWHITEPUNC0, NONWHITEPUNC0REGEX, ONE_THIRD, PUNC, S_AMP, S_APOS, S_ATSIGN, S_BACKSLASH, S_CARET, S_COLON, S_COMMA, S_DOLLAR, S_EMPTY, S_EQUALS, S_FORMFEED, S_HASH, S_LANGLE, S_LBRAK, S_LCURLY, S_LSQUARE, S_MINUS, S_NEWLINE, S_NL, S_PERCENT, S_PERIOD, S_PIPE, S_PLUS, S_POUND, S_QUERY, S_QUOT, S_RANGLE, S_RBRAK, S_RCURLY, S_RETURN, S_RSQUARE, S_SEMICOLON, S_SHRIEK, S_SLASH, S_SPACE, S_STAR, S_TAB, S_TILDE, S_UNDER, S_WHITEREGEX, TWO_THIRDS, U_S, WHITESPACE

Fields
Modifier and Type	Field and Description
`static Vector3`	`XV` X axis
`static Vector3`	`YV` Y axis
`static Vector3`	`ZEROV` zero-length vector
`static Vector3`	`ZV` Z axis

Constructor Summary

Constructors
Constructor and Description
`Vector3()` null constructor
`Vector3(Axis.Axis3 axis)` axial unit vector constructor.
`Vector3(double[] array)` construct from vector components.
`Vector3(double x, double y, double z)` construct from vector components.
`Vector3(Point3 p)` make a vector from a point vector is from origin to point
`Vector3(RealArray f)` copy constructor from RealArray.
`Vector3(Vector3 v)` copy constructor:

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Vector3`	`clone(Point3 p)` from Point3 vector is from origin to point
`Vector3`	`clone(Vector3 v)` copy constructor: synonym for copy constructor
`Vector3`	`cross(Vector3 v3)` create cross product.
`protected double`	`dot(double[] v3)` dot product - protected
`double`	`dot(Vector3 v3)` create dot product.
`double`	`elementAt(int n)` get component.
`Angle`	`getAngleMadeWith(Vector3 v2)` calculate unsigned angle between vectors result = angle between this and v2 uses acos(this.dot.v2) so angle is unsigned does not alter this.
`double[]`	`getArray()` get the vector components
`double`	`getLength()` return vector length.
`Vector3`	`getNonColinearVector()` get any vector not colinear with this.
`Vector3`	`getPerpendicularVector()` get any vector perpendicular to this.
`double`	`getScalarTripleProduct(Vector3 v2, Vector3 v3)` calculate scalar triple product between vectors.
`Vector3`	`getUnitVector()` get normalized vector.
`boolean`	`isColinearVector(Vector3 v)` are two vectors colinear.
`boolean`	`isEqualTo(Vector3 v)` are two vectors equal lengths.
`boolean`	`isIdenticalTo(Vector3 v)` are two vectors equal in all components.
`boolean`	`isZero()` is vector of zero length.
`boolean`	`longerThan(Vector3 v)` vector length > vector length
`Vector3`	`multiplyBy(double f)` scalar multiplication.
`void`	`multiplyEquals(double f)` scalar multiplication.
`Vector3`	`negative()` negative of vector.
`Vector3`	`negativeEquals()` negative of vector.
`Vector3`	`normalise()` Deprecated. (use normalize())
`Vector3`	`normalize()` normalize vector.
`Vector3`	`plus(Vector3 v3)` vector addition.
`void`	`plusEquals(Vector3 v3)` vector addition.
`Vector3`	`projectOnto(Vector3 v)` projection of this onto vector.
`Vector3`	`round()` sets vector components to nearest integer value.
`void`	`setElementAt(int n, double f)` set component.
`Vector3`	`subtract(Vector3 v3)` vector subtraction.
`void`	`subtractEquals(Vector3 v3)` vector subtraction.
`String`	`toString()` get string representation.
`Vector3`	`transform(Transform3 t)` create transformed vector.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ZEROV
```
public static final Vector3 ZEROV
```
    zero-length vector
  - XV
```
public static final Vector3 XV
```
    X axis
  - YV
```
public static final Vector3 YV
```
    Y axis
  - ZV
```
public static final Vector3 ZV
```
    Z axis
- Constructor Detail
  - Vector3
```
public Vector3()
```
    null constructor
  - Vector3
```
public Vector3(double x,
               double y,
               double z)
```
    construct from vector components.
    
    Parameters:
    
    x - component
    
    y - component
    
    z - component
  - Vector3
```
public Vector3(double[] array)
        throws EuclidRuntimeException
```
    construct from vector components.
    
    Parameters:
    
    array - components
    
    Throws:
    
    EuclidRuntimeException
  - Vector3
```
public Vector3(Axis.Axis3 axis)
```
    axial unit vector constructor. unit vectors along X, Y, Z axes
    
    Parameters:
    
    axis - to use
  - Vector3
```
public Vector3(Vector3 v)
```
    copy constructor:
    
    Parameters:
    
    v - vector to copy
  - Vector3
```
public Vector3(RealArray f)
        throws EuclidRuntimeException
```
    copy constructor from RealArray.
    
    Parameters:
    
    f - the array (of length 3)
    
    Throws:
    
    EuclidRuntimeException
  - Vector3
```
public Vector3(Point3 p)
```
    make a vector from a point vector is from origin to point
    
    Parameters:
    
    p - the point
- Method Detail
  - clone
```
public Vector3 clone(Vector3 v)
```
    copy constructor: synonym for copy constructor
    
    Parameters:
    
    v - vector to copy
    
    Returns:
    
    vector
  - clone
```
public Vector3 clone(Point3 p)
```
    from Point3 vector is from origin to point
    
    Parameters:
    
    p - the point
    
    Returns:
    
    vector
  - getArray
```
public double[] getArray()
```
    get the vector components
    
    Returns:
    
    vector of length 3
  - isEqualTo
```
public boolean isEqualTo(Vector3 v)
```
    are two vectors equal lengths. uses Real.isEqual
    
    Parameters:
    
    v -
    
    Returns:
    
    equal if length difference is within tolerance
  - longerThan
```
public boolean longerThan(Vector3 v)
```
    vector length > vector length
    
    Parameters:
    
    v - vector to compare
    
    Returns:
    
    true if this > vector
  - multiplyBy
```
public Vector3 multiplyBy(double f)
```
    scalar multiplication. create new vector vector = this*f does not alter this
    
    Parameters:
    
    f - multiplier for all components
    
    Returns:
    
    scaled vector
  - multiplyEquals
```
public void multiplyEquals(double f)
```
    scalar multiplication. sets equal to this*f alters this
    
    Parameters:
    
    f - multiplier for all components
  - plus
```
public Vector3 plus(Vector3 v3)
```
    vector addition. create new vector result = this + v3 does not alter this
    
    Parameters:
    
    v3 - vector to add
    
    Returns:
    
    resultant vector
  - plusEquals
```
public void plusEquals(Vector3 v3)
```
    vector addition. sets equal to this + v3 alters this
    
    Parameters:
    
    v3 - vector to subtract
  - subtract
```
public Vector3 subtract(Vector3 v3)
```
    vector subtraction. create new vector result = this - v3 does not alter this
    
    Parameters:
    
    v3 - vector to subtract
    
    Returns:
    
    resultant vector
  - subtractEquals
```
public void subtractEquals(Vector3 v3)
```
    vector subtraction. sets equal to this - v3 alters this
    
    Parameters:
    
    v3 - vector to subtract
  - negative
```
public Vector3 negative()
```
    negative of vector. result = -this does not alter this
    
    Returns:
    
    resultant vector
  - negativeEquals
```
public Vector3 negativeEquals()
```
    negative of vector. result = - DOES alter this
    
    Returns:
    
    resultant vector
  - elementAt
```
public double elementAt(int n)
                 throws EuclidRuntimeException
```
    get component. use raw array if you are sure checking is not required
    
    Parameters:
    
    n - the zero-based index
    
    Returns:
    
    the n'th component
    
    Throws:
    
    EuclidRuntimeException
  - setElementAt
```
public void setElementAt(int n,
                         double f)
                  throws EuclidRuntimeException
```
    set component.
    
    Parameters:
    
    n - the zero-based index
    
    f - component value
    
    Throws:
    
    EuclidRuntimeException
  - isIdenticalTo
```
public boolean isIdenticalTo(Vector3 v)
```
    are two vectors equal in all components. uses Real.isEqual
    
    Parameters:
    
    v -
    
    Returns:
    
    equal if components equal within tolerance
  - isZero
```
public boolean isZero()
```
    is vector of zero length. uses Real.isEqual
    
    Returns:
    
    if zero within tolerance
  - transform
```
public Vector3 transform(Transform3 t)
```
    create transformed vector. does not alter this.
    
    Parameters:
    
    t - transform
    
    Returns:
    
    tranformed vector
  - cross
```
public Vector3 cross(Vector3 v3)
```
    create cross product. result = this x v3 does not alter this.
    
    Parameters:
    
    v3 - vector to multiply
    
    Returns:
    
    cross product
  - round
```
public Vector3 round()
```
    sets vector components to nearest integer value. useful for crystallography and other grids uses Math.round(); ALTERS THIS
    
    Returns:
    
    vector with integer components
  - normalize
```
public Vector3 normalize()
```
    normalize vector. alters this this = this.normalize() if zero vector takes no action (maybe this is bad...)
    
    Returns:
    
    vector of unit length
  - normalise
```
public Vector3 normalise()
```
    Deprecated. (use normalize())
    
    normalize vector. alters this this = this.normalize() if zero vector takes no action (maybe this is bad...)
    
    Returns:
    
    vector of unit length
  - getUnitVector
```
public Vector3 getUnitVector()
```
    get normalized vector. does not alter this result = this.normalize() if zero vector takes no action (maybe this is bad...)
    
    Returns:
    
    vector of unit length
  - getLength
```
public double getLength()
```
    return vector length. does not alter this result = this.length()
    
    Returns:
    
    vector length
  - dot
```
public double dot(Vector3 v3)
```
    create dot product. result = this . v3 does not alter this.
    
    Parameters:
    
    v3 - vector to multiply
    
    Returns:
    
    dot product
  - dot
```
protected double dot(double[] v3)
```
    dot product - protected
    
    Parameters:
    
    v3 -
    
    Returns:
    
    the dotproduct
  - getAngleMadeWith
```
public Angle getAngleMadeWith(Vector3 v2)
```
    calculate unsigned angle between vectors result = angle between this and v2 uses acos(this.dot.v2) so angle is unsigned does not alter this.
    
    Parameters:
    
    v2 - vector to multiply
    
    Returns:
    
    angle (null if vectors zero length
  - getScalarTripleProduct
```
public double getScalarTripleProduct(Vector3 v2,
                                     Vector3 v3)
```
    calculate scalar triple product between vectors. result = this.(v2 x v3) does not alter this.
    
    Parameters:
    
    v2 - vector to multiply
    
    v3 - vector to multiply
    
    Returns:
    
    stp
  - projectOnto
```
public Vector3 projectOnto(Vector3 v)
                    throws EuclidRuntimeException
```
    projection of this onto vector. does not alter this. result = vector.norm() * (this.norm() dot vector.norm())
    
    Parameters:
    
    v - vector to project onto
    
    Returns:
    
    projected vector
    
    Throws:
    
    EuclidRuntimeException - vector or this is zero length
  - isColinearVector
```
public boolean isColinearVector(Vector3 v)
```
    are two vectors colinear. also returns true if one or more vectors are zero
    
    Parameters:
    
    v - vector to test with this
    
    Returns:
    
    true if cross product isZero()
  - getNonColinearVector
```
public Vector3 getNonColinearVector()
```
    get any vector not colinear with this. returns any axis which is not colinear with this
    
    Returns:
    
    either XV or YV (even if this is zero)
  - getPerpendicularVector
```
public Vector3 getPerpendicularVector()
```
    get any vector perpendicular to this. useful for creating cartesian axes containing this
    
    Returns:
    
    vector perpendicular to this (zero if this is zero)
  - toString
```
public String toString()
```
    get string representation.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    string representation

Class Vector3

Field Summary

Fields inherited from interface org.xmlcml.euclid.EuclidConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZEROV

XV

YV

ZV

Constructor Detail

Vector3

Vector3

Vector3

Vector3

Vector3

Vector3

Vector3

Method Detail

clone

clone

getArray

isEqualTo

longerThan

multiplyBy

multiplyEquals

plus

plusEquals

subtract

subtractEquals

negative

negativeEquals

elementAt

setElementAt

isIdenticalTo

isZero

transform

cross

round

normalize

normalise

getUnitVector

getLength

dot

dot

getAngleMadeWith

getScalarTripleProduct

projectOnto

isColinearVector

getNonColinearVector

getPerpendicularVector

toString