gov/nasa/worldwind/geom/Plane.java

   1 /*
   2 Copyright (C) 2001, 2006 United States Government
   3 as represented by the Administrator of the
   4 National Aeronautics and Space Administration.
   5 All Rights Reserved.
   6 */
   7 package gov.nasa.worldwind.geom;
   8
   9 import gov.nasa.worldwind.util.Logging;
  10
  11 /**
  12  * A <code>Plane</code> object represents a mathematical plane in an arbitrary cartesian co-ordinate system. A
  13  * <code>Plane</code> is defined by a normal vector and a distance along that vector from the origin, where the distance
  14  * represents the distance from the origin to the <code>Plane</code> rather than from the <code>Plane</code> to the
  15  * origin.
  16  * <p/>
  17  * <p/>
  18  * Instances of <code>Plane</code> are immutable. </p>
  19  *
  20  * @author Tom Gaskins
  21  * @version $Id: Plane.java 2471 2007-07-31 21:50:57Z tgaskins $
  22  */
  23 public final class Plane
  24 {
  25
  26     /**
  27      * Represents all the information about this <code>Plane</code>. The first three values (<code>x, y, z</code>) of
  28      * <code>v</code> represent a normal <code>Vector</code> to the <code>Plane</code>, while the fourth
  29      * (<code>w</code>) represents the signed distance this <code>Plane</code> has been shifted along that normal.
  30      */
  31     private final Vec4 n;
  32
  33     /**
  34      * Obtains a new instance of a <code>Plane</code> whose information is contained in <code>Vector</code>
  35      * <code>vec</code>.
  36      *
  37      * @param vec the <code>Vector</code> containing information about this <code>Plane</code>'s normal and distance
  38      * @throws IllegalArgumentException if passed a null or zero-length <code>Vector</code>
  39      */
  40     public Plane(Vec4 vec)
  41     {
  42         if (vec == null)
  43         {
  44             String message = Logging.getMessage("nullValue.VectorIsNull");
  45             Logging.logger().severe(message);
  46             throw new IllegalArgumentException(message);
  47         }
  48
  49         if (vec.getLengthSquared3() == 0.0)
  50         {
  51             String message = Logging.getMessage("Geom.Plane.VectorIsZero");
  52             Logging.logger().severe(message);
  53             throw new IllegalArgumentException(message);
  54         }
  55
  56         this.n = vec;
  57     }
  58
  59     /**
  60      * Obtains a new <code>Plane</code> whose normal is defined by the vector (a,b,c) and whose disance from that vector
  61      * is d. The vector may not have zero length.
  62      *
  63      * @param a the x-parameter of the normal to this <code>Plane</code>
  64      * @param b the y-parameter of the normal to this <code>Plane</code>
  65      * @param c the z-parameter of the normal to this <code>Plane</code>
  66      * @param d the distance of this <code>Plane</code> from the origin along its normal.
  67      * @throws IllegalArgumentException if <code>0==a==b==c</code>
  68      */
  69     public Plane(double a, double b, double c, double d)
  70     {
  71         if (a == 0.0 && b == 0.0 && c == 0.0)
  72         {
  73             String message = Logging.getMessage("Geom.Plane.VectorIsZero");
  74             Logging.logger().severe(message);
  75             throw new IllegalArgumentException(message);
  76         }
  77
  78         this.n = new Vec4(a, b, c, d);
  79     }
  80
  81     /**
  82      * Retrieves a <code>Vec4</code> representing the normal to this <code>Plane</code>.
  83      *
  84      * @return a <code>Vec4</code> representing the normal to this <code>Plane</code>
  85      */
  86     public final Vec4 getNormal()
  87     {
  88         return new Vec4(this.n.x, this.n.y, this.n.z);
  89     }
  90
  91     /**
  92      * Retrieves the distance from the origin to this <code>Plane</code>. Two options exist for defining distance - the
  93      * first represents the distance from the origin to the <code>Plane</code>, the second represents the distance from
  94      * the <code>Plane</code> to the origin. This function uses the first method. The outcome of this is that depending
  95      * on the caller's view of this method, the sign of distances may appear to be reversed.
  96      *
  97      * @return the distance between this <code>Plane</code> and the origin
  98      */
  99     public final double getDistance()
 100     {
 101         return this.n.w;
 102     }
 103
 104     /**
 105      * Retrieves a vector representing the normal and distance to this <code>Plane</code>. The vector has the structure
 106      * (x, y, z, distance), where (x, y, z) represents the normal, and distance represents the distance from the
 107      * origin.
 108      *
 109      * @return a <code>Vector</code> representation of this <code>Plane</code>
 110      */
 111     public final Vec4 getVector()
 112     {
 113         return this.n;
 114     }
 115
 116     /**
 117      * Calculates the dot product of this <code>Plane</code> with Vec4 <code>p</code>.
 118      *
 119      * @param p the Vec4 to dot with this <code>Plane</code>
 120      * @return the dot product of <code>p</code> and this <code>Plane</code>
 121      * @throws IllegalArgumentException if <code>p</code> is null
 122      */
 123     public final double dot(Vec4 p)
 124     {
 125         if (p == null)
 126         {
 127             String message = Logging.getMessage("nullValue.PointIsNull");
 128             Logging.logger().severe(message);
 129             throw new IllegalArgumentException(message);
 130         }
 131
 132         return this.n.x * p.x + this.n.y * p.y + this.n.z * p.z + this.n.w * p.w;
 133     }
 134
 135     public final Plane computeParallelPlaneAtDistance(double distance)
 136     {
 137         return new Plane(this.n.x, this.n.y, this.n.z, distance);
 138     }
 139
 140     @Override
 141     public final String toString()
 142     {
 143         return this.n.toString();
 144     }
 145
 146     public Vec4 intersect(Line line)
 147     {
 148         double ldotv = this.n.dot3(line.getDirection());
 149         if (ldotv == 0)
 150             return null;
 151
 152         Vec4 s = new Vec4(line.getOrigin().x, line.getOrigin().y, line.getOrigin().z, 1);
 153         double ldots = this.n.dot4(s);
 154         if (ldots == 0)
 155             return null;
 156
 157         double t = -ldots / ldotv;
 158         return line.getPointAt(t);
 159     }
 160
 161     @Override
 162     public final boolean equals(Object o)
 163     {
 164         if (this == o)
 165             return true;
 166         if (o == null || getClass() != o.getClass())
 167             return false;
 168
 169         final gov.nasa.worldwind.geom.Plane plane = (gov.nasa.worldwind.geom.Plane) o;
 170
 171         //noinspection RedundantIfStatement
 172         if (!this.n.normalize3().equals(plane.n.normalize3()))
 173             return false;
 174
 175         return true;
 176     }
 177
 178     @Override
 179     public final int hashCode()
 180     {
 181         return this.n.hashCode();
 182     }
 183 }