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 package org.apache.commons.geometry.euclidean;
18
19 /**
20 * Abstract base class for Euclidean vectors with two or more dimensions.
21 *
22 * @param <V> Vector implementation type
23 */
24 public abstract class MultiDimensionalEuclideanVector<V extends MultiDimensionalEuclideanVector<V>>
25 extends EuclideanVector<V> {
26 /** Get the projection of the instance onto the given base vector. The returned
27 * vector is parallel to {@code base}. Vector projection and rejection onto
28 * a given base are related by the equation
29 * <code>
30 * <strong>v</strong> = <strong>v<sub>projection</sub></strong> + <strong>v<sub>rejection</sub></strong>
31 * </code>
32 * @param base base vector
33 * @return the vector projection of the instance onto {@code base}
34 * @exception IllegalArgumentException if the norm of the base vector is zero, NaN, or infinite
35 * @see #reject(MultiDimensionalEuclideanVector)
36 */
37 public abstract V project(V base);
38
39 /** Get the rejection of the instance from the given base vector. The returned
40 * vector is orthogonal to {@code base}. This operation can be interpreted as
41 * returning the orthogonal projection of the instance onto the hyperplane
42 * orthogonal to {@code base}. Vector projection and rejection onto
43 * a given base are related by the equation
44 * <code>
45 * <strong>v</strong> = <strong>v<sub>projection</sub></strong> + <strong>v<sub>rejection</sub></strong>
46 * </code>
47 * @param base base vector
48 * @return the vector rejection of the instance from {@code base}
49 * @exception IllegalArgumentException if the norm of the base vector is zero, NaN, or infinite
50 * @see #project(MultiDimensionalEuclideanVector)
51 */
52 public abstract V reject(V base);
53
54 /** Get a unit vector orthogonal to the instance.
55 * @return a unit vector orthogonal to the current instance
56 * @throws IllegalArgumentException if the norm of the current instance is zero, NaN, or infinite
57 */
58 public abstract V orthogonal();
59
60 /** Get a unit vector orthogonal to the current vector and pointing in the direction
61 * of {@code dir}. This method is equivalent to calling {@code dir.reject(vec).normalize()}
62 * except that no intermediate vector object is produced.
63 * @param dir the direction to use for generating the orthogonal vector
64 * @return unit vector orthogonal to the current vector and pointing in the direction of
65 * {@code dir} that does not lie along the current vector
66 * @throws IllegalArgumentException if either vector norm is zero, NaN or infinite, or the
67 * given vector is collinear with this vector.
68 */
69 public abstract V orthogonal(V dir);
70 }