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
9
* http://www.apache.org/licenses/LICENSE-2.0
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.
18
package org.apache.commons.math.geometry;
20
import java.io.Serializable;
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) $
30
implements Serializable {
32
/** First canonical vector (coordinates: 1, 0, 0). */
33
public static final Vector3D plusI = new Vector3D(1, 0, 0);
35
/** Opposite of the first canonical vector (coordinates: -1, 0, 0). */
36
public static final Vector3D minusI = new Vector3D(-1, 0, 0);
38
/** Second canonical vector (coordinates: 0, 1, 0). */
39
public static final Vector3D plusJ = new Vector3D(0, 1, 0);
41
/** Opposite of the second canonical vector (coordinates: 0, -1, 0). */
42
public static final Vector3D minusJ = new Vector3D(0, -1, 0);
44
/** Third canonical vector (coordinates: 0, 0, 1). */
45
public static final Vector3D plusK = new Vector3D(0, 0, 1);
47
/** Opposite of the third canonical vector (coordinates: 0, 0, -1). */
48
public static final Vector3D minusK = new Vector3D(0, 0, -1);
50
/** Null vector (coordinates: 0, 0, 0). */
51
public static final Vector3D zero = new Vector3D(0, 0, 0);
53
/** Simple constructor.
54
* Build a null vector.
62
/** Simple constructor.
63
* Build a vector from its coordinates
71
public Vector3D(double x, double y, double z) {
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
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);
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
98
public Vector3D(double a, Vector3D u) {
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
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;
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
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;
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
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;
154
/** Get the abscissa of the vector.
155
* @return abscissa of the vector
156
* @see #Vector3D(double, double, double)
158
public double getX() {
162
/** Get the ordinate of the vector.
163
* @return ordinate of the vector
164
* @see #Vector3D(double, double, double)
166
public double getY() {
170
/** Get the height of the vector.
171
* @return height of the vector
172
* @see #Vector3D(double, double, double)
174
public double getZ() {
178
/** Get the norm for the vector.
179
* @return euclidian norm for the vector
181
public double getNorm() {
182
return Math.sqrt (x * x + y * y + z * z);
185
/** Get the azimuth of the vector.
186
* @return azimuth (α) of the vector, between -π and +π
187
* @see #Vector3D(double, double)
189
public double getAlpha() {
190
return Math.atan2(y, x);
193
/** Get the elevation of the vector.
194
* @return elevation (δ) of the vector, between -π/2 and +π/2
195
* @see #Vector3D(double, double)
197
public double getDelta() {
198
return Math.asin(z / getNorm());
201
/** Add a vector to the instance.
202
* @param v vector to add
203
* @return a new vector
205
public Vector3D add(Vector3D v) {
206
return new Vector3D(x + v.x, y + v.y, z + v.z);
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
214
public Vector3D add(double factor, Vector3D v) {
215
return new Vector3D(x + factor * v.x, y + factor * v.y, z + factor * v.z);
218
/** Subtract a vector from the instance.
219
* @param v vector to subtract
220
* @return a new vector
222
public Vector3D subtract(Vector3D v) {
223
return new Vector3D(x - v.x, y - v.y, z - v.z);
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
231
public Vector3D subtract(double factor, Vector3D v) {
232
return new Vector3D(x - factor * v.x, y - factor * v.y, z - factor * v.z);
235
/** Get a normalized vector aligned with the instance.
236
* @return a new normalized vector
237
* @exception ArithmeticException if the norm is zero
239
public Vector3D normalize() {
240
double s = getNorm();
242
throw new ArithmeticException("cannot normalize a zero norm vector");
244
return scalarMultiply(1 / s);
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 :
255
* Vector3D k = u.normalize();
256
* Vector3D i = k.orthogonal();
257
* Vector3D j = Vector3D.crossProduct(k, i);
259
* @return a new normalized vector orthogonal to the instance
260
* @exception ArithmeticException if the norm of the instance is null
262
public Vector3D orthogonal() {
264
double threshold = 0.6 * getNorm();
265
if (threshold == 0) {
266
throw new ArithmeticException("null norm");
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);
276
double inverse = 1 / Math.sqrt(x * x + y * y);
277
return new Vector3D(inverse * y, -inverse * x, 0);
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
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
292
public static double angle(Vector3D v1, Vector3D v2) {
294
double normProduct = v1.getNorm() * v2.getNorm();
295
if (normProduct == 0) {
296
throw new ArithmeticException("null norm");
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);
305
return Math.asin(v3.getNorm() / normProduct);
307
return Math.PI - Math.asin(v3.getNorm() / normProduct);
310
// the vectors are sufficiently separated to use the cosine
311
return Math.acos(dot / normProduct);
315
/** Get the opposite of the instance.
316
* @return a new vector which is opposite to the instance
318
public Vector3D negate() {
319
return new Vector3D(-x, -y, -z);
322
/** Multiply the instance by a scalar
324
* @return a new vector
326
public Vector3D scalarMultiply(double a) {
327
return new Vector3D(a * x, a * y, a * z);
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
335
public static double dotProduct(Vector3D v1, Vector3D v2) {
336
return v1.x * v2.x + v1.y * v2.y + v1.z * v2.z;
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
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);
351
private final double x;
354
private final double y;
357
private final double z;
359
/** Serializable version identifier */
360
private static final long serialVersionUID = -5721105387745193385L;
added
removed
src/java/org/apache/commons/math/geometry/Vector3D.java
