gumbo.graphic.math
Class Tuple3

java.lang.Object
  |
  +--gumbo.graphic.math.Tuple3
All Implemented Interfaces:
Graphic, GraphicGeometry, java.io.Serializable
Direct Known Subclasses:
Point3, Size3, Vector3

public abstract class Tuple3
extends java.lang.Object
implements java.io.Serializable, GraphicGeometry

An abstract base class for a 3D spatial element (3-tuple), with double precision.

Version:
$Revision: 1.11 $
Author:
Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.
See Also:
Serialized Form

Constructor Summary
Tuple3()
           
Tuple3(double[] val)
          Creates an instance using a mutator.
Tuple3(double x, double y, double z)
          Creates an instance using a mutator.
Tuple3(Tuple3 tuple)
          Creates an instance using a mutator.
 
Method Summary
 Tuple3 abs(Tuple3 tuple)
          this = tuple < 0 ? -tuple : tuple
 Tuple3 add(Tuple3 tuple, double val)
          this = tuple + val
 Tuple3 add(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA + tupleB
 Tuple3 clamp(Tuple3 tuple, double min, double max)
          this = clampMax(clampMin(tuple))
 Tuple3 clamp(Tuple3 tuple, Tuple3 min, Tuple3 max)
          this = clampMax(clampMin(tuple))
 Tuple3 clampMax(Tuple3 tuple, double max)
          this = tuple > max ? max : tuple
 Tuple3 clampMax(Tuple3 tuple, Tuple3 max)
          this = tuple > max ? max : tuple
 Tuple3 clampMin(Tuple3 tuple, double min)
          this = tuple < min ? min : tuple
 Tuple3 clampMin(Tuple3 tuple, Tuple3 min)
          this = tuple < min ? min : tuple
 Tuple3 clear()
          this = (0, 0, 0).
static void clearArray(double[] retVal)
          Sets a length 3 array to all zeros.
 Tuple3 div(Tuple3 tuple, double val)
          this = tuple / val
 Tuple3 div(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA / tupleB
 boolean equals(java.lang.Object obj)
           
 double[] get(double[] retVal)
          Gets the value of this tuple.
 double get(int dim)
          Gets a dimension value in this tuple.
 java.lang.Object getGraphic()
          Default implementation: Returns this (non-native implementation).
 SpaceNode getGraphicLocalSpace()
          Default implementation: Returns null (absolute reference space).
 Tuple3 getTuple3()
          Gets a singleton immutable view of this object with the same identity (hashCode(), equals()) as this object.
 double getX()
          Gets the X dimension value of this tuple.
 double getY()
          Gets the Y dimension value of this tuple.
 double getZ()
          Gets the Z dimension value of this tuple.
protected  Tuple3 implGetTuple3()
          Master whole state accessor.
protected  double[] implGetTuple3(double[] retVal)
          Master whole state accessor.
protected  double implGetTuple3(int dim)
          Master partial state accessor.
protected  Tuple3 implInitTuple3(double x, double y, double z)
          Master whole state initializer intended for use by constructors to establish an initial state without interference from mutator overrides.
protected  Tuple3 implSetTuple3(double[] val)
          Master whole state mutator.
protected  Tuple3 implSetTuple3(int dim, double val)
          Master partial state mutator.
 boolean isEqual(Tuple3 tuple)
          Returns true if the dimension values of a tuple are exactly equal to those of this tuple.
 boolean isEqual(Tuple3 tuple, double tolerance)
          Returns true if the dimension values of a tuple are approximately equal to those of this tuple, within plus or minus a tolerance, inclusive.
 boolean isGreaterEqual(Tuple3 tuple)
          Returns true if the dimension values of a tuple are all greater than or equal to those of this tuple.
 boolean isInsideEqual(Tuple3 min, Tuple3 max)
          Returns true if the dimension values of this tuple are all within or equal to those of the min and max bounds.
 boolean isLessEqual(Tuple3 tuple)
          Returns true if the dimension values of a tuple are all less than or equal to those of this tuple.
 boolean isOutside(Tuple3 min, Tuple3 max)
          Returns true if the dimension values of this tuple are all outside those of the min and max bounds.
 boolean isZero()
          Returns true if all dimension values of this tuple are exactly zero.
 boolean isZero(double tolerance)
          Returns true if all dimension values of this tuple are approximately zero, within plus or minus a tolerance, inclusive.
 Tuple3 max(Tuple3 tuple, double val)
          this = tuple > val ? tupleA : val
 Tuple3 max(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA > tupleB ? tupleA : tupleB
 Tuple3 min(Tuple3 tuple, double val)
          this = tuple < val ? tuple : val
 Tuple3 min(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA < tupleB ? tupleA : tupleB
 Tuple3 mult(Tuple3 tuple, double val)
          this = tuple * val
 Tuple3 mult(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA * tupleB
 Tuple3 neg(Tuple3 tuple)
          this = -tuple
 Tuple3 noise()
          this = rand[-1,1)
 Tuple3 random()
          this = rand[0,1)
 Tuple3 round(Tuple3 tuple)
          Rounds each dimension to the nearest integer value.
 Tuple3 set(double[] val)
          Sets this tuple.
 Tuple3 set(double x, double y, double z)
          Sets this tuple to the specified dimension values.
 Tuple3 set(int dim, double val)
          Sets a dimension value in this tuple to a given value.
 void set(Tuple3 tuple)
          Sets this tuple to the value of another tuple.
static void setArray(double x, double y, double z, double[] retVal)
          Sets the dimension values of a length 3 array.
 Tuple3 setX(double val)
          Sets the X dimension value of this tuple.
 Tuple3 setY(double val)
          Sets the Y dimension value of this tuple.
 Tuple3 setZ(double val)
          Sets the Z dimension value of this tuple.
 Tuple3 sub(Tuple3 tuple, double val)
          this = tuple - val
 Tuple3 sub(Tuple3 tupleA, Tuple3 tupleB)
          this = tupleA - tupleB
 double sum()
          Returns the sum of this tuple's elements.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Tuple3

public Tuple3()

Tuple3

public Tuple3(double x,
              double y,
              double z)
Creates an instance using a mutator.


Tuple3

public Tuple3(double[] val)
Creates an instance using a mutator.


Tuple3

public Tuple3(Tuple3 tuple)
Creates an instance using a mutator.

Method Detail

setX

public Tuple3 setX(double val)
Sets the X dimension value of this tuple.

Parameters:
val - The dimension value.

setY

public Tuple3 setY(double val)
Sets the Y dimension value of this tuple.

Parameters:
val - The dimension value.

setZ

public Tuple3 setZ(double val)
Sets the Z dimension value of this tuple.

Parameters:
val - The dimension value.

set

public Tuple3 set(int dim,
                  double val)
Sets a dimension value in this tuple to a given value.

Parameters:
dim - Dimension (0-2). Throws an exception if out of range.
val - New value for the dimension.
Returns:
This tuple.

set

public Tuple3 set(double x,
                  double y,
                  double z)
Sets this tuple to the specified dimension values.

Parameters:
x - X dimension value.
y - Y dimension value.
z - Z dimension value.
Returns:
This tuple.

set

public Tuple3 set(double[] val)
Sets this tuple.

Parameters:
val - New value [3]. Never null.

set

public void set(Tuple3 tuple)
Sets this tuple to the value of another tuple.

Parameters:
tuple - Tuple to copy. Never null.

clear

public Tuple3 clear()
this = (0, 0, 0).


neg

public Tuple3 neg(Tuple3 tuple)
this = -tuple


abs

public Tuple3 abs(Tuple3 tuple)
this = tuple < 0 ? -tuple : tuple


round

public Tuple3 round(Tuple3 tuple)
Rounds each dimension to the nearest integer value.


random

public Tuple3 random()
this = rand[0,1)


noise

public Tuple3 noise()
this = rand[-1,1)


add

public Tuple3 add(Tuple3 tuple,
                  double val)
this = tuple + val


add

public Tuple3 add(Tuple3 tupleA,
                  Tuple3 tupleB)
this = tupleA + tupleB


sub

public Tuple3 sub(Tuple3 tuple,
                  double val)
this = tuple - val


sub

public Tuple3 sub(Tuple3 tupleA,
                  Tuple3 tupleB)
this = tupleA - tupleB


mult

public Tuple3 mult(Tuple3 tuple,
                   double val)
this = tuple * val


mult

public Tuple3 mult(Tuple3 tupleA,
                   Tuple3 tupleB)
this = tupleA * tupleB


div

public Tuple3 div(Tuple3 tuple,
                  double val)
this = tuple / val


div

public Tuple3 div(Tuple3 tupleA,
                  Tuple3 tupleB)
this = tupleA / tupleB


min

public Tuple3 min(Tuple3 tuple,
                  double val)
this = tuple < val ? tuple : val


min

public Tuple3 min(Tuple3 tupleA,
                  Tuple3 tupleB)
this = tupleA < tupleB ? tupleA : tupleB


max

public Tuple3 max(Tuple3 tuple,
                  double val)
this = tuple > val ? tupleA : val


max

public Tuple3 max(Tuple3 tupleA,
                  Tuple3 tupleB)
this = tupleA > tupleB ? tupleA : tupleB


clampMin

public final Tuple3 clampMin(Tuple3 tuple,
                             double min)
this = tuple < min ? min : tuple


clampMin

public final Tuple3 clampMin(Tuple3 tuple,
                             Tuple3 min)
this = tuple < min ? min : tuple


clampMax

public final Tuple3 clampMax(Tuple3 tuple,
                             double max)
this = tuple > max ? max : tuple


clampMax

public final Tuple3 clampMax(Tuple3 tuple,
                             Tuple3 max)
this = tuple > max ? max : tuple


clamp

public Tuple3 clamp(Tuple3 tuple,
                    double min,
                    double max)
this = clampMax(clampMin(tuple))


clamp

public Tuple3 clamp(Tuple3 tuple,
                    Tuple3 min,
                    Tuple3 max)
this = clampMax(clampMin(tuple))


getX

public double getX()
Gets the X dimension value of this tuple.

Returns:
The dimension value.

getY

public double getY()
Gets the Y dimension value of this tuple.

Returns:
The dimension value.

getZ

public double getZ()
Gets the Z dimension value of this tuple.

Returns:
The dimension value.

get

public double get(int dim)
Gets a dimension value in this tuple.

Parameters:
dim - Dimension. Returns zero if <0 or >2.
Returns:
The dimension value.

get

public double[] get(double[] retVal)
Gets the value of this tuple.

Parameters:
retVal - Return value object [3]. Never null.

getTuple3

public Tuple3 getTuple3()
Gets a singleton immutable view of this object with the same identity (hashCode(), equals()) as this object.

Returns:
The view. Never null.

isZero

public boolean isZero()
Returns true if all dimension values of this tuple are exactly zero.


isZero

public boolean isZero(double tolerance)
Returns true if all dimension values of this tuple are approximately zero, within plus or minus a tolerance, inclusive.

Parameters:
tolerance - >=0. Zero if <0.

isEqual

public boolean isEqual(Tuple3 tuple)
Returns true if the dimension values of a tuple are exactly equal to those of this tuple.


isEqual

public boolean isEqual(Tuple3 tuple,
                       double tolerance)
Returns true if the dimension values of a tuple are approximately equal to those of this tuple, within plus or minus a tolerance, inclusive.

Parameters:
tolerance - Magnitude of the tolerance positive extent. Must be >=zero.

isLessEqual

public boolean isLessEqual(Tuple3 tuple)
Returns true if the dimension values of a tuple are all less than or equal to those of this tuple.


isGreaterEqual

public boolean isGreaterEqual(Tuple3 tuple)
Returns true if the dimension values of a tuple are all greater than or equal to those of this tuple.


isInsideEqual

public boolean isInsideEqual(Tuple3 min,
                             Tuple3 max)
Returns true if the dimension values of this tuple are all within or equal to those of the min and max bounds. Results are undefined if min is not less than or equal to max.


isOutside

public boolean isOutside(Tuple3 min,
                         Tuple3 max)
Returns true if the dimension values of this tuple are all outside those of the min and max bounds. Results are undefined if min is not less than or equal to max.


sum

public double sum()
Returns the sum of this tuple's elements.


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

implSetTuple3

protected Tuple3 implSetTuple3(int dim,
                               double val)
Master partial state mutator.

Parameters:
dim - Dimension. Throws an exception if out of range.
val - New value for the dimension.
Returns:
This tuple.

implSetTuple3

protected Tuple3 implSetTuple3(double[] val)
Master whole state mutator.

Parameters:
val - New value [3].

implGetTuple3

protected double implGetTuple3(int dim)
Master partial state accessor.

Parameters:
dim - Dimension. Throws an exception if out of range.
Returns:
The dimension value.

implGetTuple3

protected double[] implGetTuple3(double[] retVal)
Master whole state accessor.

Parameters:
retVal - Return value object [3]. Never null.

implGetTuple3

protected Tuple3 implGetTuple3()
Master whole state accessor.


implInitTuple3

protected final Tuple3 implInitTuple3(double x,
                                      double y,
                                      double z)
Master whole state initializer intended for use by constructors to establish an initial state without interference from mutator overrides. Subclasses should exercise great caution when using this method to assure a consistent internal state in the subclass, and to avoid violation of any subclass constraints or immutability if used after construction.


getGraphicLocalSpace

public SpaceNode getGraphicLocalSpace()
Default implementation: Returns null (absolute reference space).

Specified by:
getGraphicLocalSpace in interface GraphicGeometry
Returns:
Reference to the space. If null, absolute space.

getGraphic

public java.lang.Object getGraphic()
Default implementation: Returns this (non-native implementation).

Specified by:
getGraphic in interface Graphic
Returns:
The target graphic object. Possibly this object (self-proxy, direct implementation), but never null.

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object

setArray

public static void setArray(double x,
                            double y,
                            double z,
                            double[] retVal)
Sets the dimension values of a length 3 array.


clearArray

public static void clearArray(double[] retVal)
Sets a length 3 array to all zeros.