Package net.algart.math.geometry

Class Orthonormal3DBasis

java.lang.Object

net.algart.math.geometry.Orthonormal3DBasis

public final class Orthonormal3DBasis
extends Object

Right orthonormal basis in 3D Euclidean space: 3 orthogonal unit vectors i, j, k.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:

Daniel Alievsky

Field Summary

Fields

Modifier and Type	Field	Description
static final double	COLLINEARITY_EPSILON	While creating a new basis, two vectors are considered to be "almost collinear" if the sine of the angle between them is less or about COLLINEARITY_EPSILON.
static final double	COLLINEARITY_EPSILON_SQR	The square of COLLINEARITY_EPSILON.
static final Orthonormal3DBasis	DEFAULT	Default basis: I=(1,0,0), J=(0,1,0), K=(0,0,1).
static final double	MIN_ALLOWED_LENGTH	Minimal allowed length of the vectors (ix,iy,iz) and (jx,jy,jz), passed to creation methods newBasis(double, double, double, double, double, double, boolean), newSomeBasis(double, double, double).

Method Summary

Modifier and Type	Method	Description
double	distanceSquare(Orthonormal3DBasis other)
boolean	equals(Object o)	Indicates whether some other object is an instance of this class, representing the same basis.
int	hashCode()	Returns the hash code of this object.
Orthonormal3DBasis	inverse()
double	ix()	Returns x-component of i vector.
double	iy()	Returns y-component of i vector.
double	iz()	Returns z-component of i vector.
Orthonormal3DBasis	jki()	Returns new basis (i', j', k'), where i'=j, j'=k, k'=i.
double	jx()	Returns x-component of j vector.
double	jy()	Returns y-component of j vector.
double	jz()	Returns z-component of j vector.
Orthonormal3DBasis	kij()	Returns new basis (i', j', k'), where i'=k, j'=i, k'=j.
double	kx()	Returns x-component of k vector.
double	ky()	Returns y-component of j vector.
double	kz()	Returns z-component of j vector.
static double	length(double x, double y, double z)	Returns the length of 3D segment with the given projections to the axes.
static double	lengthSquare(double x, double y, double z)	Returns the square of the length of 3D segment with the given projections to the axes.
Orthonormal3DBasis	multiply(Orthonormal3DBasis other)
static Orthonormal3DBasis	newBasis(double ix, double iy, double iz, double jx, double jy, double jz, boolean exceptionOnCollinearity)	Creates new basis, where i vector has components (ix/d1, iy/d1, iz/d1), d1=sqrt(ix2+iy2+iz2), j vector has components (jx/d2, jy/d2, jz/d2), d2=sqrt(jx2+jy2+jz2), k vector is chosen automatically to provide right orthonormal basis.
static Orthonormal3DBasis	newRandomBasis(RandomGenerator random)	Creates a pseudorandom basis, which orientation is uniformly distributed in the space.
static Orthonormal3DBasis	newRandomBasis(RandomGenerator random, double ix, double iy, double iz)	Creates a pseudorandom basis, where i vector has components (ix/d, iy/d, iz/d), d=sqrt(ix2+iy2+iz2).
static Orthonormal3DBasis	newSomeBasis(double ix, double iy, double iz)	Creates new basis, where i vector has components (ix/d, iy/d, iz/d), d=sqrt(ix2+iy2+iz2).
static Optional<Orthonormal3DBasis>	optBasis(double ix, double iy, double iz, double jx, double jy, double jz)	Analogue of getBasis(ix, iy, iz, jx, jy, jz, true}, but instead of throwing exceptions this method just returns Optional.empty().
Orthonormal3DBasis	rotate(double angleXYInRadians, double angleYZInRadians, double angleZXInRadians)
Orthonormal3DBasis	rotate(double directionX, double directionY, double directionZ, double angle)
Orthonormal3DBasis	rotateIJ(double angleInRadians)
Orthonormal3DBasis	rotateJK(double angleInRadians)
Orthonormal3DBasis	rotateKI(double angleInRadians)
static double	scalarProduct(double ax, double ay, double az, double bx, double by, double bz)	Returns the scalar product of a and b vectors: ax * bx + ay * by + az * bz.
String	toString()	Returns a brief string description of this object.
double	x(double i, double j, double k)	Returns i * ix() + j * jx() + k * kx()
double	y(double i, double j, double k)	Returns i * iy() + j * jy() + k * ky()
double	z(double i, double j, double k)	Returns i * iz() + j * jz() + k * kz()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

COLLINEARITY_EPSILON

public static final double COLLINEARITY_EPSILON

While creating a new basis, two vectors are considered to be "almost collinear" if the sine of the angle between them is less or about COLLINEARITY_EPSILON.

See Also:

• Constant Field Values

COLLINEARITY_EPSILON_SQR

public static final double COLLINEARITY_EPSILON_SQR

The square of COLLINEARITY_EPSILON.

See Also:

• Constant Field Values

MIN_ALLOWED_LENGTH

public static final double MIN_ALLOWED_LENGTH

Minimal allowed length of the vectors (ix,iy,iz) and (jx,jy,jz), passed to creation methods newBasis(double, double, double, double, double, double, boolean), newSomeBasis(double, double, double).

See Also:

• Constant Field Values

DEFAULT

public static final Orthonormal3DBasis DEFAULT

Default basis: I=(1,0,0), J=(0,1,0), K=(0,0,1).

Method Details

newSomeBasis

public static Orthonormal3DBasis newSomeBasis(double ix,
 double iy,
 double iz)

Creates new basis, where i vector has components (ix/d, iy/d, iz/d), d=sqrt(ix²+iy²+iz²). Other vectors j and k will have some values, depending on the implementation.

Parameters:

ix - x-component of new i vector (maybe, multiplied by some d constant).

iy - y-component of new i vector (maybe, multiplied by some d constant).

iz - z-component of new i vector (maybe, multiplied by some d constant).

Returns:

new right orthonormal basis with given direction of i vector.

Throws:

IllegalArgumentException - if the length sqrt(ix²+iy²+iz²) of the passed vector (ix,iy,iz) is zero or too small (< MIN_ALLOWED_LENGTH).

newBasis

public static Orthonormal3DBasis newBasis(double ix,
 double iy,
 double iz,
 double jx,
 double jy,
 double jz,
 boolean exceptionOnCollinearity)
                                   throws CollinearityException

Creates new basis, where i vector has components (ix/d₁, iy/d₁, iz/d₁), d₁=sqrt(ix²+iy²+iz²), j vector has components (jx/d₂, jy/d₂, jz/d₂), d₂=sqrt(jx²+jy²+jz²), k vector is chosen automatically to provide right orthonormal basis.

If the passed vectors (ix,iy,iz) and (jx,jy,jz) are not orthogonal, the vector (jx,jy,jz) is automatically corrected, before all other calculations, to become orthogonal to i, and the plane ij is preserved while this correction.

If the passed vectors are collinear or almost collinear (with very little angle difference, about 10⁻⁸..10⁻⁶ radians or something like this), or if the length of one of the passed vectors is less than MIN_ALLOWED_LENGTH, then behaviour depends on exceptionOnCollinearity argument. If it is true, the method throws CollinearityException. In other case, the method ignores the passed vector (jx,jy,jz) and returns some basis according the passed vector (ix,iy,iz), as newSomeBasis(double, double, double) method.

Parameters:

ix - x-component of new i vector (maybe, multiplied by some d₁ constant).

iy - y-component of new i vector (maybe, multiplied by some d₁ constant).

iz - z-component of new i vector (maybe, multiplied by some d₁ constant).

jx - x-component of new j vector (maybe, multiplied by some d₂ constant).

jy - y-component of new j vector (maybe, multiplied by some d₂ constant).

jz - z-component of new j vector (maybe, multiplied by some d₂ constant).

exceptionOnCollinearity - whether exception is thrown for collinear vector pair.

Returns:

new right orthonormal basis with given direction of i vector and the direction of j vector, chosen according the arguments (see above).

Throws:

IllegalArgumentException - if the length sqrt(ix²+iy²+iz²) of the passed vector (ix,iy,iz) or the length sqrt(jx²+jy²+jz²) of the passed vector (jx,jy,jz) is zero or too small (< MIN_ALLOWED_LENGTH).

CollinearityException - if the passed two vectors are almost collinear and exceptionOnCollinearity==true.

optBasis

public static Optional<Orthonormal3DBasis> optBasis(double ix,
 double iy,
 double iz,
 double jx,
 double jy,
 double jz)

Analogue of getBasis(ix, iy, iz, jx, jy, jz, true}, but instead of throwing exceptions this method just returns Optional.empty().

In other words, this method returns Optional.empty() when the length sqrt(ix²+iy²+iz²) of the passed vector (ix,iy,iz) or the length sqrt(jx²+jy²+jz²) of the passed vector (jx,jy,jz) is zero or too small (< MIN_ALLOWED_LENGTH), and also this method returns Optional.empty() when the passed two vectors are almost collinear. In all other cases, this method is equivalent to Optional.of(getBasis(ix, iy, iz, jx, jy, jz, true/false)) (the last argument is not important). This method never throws any exceptions.

Parameters:

ix - x-component of new i vector (maybe, multiplied by some d₁ constant).

iy - y-component of new i vector (maybe, multiplied by some d₁ constant).

iz - z-component of new i vector (maybe, multiplied by some d₁ constant).

jx - x-component of new j vector (maybe, multiplied by some d₂ constant).

jy - y-component of new j vector (maybe, multiplied by some d₂ constant).

jz - z-component of new j vector (maybe, multiplied by some d₂ constant).

Returns:

new right orthonormal basis with given direction of i vector and the direction of j vector, chosen according the arguments (see newBasis(double, double, double, double, double, double, boolean)), or empty value in a case of problems.

newRandomBasis

public static Orthonormal3DBasis newRandomBasis(RandomGenerator random)

Creates a pseudorandom basis, which orientation is uniformly distributed in the space. The orientation is chosen with help of random.nextDouble() method.

Parameters:

random - random generator used to create the basis.

Returns:

new right orthonormal basis with random orientation.

newRandomBasis

public static Orthonormal3DBasis newRandomBasis(RandomGenerator random,
 double ix,
 double iy,
 double iz)

Creates a pseudorandom basis, where i vector has components (ix/d, iy/d, iz/d), d=sqrt(ix²+iy²+iz²). Directions of vector pair j, k are uniformly distributed in the plane, perpendicular to i vector. These directions are chosen with help of random.nextDouble() method.

Parameters:

random - random generator used to create the basis.

ix - x-component of new i vector (maybe, multiplied by some d constant).

iy - y-component of new i vector (maybe, multiplied by some d constant).

iz - z-component of new i vector (maybe, multiplied by some d constant).

Returns:

new randomly oriented right orthonormal basis with given direction of i vector.

Throws:

IllegalArgumentException - if the length sqrt(ix²+iy²+iz²) of the passed vector (ix,iy,iz) is zero or too small (< MIN_ALLOWED_LENGTH).

ix

public double ix()

Returns x-component of i vector.

Returns:

x-component of i vector.

iy

public double iy()

Returns y-component of i vector.

Returns:

y-component of i vector.

iz

public double iz()

Returns z-component of i vector.

Returns:

z-component of i vector.

jx

public double jx()

Returns x-component of j vector.

Returns:

x-component of j vector.

jy

public double jy()

Returns y-component of j vector.

Returns:

y-component of j vector.

jz

public double jz()

Returns z-component of j vector.

Returns:

z-component of j vector.

kx

public double kx()

Returns x-component of k vector.

Returns:

x-component of k vector.

ky

public double ky()

Returns y-component of j vector.

Returns:

y-component of j vector.

kz

public double kz()

Returns z-component of j vector.

Returns:

z-component of j vector.

x

public double x(double i,
 double j,
 double k)

Returns i * ix() + j * jx() + k * kx()

Parameters:

i - projection of some vector p to the basis vector i.

j - projection of some vector p to the basis vector j.

k - projection of some vector p to the basis vector k.

Returns:

x-component of such p vector.

y

public double y(double i,
 double j,
 double k)

Returns i * iy() + j * jy() + k * ky()

Parameters:

i - projection of some vector p to the basis vector i.

j - projection of some vector p to the basis vector j.

k - projection of some vector p to the basis vector k.

Returns:

y-component of such p vector.

z

public double z(double i,
 double j,
 double k)

Returns i * iz() + j * jz() + k * kz()

Parameters:

i - projection of some vector p to the basis vector i.

j - projection of some vector p to the basis vector j.

k - projection of some vector p to the basis vector k.

Returns:

z-component of such p vector.

jki

public Orthonormal3DBasis jki()

Returns new basis (i', j', k'), where i'=j, j'=k, k'=i.

Returns:

new basis (j, k, i).

kij

public Orthonormal3DBasis kij()

Returns new basis (i', j', k'), where i'=k, j'=i, k'=j.

Returns:

new basis (k, i, j).

rotateJK

public Orthonormal3DBasis rotateJK(double angleInRadians)

rotateKI

public Orthonormal3DBasis rotateKI(double angleInRadians)

rotateIJ

public Orthonormal3DBasis rotateIJ(double angleInRadians)

rotate

public Orthonormal3DBasis rotate(double angleXYInRadians,
 double angleYZInRadians,
 double angleZXInRadians)

rotate

public Orthonormal3DBasis rotate(double directionX,
 double directionY,
 double directionZ,
 double angle)

multiply

public Orthonormal3DBasis multiply(Orthonormal3DBasis other)

inverse

public Orthonormal3DBasis inverse()

distanceSquare

public double distanceSquare(Orthonormal3DBasis other)

toString

public String toString()

Returns a brief string description of this object.

The result of this method may depend on implementation.

Overrides:

toString in class Object

Returns:

a brief string description of this object.

equals

public boolean equals(Object o)

Indicates whether some other object is an instance of this class, representing the same basis. The corresponding coordinates of vectors are compared as in Double.equals method, i.e. they are converted to long values by Double.doubleToLongBits method and the results are compared.

Overrides:

equals in class Object

Parameters:

o - the object to be compared for equality with this instance.

Returns:

true if and only if the specified object is an instance of Orthonormal3DBasis, representing the same right orthonormal basis as this object.

hashCode

public int hashCode()

Returns the hash code of this object.

Overrides:

hashCode in class Object

Returns:

the hash code of this object.

lengthSquare

public static double lengthSquare(double x,
 double y,
 double z)

Returns the square of the length of 3D segment with the given projections to the axes. Equivalent to x * x + y * y + z * z.

Parameters:

x - x-projection of the segment.

y - y-projection of the segment.

z - z-projection of the segment.

Returns:

the square of the segment length.

length

public static double length(double x,
 double y,
 double z)

Returns the length of 3D segment with the given projections to the axes. Equivalent to Math.sqrt(lengthSquare(x, y, z))..

Parameters:

x - x-projection of the segment.

y - y-projection of the segment.

z - z-projection of the segment.

Returns:

the segment length.

scalarProduct

public static double scalarProduct(double ax,
 double ay,
 double az,
 double bx,
 double by,
 double bz)

Returns the scalar product of a and b vectors: ax * bx + ay * by + az * bz.

Parameters:

ax - x-component of the vector a.

ay - y-component of the vector a.

az - z-component of the vector a.

bx - x-component of the vector b.

by - y-component of the vector b.

bz - z-component of the vector b.

Returns:

scalar product of two vectors.