001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.geometry.euclidean;
018
019/**
020 * Abstract base class for Euclidean vectors with two or more dimensions.
021 *
022 * @param <V> Vector implementation type
023 */
024public abstract class MultiDimensionalEuclideanVector<V extends MultiDimensionalEuclideanVector<V>>
025        extends EuclideanVector<V> {
026    /** Get the projection of the instance onto the given base vector. The returned
027     * vector is parallel to {@code base}. Vector projection and rejection onto
028     * a given base are related by the equation
029     * <code>
030     *      <strong>v</strong> = <strong>v<sub>projection</sub></strong> + <strong>v<sub>rejection</sub></strong>
031     * </code>
032     * @param base base vector
033     * @return the vector projection of the instance onto {@code base}
034     * @exception IllegalArgumentException if the norm of the base vector is zero, NaN, or infinite
035     * @see #reject(MultiDimensionalEuclideanVector)
036     */
037    public abstract V project(V base);
038
039    /** Get the rejection of the instance from the given base vector. The returned
040     * vector is orthogonal to {@code base}. This operation can be interpreted as
041     * returning the orthogonal projection of the instance onto the hyperplane
042     * orthogonal to {@code base}. Vector projection and rejection onto
043     * a given base are related by the equation
044     * <code>
045     *      <strong>v</strong> = <strong>v<sub>projection</sub></strong> + <strong>v<sub>rejection</sub></strong>
046     * </code>
047     * @param base base vector
048     * @return the vector rejection of the instance from {@code base}
049     * @exception IllegalArgumentException if the norm of the base vector is zero, NaN, or infinite
050     * @see #project(MultiDimensionalEuclideanVector)
051     */
052    public abstract V reject(V base);
053
054    /** Get a unit vector orthogonal to the instance.
055     * @return a unit vector orthogonal to the current instance
056     * @throws IllegalArgumentException if the norm of the current instance is zero, NaN, or infinite
057     */
058    public abstract V orthogonal();
059
060    /** Get a unit vector orthogonal to the current vector and pointing in the direction
061     * of {@code dir}. This method is equivalent to calling {@code dir.reject(vec).normalize()}
062     * except that no intermediate vector object is produced.
063     * @param dir the direction to use for generating the orthogonal vector
064     * @return unit vector orthogonal to the current vector and pointing in the direction of
065     *      {@code dir} that does not lie along the current vector
066     * @throws IllegalArgumentException if either vector norm is zero, NaN or infinite, or the
067     *      given vector is collinear with this vector.
068     */
069    public abstract V orthogonal(V dir);
070}