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 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 &middot; 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 }