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.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  }