View Javadoc
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 normalized vector
97       * @throws IllegalArgumentException if the norm is zero, NaN, or infinite
98       * @see #normalizeOrNull()
99       */
100     V normalize();
101 
102     /** Attempt to compute a normalized vector aligned with the instance, returning null if
103      * such a vector cannot be computed. This method is equivalent to {@link #normalize()}
104      * but returns null instead of throwing an exception on failure.
105      * @return normalized vector or null if such a vector cannot be computed, i.e. if the
106      *      norm is zero, NaN, or infinite
107      * @see #normalize()
108      */
109     V normalizeOrNull();
110 
111     /** Multiply the instance by a scalar.
112      * @param a scalar
113      * @return a new vector
114      */
115     V multiply(double a);
116 
117     /** Compute the distance between the instance and another vector.
118      * @param v second vector
119      * @return the distance between the instance and v
120      */
121     double distance(V v);
122 
123     /** Compute the square of the distance between the instance and another vector.
124      * <p>Calling this method is equivalent to calling:
125      * <code>q.subtract(p).getNormSq()</code> except that no intermediate
126      * vector is built</p>
127      * @see #normSq()
128      * @param v second vector
129      * @return the square of the distance between the instance and p
130      */
131     double distanceSq(V v);
132 
133     /** Compute the dot-product of the instance and another vector.
134      * @param v second vector
135      * @return the dot product (this &middot; v)
136      */
137     double dot(V v);
138 
139     /** Compute the angular separation between two vectors in radians.
140      * @param v other vector
141      * @return angular separation between this instance and v in radians
142      * @throws IllegalArgumentException if either vector has a zero, NaN, or infinite norm
143      */
144     double angle(V v);
145 }