com.azalient.apo.basics
Class Xyz

java.lang.Object
  com.azalient.apo.basics.Xyz

All Implemented Interfaces:

IXy, IXyz, OpenGLXyz, Serializable

public class Xyz
extends Object
implements IXyz, OpenGLXyz

A utility class for representing a point in three-dimensional space, or a three-dimensional vector.

This class has methods for vector arithmetic (add, subtract) and also for cross product and dot product.

See Also:

Serialized Form

Field Summary

static IXyz	NORTH
static IXyz	UNITY
static IXyz	ZERO

Fields inherited from interface com.azalient.api.a.position.IXyz

ZERO_ARRAY

Constructor Summary

Xyz()
Create a new point or vector (0,0,0)

Xyz(double px, double py, double pz)
Create a new point or vector (px, py, pz)

Xyz(IPosition that)
Create a new object point or vector as a copy of that IPosition

Xyz(IXyz that)
Create a new object point or vector as a copy of that

Xyz(IXyz v, char op, double s)
Create a new object equal to the scalar operation of v by s.

Xyz(IXyz u, char op, IXyz v)
Create a new object calculated from operation on two vectors.

Xyz(IXyz p, double distanceXY, IAngle bearing, double gradientFrac)
Create a new point given a start point, an XY-plane distance r, bearing in radians and fractional gradient

Xyz(IXyz a, IXyz b)
Create a new Xyz that represents the vector A to B

Xyz(IXyz p, IXyz q, double r)
If this point is P, create a point on line PQ at relative distance r, where r == 0 is at P, r == 1 is at Q.

Method Summary

void	abZ(IXyz a, IXyz b) Adjust the height of this point to be on the plane that connects A and B such that a line drawn perpendicular to AB in the plane has constant Z
void	add(IXyz v) Vector add operation in place.
IAngle	angleBetween(IXyz v) Returns the UNSIGNED angle in between this vector and the vector parameter; the return value is constrained to the range [0,180].
IAngle	asBearing() Return bearing CW from N in the range [0, 2PI)
double[]	asDouble3() Returns this point/vector as an array of 3 doubles
double	asGradient() Return the fractional gradient component of this vector
boolean	atZERO() Returns true if this point is at the origin (all zeroes)
IAngle	bearingTo(IXyz there) Radians in the range [0, 2PI)
IXyz	copy() Return a new object as a copy of this point/vector
IXyz	cross(IXyz v) Return new vector result of cross with v, original vectors unchanged.
void	crossWith(IXyz v) Vector cross operation in place.
double	distance(IXy there) Returns the distance from here to there
double	distance(IXyz there) Returns the distance from here to there
double	distance(IXyz a, IXyz b, boolean limitAB) return the distance from "this" to line segment AB
void	divide(double s) Scalar divide, in place
IXyz	dividedBy(double s) Divide all components of Vector by given scalar, returning new vector, originals unchanged.
double	dot(IXyz v) Computes the dot product of this vector and vector V.
double	gradientToFrac(IXyz there) Fractional gradient as dh/XY
static IXy	intersectionPoint(IXy p1, IXy p2, IXy p3, IXy p4, boolean forSegments) calculate the intersection point of line P1P2 with P3P4.
boolean	isFinite() Test if all components are finite and numbers (not NaN)
double	length() Returns the length of this vector (or the distance of the point from the origin).
double	lengthSquared()
IXyz	minus(IXyz v) Vector minus, returning new vector, originals unchanged.
IXyz	multipliedBy(double s) Multiply all components of Vector by given scalar, returning new vector, originals unchanged.
void	multiply(double s) Scalar multiply, in place
IXyz	nearestPointOn(IXyz a, IXyz b, boolean limitAB) return the nearest point to "this" on line segment AB.
IXyz	nearestPointOnLine(IXyz a, IXyz b) Returns the nearest point on line AB to this point.
void	negate() Negates the value of this xyz in place.
IXyz	negative() Return a negative of this vector, original unchanged
IXyz	normalized() Returns normalized version of this vector, original unchanged.
IXyz	parallelComponent(IXyz v) Return the component of v that is parallel with this
double	parallelComponentMag(IXyz v) Return the magnitude of the component of v that is parallel with this
IXyz	perpComponent(IXyz v) The component of v that is perpendicular to this
IXyz	plus(IXyz v) Vector plus, returning new vector, originals unchanged.
int	rgb() Convert a triple that represents a color into an RGB encoded integer
void	rotate(IXya xya) Rotate this point in the XY-plane around the axis of rotation (x,y) by given angle.
void	rotate(IXy xy, IAngle rotation) Rotate this point in the XY-plane around the axis of rotation (x,y) by given angle.
IXyz	rotationAsMove(IXya xya) Convert the given XY-plane rotation around an XY-axis into a translation
IXyz	rotationAsMove(IXy xy, IAngle rotation) Convert the given XY-plane rotation around an XY-axis into a translation
void	scale(double s) Scalar multiply, in place
Xyz	selfNormalize() Normalizes this vector in place.
void	set(double px, double py, double pz) Set this point/vector to the given values
void	set(IXyz xyz) Set this point/vector to have the same values as that one (copy by value, not by reference)
void	set(IXyz p, double distanceXY, IAngle bearing, double gradientFrac) Set the location based on a start point, an XY-plane distance r, bearing in radians and fractional gradient
void	subtract(IXyz v) Vector subtract operation in place.
boolean	toRightOf(IXyz pA, IXyz pB) Is this point to the right of the line segment AB? If this point is T, calculate cross product of vectors AT and AB.
String	toString()
IXyz	transform(IXyz origin0, IAngle compass0, IXyz origin1, IAngle compass1)
Xyz	truncateLength(double maxLength) Clip to a given length, returning a new object if modification is required
double	v(int i) indexed access to components: i=0 -> X i=1 -> Y i=2 -> Z
void	v(int i, double v) indexed access to components: i=0 -> X i=1 -> Y i=2 -> Z
double	x() X-coordinate of this point
void	x(double _x) Set the X-coordinate of this point
double	y() Y-coordinate of this point
void	y(double _y) Set the Y-coordinate of this point
double	z() Z-coordinate of this point
void	z(double _z) Set the Z-coordinate of this point

Methods inherited from class java.lang.Object

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

Field Detail

ZERO

public static final IXyz ZERO

NORTH

public static final IXyz NORTH

UNITY

public static final IXyz UNITY

Constructor Detail

Xyz

public Xyz()

Create a new point or vector (0,0,0)

Xyz

public Xyz(double px,
           double py,
           double pz)

Create a new point or vector (px, py, pz)

Xyz

public Xyz(IXyz that)

Create a new object point or vector as a copy of that

Xyz

public Xyz(IPosition that)

Create a new object point or vector as a copy of that IPosition

Xyz

public Xyz(IXyz a,
           IXyz b)

Create a new Xyz that represents the vector A to B

Xyz

public Xyz(IXyz u,
           char op,
           IXyz v)

Create a new object calculated from operation on two vectors.

Parameters:

u - the first xyz

op - operand either '+', '-' or 'x'. 'x' means cross product: a vector that is perpendicular to both u and v

v - the second xyz

Xyz

public Xyz(IXyz v,
           char op,
           double s)

Create a new object equal to the scalar operation of v by s.

Parameters:

s - the scalar value

op - operand either '*' or '/'

v - the source xyz

Xyz

public Xyz(IXyz p,
           double distanceXY,
           IAngle bearing,
           double gradientFrac)

Create a new point given a start point, an XY-plane distance r, bearing in radians and fractional gradient

Xyz

public Xyz(IXyz p,
           IXyz q,
           double r)

If this point is P, create a point on line PQ at relative distance r, where r == 0 is at P, r == 1 is at Q. If r is negative, point is created on other side of P to Q. If r is > 1, point is on other side of Q to P.

Method Detail

copy

public final IXyz copy()

Description copied from interface: IXyz

Return a new object as a copy of this point/vector

Specified by:

copy in interface IXyz

atZERO

public final boolean atZERO()

Description copied from interface: IXyz

Returns true if this point is at the origin (all zeroes)

Specified by:

atZERO in interface IXyz

v

public final double v(int i)

Description copied from interface: IXyz

indexed access to components:
i=0 -> X
i=1 -> Y
i=2 -> Z

Specified by:

v in interface IXyz

v

public final void v(int i,
                    double v)

Description copied from interface: IXyz

indexed access to components:
i=0 -> X
i=1 -> Y
i=2 -> Z

Specified by:

v in interface IXyz

asBearing

public final IAngle asBearing()

Description copied from interface: IXyz

Return bearing CW from N in the range [0, 2PI)

Specified by:

asBearing in interface IXyz

x

public final void x(double _x)

Description copied from interface: IXyz

Set the X-coordinate of this point

Specified by:

x in interface IXy

Specified by:

x in interface IXyz

y

public final void y(double _y)

Description copied from interface: IXyz

Set the Y-coordinate of this point

Specified by:

y in interface IXy

Specified by:

y in interface IXyz

z

public final void z(double _z)

Description copied from interface: IXyz

Set the Z-coordinate of this point

Specified by:

z in interface IXyz

length

public final double length()

Description copied from interface: IXyz

Returns the length of this vector (or the distance of the point from the origin). This value is cached.

Specified by:

length in interface IXyz

x

public final double x()

Description copied from interface: IXyz

X-coordinate of this point

Specified by:

x in interface IXy

Specified by:

x in interface IXyz

Specified by:

x in interface OpenGLXyz

y

public final double y()

Description copied from interface: IXyz

Y-coordinate of this point

Specified by:

y in interface IXy

Specified by:

y in interface IXyz

Specified by:

y in interface OpenGLXyz

z

public final double z()

Description copied from interface: IXyz

Z-coordinate of this point

Specified by:

z in interface IXyz

Specified by:

z in interface OpenGLXyz

set

public void set(IXyz xyz)

Description copied from interface: IXyz

Set this point/vector to have the same values as that one (copy by value, not by reference)

Specified by:

set in interface IXyz

set

public final void set(double px,
                      double py,
                      double pz)

Description copied from interface: IXyz

Set this point/vector to the given values

Specified by:

set in interface IXyz

set

public final void set(IXyz p,
                      double distanceXY,
                      IAngle bearing,
                      double gradientFrac)

Set the location based on a start point, an XY-plane distance r, bearing in radians and fractional gradient

negate

public final void negate()

Negates the value of this xyz in place.

Specified by:

negate in interface IXyz

negative

public final IXyz negative()

Description copied from interface: IXyz

Return a negative of this vector, original unchanged

Specified by:

negative in interface IXyz

normalized

public final IXyz normalized()

Description copied from interface: IXyz

Returns normalized version of this vector, original unchanged.

Specified by:

normalized in interface IXyz

selfNormalize

public final Xyz selfNormalize()

Normalizes this vector in place.

Specified by:

selfNormalize in interface IXyz

distance

public final double distance(IXyz there)

Returns the distance from here to there

Specified by:

distance in interface IXyz

Parameters:

there -

distance

public final double distance(IXy there)

Returns the distance from here to there

Specified by:

distance in interface IXy

Parameters:

there -

bearingTo

public final IAngle bearingTo(IXyz there)

Radians in the range [0, 2PI)

Specified by:

bearingTo in interface IXyz

gradientToFrac

public final double gradientToFrac(IXyz there)

Fractional gradient as dh/XY

Specified by:

gradientToFrac in interface IXyz

asGradient

public final double asGradient()

Description copied from interface: IXyz

Return the fractional gradient component of this vector

Specified by:

asGradient in interface IXyz

add

public final void add(IXyz v)

Description copied from interface: IXyz

Vector add operation in place.

Specified by:

add in interface IXyz

subtract

public final void subtract(IXyz v)

Description copied from interface: IXyz

Vector subtract operation in place.

Specified by:

subtract in interface IXyz

plus

public final IXyz plus(IXyz v)

Vector plus, returning new vector, originals unchanged.

Specified by:

plus in interface IXyz

minus

public final IXyz minus(IXyz v)

Vector minus, returning new vector, originals unchanged.

Specified by:

minus in interface IXyz

crossWith

public final void crossWith(IXyz v)

Vector cross operation in place.

Specified by:

crossWith in interface IXyz

cross

public final IXyz cross(IXyz v)

Description copied from interface: IXyz

Return new vector result of cross with v, original vectors unchanged.

Specified by:

cross in interface IXyz

scale

public final void scale(double s)

Description copied from interface: IXyz

Scalar multiply, in place

Specified by:

scale in interface IXyz

divide

public final void divide(double s)

Description copied from interface: IXyz

Scalar divide, in place

Specified by:

divide in interface IXyz

multiply

public final void multiply(double s)

Description copied from interface: IXyz

Scalar multiply, in place

Specified by:

multiply in interface IXyz

multipliedBy

public final IXyz multipliedBy(double s)

Description copied from interface: IXyz

Multiply all components of Vector by given scalar, returning new vector, originals unchanged.

Specified by:

multipliedBy in interface IXyz

dividedBy

public final IXyz dividedBy(double s)

Description copied from interface: IXyz

Divide all components of Vector by given scalar, returning new vector, originals unchanged.

Specified by:

dividedBy in interface IXyz

dot

public final double dot(IXyz v)

Computes the dot product of this vector and vector V. The dot product is a scalar value that varies as a cosine curve with the angle between the vectors. The dot product of a vector with itself is simply the square of its length. The dot product is

• Zero for perpendicular vectors
• Negative for vectors in "opposite directions" (more than 90 deg)
• Positive for vectors in "same direction" (less than 90 deg)

 
   U.V = u * v * cos(theta)
       = ux*vx + uy*vy + uz*vz
   
 

where u is the length of U, v is the length of V and theta is the angle between U and V. As this returns a scalar value,it cannot be included in the constructors or in the other vector operation methods

Specified by:

dot in interface IXyz

Parameters:

v - the other vector

Returns:

the dot product of this vector and v

lengthSquared

public final double lengthSquared()

Specified by:

lengthSquared in interface IXyz

parallelComponent

public final IXyz parallelComponent(IXyz v)

Return the component of v that is parallel with this

Specified by:

parallelComponent in interface IXyz

parallelComponentMag

public final double parallelComponentMag(IXyz v)

Return the magnitude of the component of v that is parallel with this

Specified by:

parallelComponentMag in interface IXyz

perpComponent

public final IXyz perpComponent(IXyz v)

The component of v that is perpendicular to this

Specified by:

perpComponent in interface IXyz

truncateLength

public final Xyz truncateLength(double maxLength)

Clip to a given length, returning a new object if modification is required

Specified by:

truncateLength in interface IXyz

angleBetween

public final IAngle angleBetween(IXyz v)

Returns the UNSIGNED angle in between this vector and the vector parameter; the return value is constrained to the range [0,180].

Specified by:

angleBetween in interface IXyz

Parameters:

v - the other vector

Returns:

the angle in radians in the range[0,180]

rgb

public final int rgb()

Convert a triple that represents a color into an RGB encoded integer

Returns:

The RGB encoding of the Xyz triple

toRightOf

public final boolean toRightOf(IXyz pA,
                               IXyz pB)

Is this point to the right of the line segment AB? If this point is T, calculate cross product of vectors AT and AB. A positive value of z component means point is to the right public final boolean toRightOf_Slow(IXyz pA, IXyz pB) { Xyz aToHere = new Xyz(this, CC.MI, pA); Xyz aToB = new Xyz(pB, CC.MI, pA); Xyz cross = new Xyz(aToHere, 'x', aToB); return (cross.z() > 0); }

Specified by:

toRightOf in interface IXyz

toString

public String toString()

Overrides:

toString in class Object

nearestPointOnLine

public final IXyz nearestPointOnLine(IXyz a,
                                     IXyz b)

Returns the nearest point on line AB to this point.

Specified by:

nearestPointOnLine in interface IXyz

rotate

public final void rotate(IXy xy,
                         IAngle rotation)

Rotate this point in the XY-plane around the axis of rotation (x,y) by given angle. Rotation is in the XY-plane: The z co-ordinate of this point is not affected.

Specified by:

rotate in interface IXyz

rotate

public final void rotate(IXya xya)

Rotate this point in the XY-plane around the axis of rotation (x,y) by given angle. Rotation is in the XY-plane: The z co-ordinate of this point is not affected.

Specified by:

rotate in interface IXyz

rotationAsMove

public final IXyz rotationAsMove(IXy xy,
                                 IAngle rotation)

Convert the given XY-plane rotation around an XY-axis into a translation

Specified by:

rotationAsMove in interface IXyz

rotationAsMove

public final IXyz rotationAsMove(IXya xya)

Convert the given XY-plane rotation around an XY-axis into a translation

Specified by:

rotationAsMove in interface IXyz

transform

public final IXyz transform(IXyz origin0,
                            IAngle compass0,
                            IXyz origin1,
                            IAngle compass1)

Specified by:

transform in interface IXyz

nearestPointOn

public final IXyz nearestPointOn(IXyz a,
                                 IXyz b,
                                 boolean limitAB)

Description copied from interface: IXyz

return the nearest point to "this" on line segment AB.

Specified by:

nearestPointOn in interface IXyz

limitAB - if true, the point must be between A and B, inclusive

distance

public final double distance(IXyz a,
                             IXyz b,
                             boolean limitAB)

Description copied from interface: IXyz

return the distance from "this" to line segment AB

Specified by:

distance in interface IXyz

limitAB - if true, the distance is to a point between A and B, inclusive. If false, the line is extended to infinite length

intersectionPoint

public static IXy intersectionPoint(IXy p1,
                                    IXy p2,
                                    IXy p3,
                                    IXy p4,
                                    boolean forSegments)

calculate the intersection point of line P1P2 with P3P4. For use with line segments, set forSegments to true - this will return null if the intersection point is not between P1 and P2 and between P3 and P4. if lines are parallel or coincident, null will be returned

abZ

public final void abZ(IXyz a,
                      IXyz b)

Adjust the height of this point to be on the plane that connects A and B such that a line drawn perpendicular to AB in the plane has constant Z

Specified by:

abZ in interface IXyz

isFinite

public final boolean isFinite()

Description copied from interface: IXyz

Test if all components are finite and numbers (not NaN)

Specified by:

isFinite in interface IXyz

asDouble3

public final double[] asDouble3()

Description copied from interface: IXyz

Returns this point/vector as an array of 3 doubles

Specified by:

asDouble3 in interface IXyz