1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.math.geometry; 19 20 import java.io.Serializable; 21 22 /** 23 * This class implements vectors in a three-dimensional space. 24 * <p>Instance of this class are guaranteed to be immutable.</p> 25 * @version $Revision: 627998 $ $Date: 2008-02-15 03:24:50 -0700 (Fri, 15 Feb 2008) $ 26 * @since 1.2 27 */ 28 29 public class Vector3D 30 implements Serializable { 31 32 /** First canonical vector (coordinates: 1, 0, 0). */ 33 public static final Vector3D plusI = new Vector3D(1, 0, 0); 34 35 /** Opposite of the first canonical vector (coordinates: -1, 0, 0). */ 36 public static final Vector3D minusI = new Vector3D(-1, 0, 0); 37 38 /** Second canonical vector (coordinates: 0, 1, 0). */ 39 public static final Vector3D plusJ = new Vector3D(0, 1, 0); 40 41 /** Opposite of the second canonical vector (coordinates: 0, -1, 0). */ 42 public static final Vector3D minusJ = new Vector3D(0, -1, 0); 43 44 /** Third canonical vector (coordinates: 0, 0, 1). */ 45 public static final Vector3D plusK = new Vector3D(0, 0, 1); 46 47 /** Opposite of the third canonical vector (coordinates: 0, 0, -1). */ 48 public static final Vector3D minusK = new Vector3D(0, 0, -1); 49 50 /** Null vector (coordinates: 0, 0, 0). */ 51 public static final Vector3D zero = new Vector3D(0, 0, 0); 52 53 /** Simple constructor. 54 * Build a null vector. 55 */ 56 public Vector3D() { 57 x = 0; 58 y = 0; 59 z = 0; 60 } 61 62 /** Simple constructor. 63 * Build a vector from its coordinates 64 * @param x abscissa 65 * @param y ordinate 66 * @param z height 67 * @see #getX() 68 * @see #getY() 69 * @see #getZ() 70 */ 71 public Vector3D(double x, double y, double z) { 72 this.x = x; 73 this.y = y; 74 this.z = z; 75 } 76 77 /** Simple constructor. 78 * Build a vector from its azimuthal coordinates 79 * @param alpha azimuth (α) around Z 80 * (0 is +X, π/2 is +Y, π is -X and 3π/2 is -Y) 81 * @param delta elevation (δ) above (XY) plane, from -π/2 to +π/2 82 * @see #getAlpha() 83 * @see #getDelta() 84 */ 85 public Vector3D(double alpha, double delta) { 86 double cosDelta = Math.cos(delta); 87 this.x = Math.cos(alpha) * cosDelta; 88 this.y = Math.sin(alpha) * cosDelta; 89 this.z = Math.sin(delta); 90 } 91 92 /** Multiplicative constructor 93 * Build a vector from another one and a scale factor. 94 * The vector built will be a * u 95 * @param a scale factor 96 * @param u base (unscaled) vector 97 */ 98 public Vector3D(double a, Vector3D u) { 99 this.x = a * u.x; 100 this.y = a * u.y; 101 this.z = a * u.z; 102 } 103 104 /** Linear constructor 105 * Build a vector from two other ones and corresponding scale factors. 106 * The vector built will be a1 * u1 + a2 * u2 107 * @param a1 first scale factor 108 * @param u1 first base (unscaled) vector 109 * @param a2 second scale factor 110 * @param u2 second base (unscaled) vector 111 */ 112 public Vector3D(double a1, Vector3D u1, double a2, Vector3D u2) { 113 this.x = a1 * u1.x + a2 * u2.x; 114 this.y = a1 * u1.y + a2 * u2.y; 115 this.z = a1 * u1.z + a2 * u2.z; 116 } 117 118 /** Linear constructor 119 * Build a vector from three other ones and corresponding scale factors. 120 * The vector built will be a1 * u1 + a2 * u2 + a3 * u3 121 * @param a1 first scale factor 122 * @param u1 first base (unscaled) vector 123 * @param a2 second scale factor 124 * @param u2 second base (unscaled) vector 125 * @param a3 third scale factor 126 * @param u3 third base (unscaled) vector 127 */ 128 public Vector3D(double a1, Vector3D u1, double a2, Vector3D u2, 129 double a3, Vector3D u3) { 130 this.x = a1 * u1.x + a2 * u2.x + a3 * u3.x; 131 this.y = a1 * u1.y + a2 * u2.y + a3 * u3.y; 132 this.z = a1 * u1.z + a2 * u2.z + a3 * u3.z; 133 } 134 135 /** Linear constructor 136 * Build a vector from four other ones and corresponding scale factors. 137 * The vector built will be a1 * u1 + a2 * u2 + a3 * u3 + a4 * u4 138 * @param a1 first scale factor 139 * @param u1 first base (unscaled) vector 140 * @param a2 second scale factor 141 * @param u2 second base (unscaled) vector 142 * @param a3 third scale factor 143 * @param u3 third base (unscaled) vector 144 * @param a4 fourth scale factor 145 * @param u4 fourth base (unscaled) vector 146 */ 147 public Vector3D(double a1, Vector3D u1, double a2, Vector3D u2, 148 double a3, Vector3D u3, double a4, Vector3D u4) { 149 this.x = a1 * u1.x + a2 * u2.x + a3 * u3.x + a4 * u4.x; 150 this.y = a1 * u1.y + a2 * u2.y + a3 * u3.y + a4 * u4.y; 151 this.z = a1 * u1.z + a2 * u2.z + a3 * u3.z + a4 * u4.z; 152 } 153 154 /** Get the abscissa of the vector. 155 * @return abscissa of the vector 156 * @see #Vector3D(double, double, double) 157 */ 158 public double getX() { 159 return x; 160 } 161 162 /** Get the ordinate of the vector. 163 * @return ordinate of the vector 164 * @see #Vector3D(double, double, double) 165 */ 166 public double getY() { 167 return y; 168 } 169 170 /** Get the height of the vector. 171 * @return height of the vector 172 * @see #Vector3D(double, double, double) 173 */ 174 public double getZ() { 175 return z; 176 } 177 178 /** Get the norm for the vector. 179 * @return euclidian norm for the vector 180 */ 181 public double getNorm() { 182 return Math.sqrt (x * x + y * y + z * z); 183 } 184 185 /** Get the azimuth of the vector. 186 * @return azimuth (α) of the vector, between -π and +π 187 * @see #Vector3D(double, double) 188 */ 189 public double getAlpha() { 190 return Math.atan2(y, x); 191 } 192 193 /** Get the elevation of the vector. 194 * @return elevation (δ) of the vector, between -π/2 and +π/2 195 * @see #Vector3D(double, double) 196 */ 197 public double getDelta() { 198 return Math.asin(z / getNorm()); 199 } 200 201 /** Add a vector to the instance. 202 * @param v vector to add 203 * @return a new vector 204 */ 205 public Vector3D add(Vector3D v) { 206 return new Vector3D(x + v.x, y + v.y, z + v.z); 207 } 208 209 /** Add a scaled vector to the instance. 210 * @param factor scale factor to apply to v before adding it 211 * @param v vector to add 212 * @return a new vector 213 */ 214 public Vector3D add(double factor, Vector3D v) { 215 return new Vector3D(x + factor * v.x, y + factor * v.y, z + factor * v.z); 216 } 217 218 /** Subtract a vector from the instance. 219 * @param v vector to subtract 220 * @return a new vector 221 */ 222 public Vector3D subtract(Vector3D v) { 223 return new Vector3D(x - v.x, y - v.y, z - v.z); 224 } 225 226 /** Subtract a scaled vector from the instance. 227 * @param factor scale factor to apply to v before subtracting it 228 * @param v vector to subtract 229 * @return a new vector 230 */ 231 public Vector3D subtract(double factor, Vector3D v) { 232 return new Vector3D(x - factor * v.x, y - factor * v.y, z - factor * v.z); 233 } 234 235 /** Get a normalized vector aligned with the instance. 236 * @return a new normalized vector 237 * @exception ArithmeticException if the norm is zero 238 */ 239 public Vector3D normalize() { 240 double s = getNorm(); 241 if (s == 0) { 242 throw new ArithmeticException("cannot normalize a zero norm vector"); 243 } 244 return scalarMultiply(1 / s); 245 } 246 247 /** Get a vector orthogonal to the instance. 248 * <p>There are an infinite number of normalized vectors orthogonal 249 * to the instance. This method picks up one of them almost 250 * arbitrarily. It is useful when one needs to compute a reference 251 * frame with one of the axes in a predefined direction. The 252 * following example shows how to build a frame having the k axis 253 * aligned with the known vector u : 254 * <pre><code> 255 * Vector3D k = u.normalize(); 256 * Vector3D i = k.orthogonal(); 257 * Vector3D j = Vector3D.crossProduct(k, i); 258 * </code></pre></p> 259 * @return a new normalized vector orthogonal to the instance 260 * @exception ArithmeticException if the norm of the instance is null 261 */ 262 public Vector3D orthogonal() { 263 264 double threshold = 0.6 * getNorm(); 265 if (threshold == 0) { 266 throw new ArithmeticException("null norm"); 267 } 268 269 if ((x >= -threshold) && (x <= threshold)) { 270 double inverse = 1 / Math.sqrt(y * y + z * z); 271 return new Vector3D(0, inverse * z, -inverse * y); 272 } else if ((y >= -threshold) && (y <= threshold)) { 273 double inverse = 1 / Math.sqrt(x * x + z * z); 274 return new Vector3D(-inverse * z, 0, inverse * x); 275 } 276 double inverse = 1 / Math.sqrt(x * x + y * y); 277 return new Vector3D(inverse * y, -inverse * x, 0); 278 279 } 280 281 /** Compute the angular separation between two vectors. 282 * <p>This method computes the angular separation between two 283 * vectors using the dot product for well separated vectors and the 284 * cross product for almost aligned vectors. This allow to have a 285 * good accuracy in all cases, even for vectors very close to each 286 * other.</p> 287 * @param v1 first vector 288 * @param v2 second vector 289 * @return angular separation between v1 and v2 290 * @exception ArithmeticException if either vector has a null norm 291 */ 292 public static double angle(Vector3D v1, Vector3D v2) { 293 294 double normProduct = v1.getNorm() * v2.getNorm(); 295 if (normProduct == 0) { 296 throw new ArithmeticException("null norm"); 297 } 298 299 double dot = dotProduct(v1, v2); 300 double threshold = normProduct * 0.9999; 301 if ((dot < -threshold) || (dot > threshold)) { 302 // the vectors are almost aligned, compute using the sine 303 Vector3D v3 = crossProduct(v1, v2); 304 if (dot >= 0) { 305 return Math.asin(v3.getNorm() / normProduct); 306 } 307 return Math.PI - Math.asin(v3.getNorm() / normProduct); 308 } 309 310 // the vectors are sufficiently separated to use the cosine 311 return Math.acos(dot / normProduct); 312 313 } 314 315 /** Get the opposite of the instance. 316 * @return a new vector which is opposite to the instance 317 */ 318 public Vector3D negate() { 319 return new Vector3D(-x, -y, -z); 320 } 321 322 /** Multiply the instance by a scalar 323 * @param a scalar 324 * @return a new vector 325 */ 326 public Vector3D scalarMultiply(double a) { 327 return new Vector3D(a * x, a * y, a * z); 328 } 329 330 /** Compute the dot-product of two vectors. 331 * @param v1 first vector 332 * @param v2 second vector 333 * @return the dot product v1.v2 334 */ 335 public static double dotProduct(Vector3D v1, Vector3D v2) { 336 return v1.x * v2.x + v1.y * v2.y + v1.z * v2.z; 337 } 338 339 /** Compute the cross-product of two vectors. 340 * @param v1 first vector 341 * @param v2 second vector 342 * @return the cross product v1 ^ v2 as a new Vector 343 */ 344 public static Vector3D crossProduct(Vector3D v1, Vector3D v2) { 345 return new Vector3D(v1.y * v2.z - v1.z * v2.y, 346 v1.z * v2.x - v1.x * v2.z, 347 v1.x * v2.y - v1.y * v2.x); 348 } 349 350 /** Abscissa. */ 351 private final double x; 352 353 /** Ordinate. */ 354 private final double y; 355 356 /** Height. */ 357 private final double z; 358 359 /** Serializable version identifier */ 360 private static final long serialVersionUID = -5721105387745193385L; 361 362 363 }