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.*;
  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 1749 2007-05-06 19:48:14Z 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 Vector v;
  32     private final Point n;
  33
  34     /**
  35      * Obtains a new instance of a <code>Plane</code> whose information is contained in <code>Vector</code>
  36      * <code>vec</code>.
  37      *
  38      * @param vec the <code>Vector</code> containing information about this <code>Plane</code>'s normal and distance
  39      * @throws IllegalArgumentException if passed a null or zero-length <code>Vector</code>
  40      */
  41     public Plane(Point vec)
  42     {
  43         if (vec == null)
  44         {
  45             String message = WorldWind.retrieveErrMsg("nullValue.VectorIsNull");
  46             WorldWind.logger().log(java.util.logging.Level.FINE, message);
  47             throw new IllegalArgumentException(message);
  48         }
  49
  50         if (vec.selfDot() == 0)
  51         {
  52             String message = WorldWind.retrieveErrMsg("geom.Plane.VectorIsZero");
  53             WorldWind.logger().log(java.util.logging.Level.FINE, message);
  54             throw new IllegalArgumentException(message);
  55         }
  56
  57         this.n = vec;
  58     }
  59
  60     /**
  61      * Obtains a new <code>Plane</code> whose normal is defined by the vector (a,b,c) and whose disance from that vector
  62      * is d. The vector may not have zero length.
  63      *
  64      * @param a the x-parameter of the normal to this <code>Plane</code>
  65      * @param b the y-parameter of the normal to this <code>Plane</code>
  66      * @param c the z-parameter of the normal to this <code>Plane</code>
  67      * @param d the distance of this <code>Plane</code> from the origin along its normal.
  68      * @throws IllegalArgumentException if <code>0==a==b==c</code>
  69      */
  70     public Plane(double a, double b, double c, double d)
  71     {
  72         if (a == 0 && b == 0 && c == 0)
  73         {
  74             String message = WorldWind.retrieveErrMsg("geom.Plane.VectorIsZero");
  75             WorldWind.logger().log(java.util.logging.Level.FINE, message);
  76             throw new IllegalArgumentException(message);
  77         }
  78
  79         this.n = new Point(a, b, c, d);
  80     }
  81
  82     /**
  83      * Retrieves a <code>Point</code> representing the normal to this <code>Plane</code>.
  84      *
  85      * @return a <code>Point</code> representing the normal to this <code>Plane</code>
  86      */
  87     public final Point getNormal()
  88     {
  89         return new Point(this.n.x(), this.n.y(), this.n.z());
  90     }
  91
  92     /**
  93      * Retrieves the distance from the origin to this <code>Plane</code>. Two options exist for defining distance - the
  94      * first represents the distance from the origin to the <code>Plane</code>, the second represents the distance from
  95      * the <code>Plane</code> to the origin. This function uses the first method. The outcome of this is that depending
  96      * on the caller's view of this method, the sign of distances may appear to be reversed.
  97      *
  98      * @return the distance between this <code>Plane</code> and the origin
  99      */
 100     public final double getDistance()
 101     {
 102         return this.n.w();
 103     }
 104
 105     /**
 106      * Retrieves a vector representing the normal and distance to this <code>Plane</code>. The
 107      * vector has the structure (x, y, z, distance), where (x, y, z) represents the normal, and distance
 108      * represents the distance from the origin.
 109      *
 110      * @return a <code>Vector</code> representation of this <code>Plane</code>
 111      */
 112     public final Point getVector()
 113     {
 114         return this.n;
 115     }
 116
 117     /**
 118      * Calculates the dot product of this <code>Plane</code> with Point <code>p</code>.
 119      *
 120      * @param p the Point to dot with this <code>Plane</code>
 121      * @return the dot product of <code>p</code> and this <code>Plane</code>
 122      * @throws IllegalArgumentException if <code>p</code> is null
 123      */
 124     public final double dot(Point p)
 125     {
 126         if (p == null)
 127         {
 128             String message = WorldWind.retrieveErrMsg("nullValue.PointIsNull");
 129             WorldWind.logger().log(java.util.logging.Level.FINE, message);
 130             throw new IllegalArgumentException(message);
 131         }
 132
 133         return this.n.x() * p.x() + this.n.y() * p.y() + this.n.z() * p.z() + this.n.w() * p.w();
 134     }
 135
 136     @Override
 137     public final String toString()
 138     {
 139         return this.n.toString();
 140     }
 141
 142     @Override
 143     public final boolean equals(Object o)
 144     {
 145         if (this == o)
 146             return true;
 147         if (o == null || getClass() != o.getClass())
 148             return false;
 149
 150         final gov.nasa.worldwind.geom.Plane plane = (gov.nasa.worldwind.geom.Plane) o;
 151
 152         //noinspection RedundantIfStatement
 153         if (!this.n.normalize().equals(plane.n.normalize()))
 154             return false;
 155
 156         return true;
 157     }
 158
 159     @Override
 160     public final int hashCode()
 161     {
 162         return this.n.hashCode();
 163     }
 164 }