javax.vecmath/src/javax/vecmath/Tuple3d.java

   1 /*
   2  * $RCSfile: Tuple3d.java,v $
   3  *
   4  * Copyright 1997-2008 Sun Microsystems, Inc.  All Rights Reserved.
   5  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6  *
   7  * This code is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License version 2 only, as
   9  * published by the Free Software Foundation.  Sun designates this
  10  * particular file as subject to the "Classpath" exception as provided
  11  * by Sun in the LICENSE file that accompanied this code.
  12  *
  13  * This code is distributed in the hope that it will be useful, but WITHOUT
  14  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * version 2 for more details (a copy is included in the LICENSE file that
  17  * accompanied this code).
  18  *
  19  * You should have received a copy of the GNU General Public License version
  20  * 2 along with this work; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  22  *
  23  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  24  * CA 95054 USA or visit www.sun.com if you need additional information or
  25  * have any questions.
  26  *
  27  * $Revision: 1.8 $
  28  * $Date: 2008/02/28 20:18:51 $
  29  * $State: Exp $
  30  */
  31
  32 package javax.vecmath;
  33
  34 import java.lang.Math;
  35
  36 /**
  37  * A generic 3-element tuple that is represented by double-precision
  38  * floating point x,y,z coordinates.
  39  *
  40  */
  41 public abstract class Tuple3d implements java.io.Serializable, Cloneable {
  42
  43     static final long serialVersionUID = 5542096614926168415L;
  44
  45     /**
  46      * The x coordinate.
  47      */
  48     public      double  x;
  49
  50     /**
  51      * The y coordinate.
  52      */
  53     public      double  y;
  54
  55     /**
  56      * The z coordinate.
  57      */
  58     public      double  z;
  59
  60
  61     /**
  62      * Constructs and initializes a Tuple3d from the specified xyz coordinates.
  63      * @param x the x coordinate
  64      * @param y the y coordinate
  65      * @param z the z coordinate
  66      */
  67     public Tuple3d(double x, double y, double z)
  68     {
  69         this.x = x;
  70         this.y = y;
  71         this.z = z;
  72     }
  73
  74     /**
  75      * Constructs and initializes a Tuple3d from the array of length 3.
  76      * @param t the array of length 3 containing xyz in order
  77      */
  78     public Tuple3d(double[] t)
  79     {
  80         this.x = t[0];
  81         this.y = t[1];
  82         this.z = t[2];
  83     }
  84
  85     /**
  86      * Constructs and initializes a Tuple3d from the specified Tuple3d.
  87      * @param t1 the Tuple3d containing the initialization x y z data
  88      */
  89     public Tuple3d(Tuple3d t1)
  90     {
  91         this.x = t1.x;
  92         this.y = t1.y;
  93         this.z = t1.z;
  94     }
  95
  96     /**
  97      * Constructs and initializes a Tuple3d from the specified Tuple3f.
  98      * @param t1 the Tuple3f containing the initialization x y z data
  99      */
 100     public Tuple3d(Tuple3f t1)
 101     {
 102         this.x = (double) t1.x;
 103         this.y = (double) t1.y;
 104         this.z = (double) t1.z;
 105     }
 106
 107     /**
 108      * Constructs and initializes a Tuple3d to (0,0,0).
 109      */
 110     public Tuple3d()
 111     {
 112         this.x = (double) 0.0;
 113         this.y = (double) 0.0;
 114         this.z = (double) 0.0;
 115     }
 116
 117     /**
 118      * Sets the value of this tuple to the specified xyz coordinates.
 119      * @param x the x coordinate
 120      * @param y the y coordinate
 121      * @param z the z coordinate
 122      */
 123     public final void set(double x, double y, double z)
 124     {
 125         this.x = x;
 126         this.y = y;
 127         this.z = z;
 128     }
 129
 130     /**
 131      * Sets the value of this tuple to the value of the xyz coordinates
 132      * located in the array of length 3.
 133      * @param t the array of length 3 containing xyz in order
 134      */
 135     public final void set(double[] t)
 136     {
 137         this.x = t[0];
 138         this.y = t[1];
 139         this.z = t[2];
 140     }
 141
 142     /**
 143      * Sets the value of this tuple to the value of tuple t1.
 144      * @param t1 the tuple to be copied
 145      */
 146     public final void set(Tuple3d t1)
 147     {
 148         this.x = t1.x;
 149         this.y = t1.y;
 150         this.z = t1.z;
 151     }
 152
 153     /**
 154      * Sets the value of this tuple to the value of tuple t1.
 155      * @param t1 the tuple to be copied
 156      */
 157     public final void set(Tuple3f t1)
 158     {
 159         this.x = (double) t1.x;
 160         this.y = (double) t1.y;
 161         this.z = (double) t1.z;
 162     }
 163
 164    /**
 165      * Copies the x,y,z coordinates of this tuple into the array t
 166      * of length 3.
 167      * @param t  the target array
 168      */
 169     public final void get(double[] t)
 170     {
 171         t[0] = this.x;
 172         t[1] = this.y;
 173         t[2] = this.z;
 174     }
 175
 176
 177    /**
 178      * Copies the x,y,z coordinates of this tuple into the tuple t.
 179      * @param t  the Tuple3d object into which the values of this object are copied
 180      */
 181     public final void get(Tuple3d t)
 182     {
 183         t.x = this.x;
 184         t.y = this.y;
 185         t.z = this.z;
 186     }
 187
 188
 189     /**
 190      * Sets the value of this tuple to the sum of tuples t1 and t2.
 191      * @param t1 the first tuple
 192      * @param t2 the second tuple
 193      */
 194     public final void add(Tuple3d t1, Tuple3d t2)
 195     {
 196         this.x = t1.x + t2.x;
 197         this.y = t1.y + t2.y;
 198         this.z = t1.z + t2.z;
 199     }
 200
 201
 202     /**
 203      * Sets the value of this tuple to the sum of itself and t1.
 204      * @param t1 the other tuple
 205      */
 206     public final void add(Tuple3d t1)
 207     {
 208         this.x += t1.x;
 209         this.y += t1.y;
 210         this.z += t1.z;
 211     }
 212
 213     /**
 214      * Sets the value of this tuple to the difference of tuples
 215      * t1 and t2 (this = t1 - t2).
 216      * @param t1 the first tuple
 217      * @param t2 the second tuple
 218      */
 219     public final void sub(Tuple3d t1, Tuple3d t2)
 220     {
 221         this.x = t1.x - t2.x;
 222         this.y = t1.y - t2.y;
 223         this.z = t1.z - t2.z;
 224     }
 225
 226     /**
 227      * Sets the value of this tuple to the difference
 228      * of itself and t1 (this = this - t1).
 229      * @param t1 the other tuple
 230      */
 231     public final void sub(Tuple3d t1)
 232     {
 233         this.x -= t1.x;
 234         this.y -= t1.y;
 235         this.z -= t1.z;
 236     }
 237
 238
 239     /**
 240      * Sets the value of this tuple to the negation of tuple t1.
 241      * @param t1 the source tuple
 242      */
 243     public final void negate(Tuple3d t1)
 244     {
 245         this.x = -t1.x;
 246         this.y = -t1.y;
 247         this.z = -t1.z;
 248     }
 249
 250
 251     /**
 252      * Negates the value of this tuple in place.
 253      */
 254     public final void negate()
 255     {
 256         this.x = -this.x;
 257         this.y = -this.y;
 258         this.z = -this.z;
 259     }
 260
 261
 262     /**
 263      * Sets the value of this tuple to the scalar multiplication
 264      * of tuple t1.
 265      * @param s the scalar value
 266      * @param t1 the source tuple
 267      */
 268     public final void scale(double s, Tuple3d t1)
 269     {
 270         this.x = s*t1.x;
 271         this.y = s*t1.y;
 272         this.z = s*t1.z;
 273     }
 274
 275
 276     /**
 277      * Sets the value of this tuple to the scalar multiplication
 278      * of itself.
 279      * @param s the scalar value
 280      */
 281     public final void scale(double s)
 282     {
 283         this.x *= s;
 284         this.y *= s;
 285         this.z *= s;
 286     }
 287
 288
 289     /**
 290      * Sets the value of this tuple to the scalar multiplication
 291      * of tuple t1 and then adds tuple t2 (this = s*t1 + t2).
 292      * @param s the scalar value
 293      * @param t1 the tuple to be multipled
 294      * @param t2 the tuple to be added
 295      */
 296     public final void scaleAdd(double s, Tuple3d t1, Tuple3d t2)
 297     {
 298         this.x = s*t1.x + t2.x;
 299         this.y = s*t1.y + t2.y;
 300         this.z = s*t1.z + t2.z;
 301     }
 302
 303
 304     /**
 305      * @deprecated Use scaleAdd(double,Tuple3d) instead
 306      */
 307     public final void scaleAdd(double s, Tuple3f t1) {
 308         scaleAdd(s, new Point3d(t1));
 309     }
 310
 311
 312     /**
 313      * Sets the value of this tuple to the scalar multiplication
 314      * of itself and then adds tuple t1 (this = s*this + t1).
 315      * @param s the scalar value
 316      * @param t1 the tuple to be added
 317      */
 318     public final void scaleAdd(double s, Tuple3d t1) {
 319         this.x = s*this.x + t1.x;
 320         this.y = s*this.y + t1.y;
 321         this.z = s*this.z + t1.z;
 322     }
 323
 324
 325
 326    /**
 327      * Returns a string that contains the values of this Tuple3d.
 328      * The form is (x,y,z).
 329      * @return the String representation
 330      */
 331     public String toString() {
 332         return "(" + this.x + ", " + this.y + ", " + this.z + ")";
 333     }
 334
 335
 336     /**
 337      * Returns a hash code value based on the data values in this
 338      * object.  Two different Tuple3d objects with identical data values
 339      * (i.e., Tuple3d.equals returns true) will return the same hash
 340      * code value.  Two objects with different data members may return the
 341      * same hash value, although this is not likely.
 342      * @return the integer hash code value
 343      */
 344     public int hashCode() {
 345         long bits = 1L;
 346         bits = 31L * bits + VecMathUtil.doubleToLongBits(x);
 347         bits = 31L * bits + VecMathUtil.doubleToLongBits(y);
 348         bits = 31L * bits + VecMathUtil.doubleToLongBits(z);
 349         return (int) (bits ^ (bits >> 32));
 350     }
 351
 352
 353    /**
 354      * Returns true if all of the data members of Tuple3d t1 are
 355      * equal to the corresponding data members in this Tuple3d.
 356      * @param t1  the tuple with which the comparison is made
 357      * @return  true or false
 358      */
 359     public boolean equals(Tuple3d t1)
 360     {
 361       try {
 362         return(this.x == t1.x && this.y == t1.y && this.z == t1.z);
 363       }
 364       catch (NullPointerException e2) {return false;}
 365     }
 366
 367    /**
 368      * Returns true if the Object t1 is of type Tuple3d and all of the
 369      * data members of t1 are equal to the corresponding data members in
 370      * this Tuple3d.
 371      * @param t1  the Object with which the comparison is made
 372      * @return  true or false
 373      */
 374     public boolean equals(Object t1)
 375     {
 376       try {
 377            Tuple3d t2 = (Tuple3d) t1;
 378            return(this.x == t2.x && this.y == t2.y && this.z == t2.z);
 379       }
 380       catch (ClassCastException   e1) {return false;}
 381       catch (NullPointerException e2) {return false;}
 382
 383     }
 384
 385    /**
 386      * Returns true if the L-infinite distance between this tuple
 387      * and tuple t1 is less than or equal to the epsilon parameter,
 388      * otherwise returns false.  The L-infinite
 389      * distance is equal to MAX[abs(x1-x2), abs(y1-y2), abs(z1-z2)].
 390      * @param t1  the tuple to be compared to this tuple
 391      * @param epsilon  the threshold value
 392      * @return  true or false
 393      */
 394     public boolean epsilonEquals(Tuple3d t1, double epsilon)
 395     {
 396        double diff;
 397
 398        diff = x - t1.x;
 399        if(Double.isNaN(diff)) return false;
 400        if((diff<0?-diff:diff) > epsilon) return false;
 401
 402        diff = y - t1.y;
 403        if(Double.isNaN(diff)) return false;
 404        if((diff<0?-diff:diff) > epsilon) return false;
 405
 406        diff = z - t1.z;
 407        if(Double.isNaN(diff)) return false;
 408        if((diff<0?-diff:diff) > epsilon) return false;
 409
 410        return true;
 411
 412     }
 413
 414
 415     /**
 416      * @deprecated Use clamp(double,double,Tuple3d) instead
 417      */
 418     public final void clamp(float min, float max, Tuple3d t) {
 419         clamp((double)min, (double)max, t);
 420     }
 421
 422
 423     /**
 424      *  Clamps the tuple parameter to the range [low, high] and
 425      *  places the values into this tuple.
 426      *  @param min   the lowest value in the tuple after clamping
 427      *  @param max  the highest value in the tuple after clamping
 428      *  @param t   the source tuple, which will not be modified
 429      */
 430     public final void clamp(double min, double max, Tuple3d t) {
 431         if( t.x > max ) {
 432           x = max;
 433         } else if( t.x < min ){
 434           x = min;
 435         } else {
 436           x = t.x;
 437         }
 438
 439         if( t.y > max ) {
 440           y = max;
 441         } else if( t.y < min ){
 442           y = min;
 443         } else {
 444           y = t.y;
 445         }
 446
 447         if( t.z > max ) {
 448           z = max;
 449         } else if( t.z < min ){
 450           z = min;
 451         } else {
 452           z = t.z;
 453         }
 454
 455    }
 456
 457
 458     /**
 459      * @deprecated Use clampMin(double,Tuple3d) instead
 460      */
 461     public final void clampMin(float min, Tuple3d t) {
 462         clampMin((double)min, t);
 463     }
 464
 465
 466     /**
 467      *  Clamps the minimum value of the tuple parameter to the min
 468      *  parameter and places the values into this tuple.
 469      *  @param min   the lowest value in the tuple after clamping
 470      *  @param t   the source tuple, which will not be modified
 471      */
 472     public final void clampMin(double min, Tuple3d t) {
 473         if( t.x < min ) {
 474           x = min;
 475         } else {
 476           x = t.x;
 477         }
 478
 479         if( t.y < min ) {
 480           y = min;
 481         } else {
 482           y = t.y;
 483         }
 484
 485         if( t.z < min ) {
 486           z = min;
 487         } else {
 488           z = t.z;
 489         }
 490
 491    }
 492
 493
 494     /**
 495      * @deprecated Use clampMax(double,Tuple3d) instead
 496      */
 497     public final void clampMax(float max, Tuple3d t) {
 498         clampMax((double)max, t);
 499     }
 500
 501
 502     /**
 503      *  Clamps the maximum value of the tuple parameter to the max
 504      *  parameter and places the values into this tuple.
 505      *  @param max the highest value in the tuple after clamping
 506      *  @param t   the source tuple, which will not be modified
 507      */
 508     public final void clampMax(double max, Tuple3d t) {
 509         if( t.x > max ) {
 510           x = max;
 511         } else {
 512           x = t.x;
 513         }
 514
 515         if( t.y > max ) {
 516           y = max;
 517         } else {
 518           y = t.y;
 519         }
 520
 521         if( t.z > max ) {
 522           z = max;
 523         } else {
 524           z = t.z;
 525         }
 526
 527    }
 528
 529
 530   /**
 531     *  Sets each component of the tuple parameter to its absolute
 532     *  value and places the modified values into this tuple.
 533     *  @param t   the source tuple, which will not be modified
 534     */
 535   public final void absolute(Tuple3d t)
 536   {
 537        x = Math.abs(t.x);
 538        y = Math.abs(t.y);
 539        z = Math.abs(t.z);
 540
 541   }
 542
 543
 544     /**
 545      * @deprecated Use clamp(double,double) instead
 546      */
 547     public final void clamp(float min, float max) {
 548         clamp((double)min, (double)max);
 549     }
 550
 551
 552     /**
 553      *  Clamps this tuple to the range [low, high].
 554      *  @param min  the lowest value in this tuple after clamping
 555      *  @param max  the highest value in this tuple after clamping
 556      */
 557     public final void clamp(double min, double max) {
 558         if( x > max ) {
 559           x = max;
 560         } else if( x < min ){
 561           x = min;
 562         }
 563
 564         if( y > max ) {
 565           y = max;
 566         } else if( y < min ){
 567           y = min;
 568         }
 569
 570         if( z > max ) {
 571           z = max;
 572         } else if( z < min ){
 573           z = min;
 574         }
 575
 576    }
 577
 578
 579     /**
 580      * @deprecated Use clampMin(double) instead
 581      */
 582     public final void clampMin(float min) {
 583         clampMin((double)min);
 584     }
 585
 586
 587     /**
 588      *  Clamps the minimum value of this tuple to the min parameter.
 589      *  @param min   the lowest value in this tuple after clamping
 590      */
 591     public final void clampMin(double min) {
 592       if( x < min ) x=min;
 593       if( y < min ) y=min;
 594       if( z < min ) z=min;
 595
 596    }
 597
 598
 599     /**
 600      * @deprecated Use clampMax(double) instead
 601      */
 602     public final void clampMax(float max) {
 603         clampMax((double)max);
 604     }
 605
 606
 607     /**
 608      *  Clamps the maximum value of this tuple to the max parameter.
 609      *  @param max   the highest value in the tuple after clamping
 610      */
 611     public final void clampMax(double max) {
 612       if( x > max ) x=max;
 613       if( y > max ) y=max;
 614       if( z > max ) z=max;
 615    }
 616
 617
 618   /**
 619     *  Sets each component of this tuple to its absolute value.
 620     */
 621   public final void absolute()
 622   {
 623      x = Math.abs(x);
 624      y = Math.abs(y);
 625      z = Math.abs(z);
 626   }
 627
 628
 629     /**
 630      * @deprecated Use interpolate(Tuple3d,Tuple3d,double) instead
 631      */
 632     public final void interpolate(Tuple3d t1, Tuple3d t2, float alpha) {
 633         interpolate(t1, t2, (double)alpha);
 634     }
 635
 636
 637     /**
 638      *  Linearly interpolates between tuples t1 and t2 and places the
 639      *  result into this tuple:  this = (1-alpha)*t1 + alpha*t2.
 640      *  @param t1  the first tuple
 641      *  @param t2  the second tuple
 642      *  @param alpha  the alpha interpolation parameter
 643      */
 644     public final void interpolate(Tuple3d t1, Tuple3d t2, double alpha) {
 645         this.x = (1-alpha)*t1.x + alpha*t2.x;
 646         this.y = (1-alpha)*t1.y + alpha*t2.y;
 647         this.z = (1-alpha)*t1.z + alpha*t2.z;
 648     }
 649
 650
 651     /**
 652      * @deprecated Use interpolate(Tuple3d,double) instead
 653      */
 654     public final void interpolate(Tuple3d t1, float alpha) {
 655         interpolate(t1, (double)alpha);
 656     }
 657
 658
 659     /**
 660     *  Linearly interpolates between this tuple and tuple t1 and
 661     *  places the result into this tuple:  this = (1-alpha)*this + alpha*t1.
 662     *  @param t1  the first tuple
 663     *  @param alpha  the alpha interpolation parameter
 664     */
 665     public final void interpolate(Tuple3d t1, double alpha) {
 666         this.x = (1-alpha)*this.x + alpha*t1.x;
 667         this.y = (1-alpha)*this.y + alpha*t1.y;
 668         this.z = (1-alpha)*this.z + alpha*t1.z;
 669     }
 670
 671     /**
 672      * Creates a new object of the same class as this object.
 673      *
 674      * @return a clone of this instance.
 675      * @exception OutOfMemoryError if there is not enough memory.
 676      * @see java.lang.Cloneable
 677      * @since vecmath 1.3
 678      */
 679     public Object clone() {
 680         // Since there are no arrays we can just use Object.clone()
 681         try {
 682             return super.clone();
 683         } catch (CloneNotSupportedException e) {
 684             // this shouldn't happen, since we are Cloneable
 685             throw new InternalError();
 686         }
 687     }
 688
 689     /**
 690          * Get the <i>x</i> coordinate.
 691          *
 692          * @return  the <i>x</i> coordinate.
 693          *
 694          * @since vecmath 1.5
 695          */
 696         public final double getX() {
 697                 return x;
 698         }
 699
 700
 701         /**
 702          * Set the <i>x</i> coordinate.
 703          *
 704          * @param x  value to <i>x</i> coordinate.
 705          *
 706          * @since vecmath 1.5
 707          */
 708         public final void setX(double x) {
 709                 this.x = x;
 710         }
 711
 712
 713         /**
 714          * Get the <i>y</i> coordinate.
 715          *
 716          * @return the <i>y</i> coordinate.
 717          *
 718          * @since vecmath 1.5
 719          */
 720         public final double getY() {
 721                 return y;
 722         }
 723
 724
 725         /**
 726          * Set the <i>y</i> coordinate.
 727          *
 728          * @param y value to <i>y</i> coordinate.
 729          *
 730          * @since vecmath 1.5
 731          */
 732         public final void setY(double y) {
 733                 this.y = y;
 734         }
 735
 736         /**
 737          * Get the <i>z</i> coordinate.
 738          *
 739          * @return the <i>z</i> coordinate.
 740          *
 741          * @since vecmath 1.5
 742          */
 743         public final double getZ() {
 744                 return z;
 745         }
 746
 747
 748         /**
 749          * Set the <i>z</i> coordinate.
 750          *
 751          * @param z value to <i>z</i> coordinate.
 752          *
 753          * @since vecmath 1.5
 754          */
 755         public final void setZ(double z) {
 756                 this.z = z;
 757         }
 758 }