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.core;
18
19 /** Interface representing a vector in a vector space or displacement vectors
20 * in an affine space.
21 *
22 * <p>This interface uses self-referencing generic parameters to ensure
23 * that implementations are only used with instances of their own type.
24 * This removes the need for casting inside of methods in order to access
25 * implementation-specific data, such as coordinate values.
26 * </p>
27 *
28 * @see <a href="https://en.wikipedia.org/wiki/Vector_space">Vector space</a>
29 * @see <a href="https://en.wikipedia.org/wiki/Affine_space">Affine space</a>
30 *
31 * @param <V> Vector implementation type
32 */
33 public interface Vector<V extends Vector<V>> extends Spatial {
34
35 /** Get the zero (null) vector of the space.
36 * @return zero vector of the space
37 */
38 V getZero();
39
40 /** Get the L<sub>2</sub> norm (commonly known as the Euclidean norm) for the vector.
41 * This corresponds to the common notion of vector magnitude or length and
42 * is defined as the square root of the sum of the squares of all vector components.
43 * @see <a href="http://mathworld.wolfram.com/L2-Norm.html">L2 Norm</a>
44 * @return L<sub>2</sub> norm for the vector
45 */
46 double norm();
47
48 /** Get the square of the L<sub>2</sub> norm (also known as the Euclidean norm)
49 * for the vector. This is equal to the sum of the squares of all vector components.
50 * @see #norm()
51 * @return square of the L<sub>2</sub> norm for the vector
52 */
53 double normSq();
54
55 /** Returns a vector with the same direction but with the given
56 * norm. This is equivalent to calling {@code vec.normalize().scalarMultiply(mag)}
57 * but without the intermediate vector.
58 * @param norm The vector norm
59 * @return a vector with the same direction as the current instance but the given norm
60 */
61 V withNorm(double norm);
62
63 /** Add a vector to the instance.
64 * @param v vector to add
65 * @return a new vector
66 */
67 V add(V v);
68
69 /** Add a scaled vector to the instance.
70 * @param factor scale factor to apply to v before adding it
71 * @param v vector to add
72 * @return a new vector
73 */
74 V add(double factor, V v);
75
76 /** Subtract a vector from the instance.
77 * @param v vector to subtract
78 * @return a new vector
79 */
80 V subtract(V v);
81
82 /** Subtract a scaled vector from the instance.
83 * @param factor scale factor to apply to v before subtracting it
84 * @param v vector to subtract
85 * @return a new vector
86 */
87 V subtract(double factor, V v);
88
89 /** Get the negation of the instance.
90 * @return a new vector which is the negation of the instance
91 */
92 V negate();
93
94 /** Get a normalized vector aligned with the instance. The returned
95 * vector has a magnitude of 1.
96 * @return a new normalized vector
97 * @throws IllegalArgumentException if the norm is zero, NaN, or infinite
98 */
99 V normalize();
100
101 /** Multiply the instance by a scalar.
102 * @param a scalar
103 * @return a new vector
104 */
105 V multiply(double a);
106
107 /** Compute the distance between the instance and another vector.
108 * @param v second vector
109 * @return the distance between the instance and v
110 */
111 double distance(V v);
112
113 /** Compute the square of the distance between the instance and another vector.
114 * <p>Calling this method is equivalent to calling:
115 * <code>q.subtract(p).getNormSq()</code> except that no intermediate
116 * vector is built</p>
117 * @see #normSq()
118 * @param v second vector
119 * @return the square of the distance between the instance and p
120 */
121 double distanceSq(V v);
122
123 /** Compute the dot-product of the instance and another vector.
124 * @param v second vector
125 * @return the dot product (this · v)
126 */
127 double dot(V v);
128
129 /** Compute the angular separation between two vectors in radians.
130 * @param v other vector
131 * @return angular separation between this instance and v in radians
132 * @throws IllegalArgumentException if either vector has a zero, NaN, or infinite norm
133 */
134 double angle(V v);
135 }