org.apache.commons.geometry.core.Vector Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of commons-geometry-core Show documentation
Core interfaces and classes for Apache Commons Geometry.
There is a newer version: 1.0
Show newest version
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.geometry.core;

/** Interface representing a vector in a vector space or displacement vectors
 * in an affine space.
 *
 * This interface uses self-referencing generic parameters to ensure
 * that implementations are only used with instances of their own type.
 * This removes the need for casting inside of methods in order to access
 * implementation-specific data, such as coordinate values.
 * 
 *
 * @see Vector space
 * @see Affine space
 *
 * @param  Vector implementation type
 */
public interface Vector> extends Spatial {

    /** Get the zero (null) vector of the space.
     * @return zero vector of the space
     */
    V getZero();

    /** Get the L₂ norm (commonly known as the Euclidean norm) for the vector.
     * This corresponds to the common notion of vector magnitude or length and
     * is defined as the square root of the sum of the squares of all vector components.
     * @see L2 Norm
     * @return L₂ norm for the vector
     */
    double norm();

    /** Get the square of the L₂ norm (also known as the Euclidean norm)
     * for the vector. This is equal to the sum of the squares of all vector components.
     * @see #norm()
     * @return square of the L₂ norm for the vector
     */
    double normSq();

    /** Returns a vector with the same direction but with the given
     * norm. This is equivalent to calling {@code vec.normalize().scalarMultiply(mag)}
     * but without the intermediate vector.
     * @param norm The vector norm
     * @return a vector with the same direction as the current instance but the given norm
     */
    V withNorm(double norm);

    /** Add a vector to the instance.
     * @param v vector to add
     * @return a new vector
     */
    V add(V v);

    /** Add a scaled vector to the instance.
     * @param factor scale factor to apply to v before adding it
     * @param v vector to add
     * @return a new vector
     */
    V add(double factor, V v);

    /** Subtract a vector from the instance.
     * @param v vector to subtract
     * @return a new vector
     */
    V subtract(V v);

    /** Subtract a scaled vector from the instance.
     * @param factor scale factor to apply to v before subtracting it
     * @param v vector to subtract
     * @return a new vector
     */
    V subtract(double factor, V v);

    /** Get the negation of the instance.
     * @return a new vector which is the negation of the instance
     */
    V negate();

    /** Get a normalized vector aligned with the instance. The returned
     * vector has a magnitude of 1.
     * @return a new normalized vector
     * @throws IllegalArgumentException if the norm is zero, NaN, or infinite
     */
    V normalize();

    /** Multiply the instance by a scalar.
     * @param a scalar
     * @return a new vector
     */
    V multiply(double a);

    /** Compute the distance between the instance and another vector.
     * @param v second vector
     * @return the distance between the instance and v
     */
    double distance(V v);

    /** Compute the square of the distance between the instance and another vector.
     * Calling this method is equivalent to calling:
     * q.subtract(p).getNormSq() except that no intermediate
     * vector is built
     * @see #normSq()
     * @param v second vector
     * @return the square of the distance between the instance and p
     */
    double distanceSq(V v);

    /** Compute the dot-product of the instance and another vector.
     * @param v second vector
     * @return the dot product (this · v)
     */
    double dot(V v);

    /** Compute the angular separation between two vectors in radians.
     * @param v other vector
     * @return angular separation between this instance and v in radians
     * @throws IllegalArgumentException if either vector has a zero, NaN, or infinite norm
     */
    double angle(V v);
}