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 }