    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     */
    017    package org.apache.commons.math3.geometry.euclidean.twod;
    018
    019    import java.text.NumberFormat;
    020
    021    import org.apache.commons.math3.exception.DimensionMismatchException;
    022    import org.apache.commons.math3.exception.MathArithmeticException;
    023    import org.apache.commons.math3.exception.util.LocalizedFormats;
    024    import org.apache.commons.math3.geometry.Space;
    025    import org.apache.commons.math3.geometry.Vector;
    026    import org.apache.commons.math3.util.FastMath;
    027    import org.apache.commons.math3.util.MathUtils;
    028
    029    /** This class represents a 2D vector.
    030     * <p>Instances of this class are guaranteed to be immutable.</p>
    031     * @version $Id: Vector2D.java 1416643 2012-12-03 19:37:14Z tn $
    032     * @since 3.0
    033     */
    034    public class Vector2D implements Vector<Euclidean2D> {
    035
    036        /** Origin (coordinates: 0, 0). */
    037        public static final Vector2D ZERO   = new Vector2D(0, 0);
    038
    039        // CHECKSTYLE: stop ConstantName
    040        /** A vector with all coordinates set to NaN. */
    041        public static final Vector2D NaN = new Vector2D(Double.NaN, Double.NaN);
    042        // CHECKSTYLE: resume ConstantName
    043
    044        /** A vector with all coordinates set to positive infinity. */
    045        public static final Vector2D POSITIVE_INFINITY =
    046            new Vector2D(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY);
    047
    048        /** A vector with all coordinates set to negative infinity. */
    049        public static final Vector2D NEGATIVE_INFINITY =
    050            new Vector2D(Double.NEGATIVE_INFINITY, Double.NEGATIVE_INFINITY);
    051
    052        /** Serializable UID. */
    053        private static final long serialVersionUID = 266938651998679754L;
    054
    055        /** Abscissa. */
    056        private final double x;
    057
    058        /** Ordinate. */
    059        private final double y;
    060
    061        /** Simple constructor.
    062         * Build a vector from its coordinates
    063         * @param x abscissa
    064         * @param y ordinate
    065         * @see #getX()
    066         * @see #getY()
    067         */
    068        public Vector2D(double x, double y) {
    069            this.x = x;
    070            this.y = y;
    071        }
    072
    073        /** Simple constructor.
    074         * Build a vector from its coordinates
    075         * @param v coordinates array
    076         * @exception DimensionMismatchException if array does not have 2 elements
    077         * @see #toArray()
    078         */
    079        public Vector2D(double[] v) throws DimensionMismatchException {
    080            if (v.length != 2) {
    081                throw new DimensionMismatchException(v.length, 2);
    082            }
    083            this.x = v[0];
    084            this.y = v[1];
    085        }
    086
    087        /** Multiplicative constructor
    088         * Build a vector from another one and a scale factor.
    089         * The vector built will be a * u
    090         * @param a scale factor
    091         * @param u base (unscaled) vector
    092         */
    093        public Vector2D(double a, Vector2D u) {
    094            this.x = a * u.x;
    095            this.y = a * u.y;
    096        }
    097
    098        /** Linear constructor
    099         * Build a vector from two other ones and corresponding scale factors.
    100         * The vector built will be a1 * u1 + a2 * u2
    101         * @param a1 first scale factor
    102         * @param u1 first base (unscaled) vector
    103         * @param a2 second scale factor
    104         * @param u2 second base (unscaled) vector
    105         */
    106        public Vector2D(double a1, Vector2D u1, double a2, Vector2D u2) {
    107            this.x = a1 * u1.x + a2 * u2.x;
    108            this.y = a1 * u1.y + a2 * u2.y;
    109        }
    110
    111        /** Linear constructor
    112         * Build a vector from three other ones and corresponding scale factors.
    113         * The vector built will be a1 * u1 + a2 * u2 + a3 * u3
    114         * @param a1 first scale factor
    115         * @param u1 first base (unscaled) vector
    116         * @param a2 second scale factor
    117         * @param u2 second base (unscaled) vector
    118         * @param a3 third scale factor
    119         * @param u3 third base (unscaled) vector
    120         */
    121        public Vector2D(double a1, Vector2D u1, double a2, Vector2D u2,
    122                       double a3, Vector2D u3) {
    123            this.x = a1 * u1.x + a2 * u2.x + a3 * u3.x;
    124            this.y = a1 * u1.y + a2 * u2.y + a3 * u3.y;
    125        }
    126
    127        /** Linear constructor
    128         * Build a vector from four other ones and corresponding scale factors.
    129         * The vector built will be a1 * u1 + a2 * u2 + a3 * u3 + a4 * u4
    130         * @param a1 first scale factor
    131         * @param u1 first base (unscaled) vector
    132         * @param a2 second scale factor
    133         * @param u2 second base (unscaled) vector
    134         * @param a3 third scale factor
    135         * @param u3 third base (unscaled) vector
    136         * @param a4 fourth scale factor
    137         * @param u4 fourth base (unscaled) vector
    138         */
    139        public Vector2D(double a1, Vector2D u1, double a2, Vector2D u2,
    140                       double a3, Vector2D u3, double a4, Vector2D u4) {
    141            this.x = a1 * u1.x + a2 * u2.x + a3 * u3.x + a4 * u4.x;
    142            this.y = a1 * u1.y + a2 * u2.y + a3 * u3.y + a4 * u4.y;
    143        }
    144
    145        /** Get the abscissa of the vector.
    146         * @return abscissa of the vector
    147         * @see #Vector2D(double, double)
    148         */
    149        public double getX() {
    150            return x;
    151        }
    152
    153        /** Get the ordinate of the vector.
    154         * @return ordinate of the vector
    155         * @see #Vector2D(double, double)
    156         */
    157        public double getY() {
    158            return y;
    159        }
    160
    161        /** Get the vector coordinates as a dimension 2 array.
    162         * @return vector coordinates
    163         * @see #Vector2D(double[])
    164         */
    165        public double[] toArray() {
    166            return new double[] { x, y };
    167        }
    168
    169        /** {@inheritDoc} */
    170        public Space getSpace() {
    171            return Euclidean2D.getInstance();
    172        }
    173
    174        /** {@inheritDoc} */
    175        public Vector2D getZero() {
    176            return ZERO;
    177        }
    178
    179        /** {@inheritDoc} */
    180        public double getNorm1() {
    181            return FastMath.abs(x) + FastMath.abs(y);
    182        }
    183
    184        /** {@inheritDoc} */
    185        public double getNorm() {
    186            return FastMath.sqrt (x * x + y * y);
    187        }
    188
    189        /** {@inheritDoc} */
    190        public double getNormSq() {
    191            return x * x + y * y;
    192        }
    193
    194        /** {@inheritDoc} */
    195        public double getNormInf() {
    196            return FastMath.max(FastMath.abs(x), FastMath.abs(y));
    197        }
    198
    199        /** {@inheritDoc} */
    200        public Vector2D add(Vector<Euclidean2D> v) {
    201            Vector2D v2 = (Vector2D) v;
    202            return new Vector2D(x + v2.getX(), y + v2.getY());
    203        }
    204
    205        /** {@inheritDoc} */
    206        public Vector2D add(double factor, Vector<Euclidean2D> v) {
    207            Vector2D v2 = (Vector2D) v;
    208            return new Vector2D(x + factor * v2.getX(), y + factor * v2.getY());
    209        }
    210
    211        /** {@inheritDoc} */
    212        public Vector2D subtract(Vector<Euclidean2D> p) {
    213            Vector2D p3 = (Vector2D) p;
    214            return new Vector2D(x - p3.x, y - p3.y);
    215        }
    216
    217        /** {@inheritDoc} */
    218        public Vector2D subtract(double factor, Vector<Euclidean2D> v) {
    219            Vector2D v2 = (Vector2D) v;
    220            return new Vector2D(x - factor * v2.getX(), y - factor * v2.getY());
    221        }
    222
    223        /** {@inheritDoc} */
    224        public Vector2D normalize() throws MathArithmeticException {
    225            double s = getNorm();
    226            if (s == 0) {
    227                throw new MathArithmeticException(LocalizedFormats.CANNOT_NORMALIZE_A_ZERO_NORM_VECTOR);
    228            }
    229            return scalarMultiply(1 / s);
    230        }
    231        /** {@inheritDoc} */
    232        public Vector2D negate() {
    233            return new Vector2D(-x, -y);
    234        }
    235
    236        /** {@inheritDoc} */
    237        public Vector2D scalarMultiply(double a) {
    238            return new Vector2D(a * x, a * y);
    239        }
    240
    241        /** {@inheritDoc} */
    242        public boolean isNaN() {
    243            return Double.isNaN(x) || Double.isNaN(y);
    244        }
    245
    246        /** {@inheritDoc} */
    247        public boolean isInfinite() {
    248            return !isNaN() && (Double.isInfinite(x) || Double.isInfinite(y));
    249        }
    250
    251        /** {@inheritDoc} */
    252        public double distance1(Vector<Euclidean2D> p) {
    253            Vector2D p3 = (Vector2D) p;
    254            final double dx = FastMath.abs(p3.x - x);
    255            final double dy = FastMath.abs(p3.y - y);
    256            return dx + dy;
    257        }
    258
    259        /** {@inheritDoc} */
    260        public double distance(Vector<Euclidean2D> p) {
    261            Vector2D p3 = (Vector2D) p;
    262            final double dx = p3.x - x;
    263            final double dy = p3.y - y;
    264            return FastMath.sqrt(dx * dx + dy * dy);
    265        }
    266
    267        /** {@inheritDoc} */
    268        public double distanceInf(Vector<Euclidean2D> p) {
    269            Vector2D p3 = (Vector2D) p;
    270            final double dx = FastMath.abs(p3.x - x);
    271            final double dy = FastMath.abs(p3.y - y);
    272            return FastMath.max(dx, dy);
    273        }
    274
    275        /** {@inheritDoc} */
    276        public double distanceSq(Vector<Euclidean2D> p) {
    277            Vector2D p3 = (Vector2D) p;
    278            final double dx = p3.x - x;
    279            final double dy = p3.y - y;
    280            return dx * dx + dy * dy;
    281        }
    282
    283        /** {@inheritDoc} */
    284        public double dotProduct(final Vector<Euclidean2D> v) {
    285            final Vector2D v2 = (Vector2D) v;
    286            return x * v2.x + y * v2.y;
    287        }
    288
    289        /** Compute the distance between two vectors according to the L<sub>2</sub> norm.
    290         * <p>Calling this method is equivalent to calling:
    291         * <code>p1.subtract(p2).getNorm()</code> except that no intermediate
    292         * vector is built</p>
    293         * @param p1 first vector
    294         * @param p2 second vector
    295         * @return the distance between p1 and p2 according to the L<sub>2</sub> norm
    296         */
    297        public static double distance(Vector2D p1, Vector2D p2) {
    298            return p1.distance(p2);
    299        }
    300
    301        /** Compute the distance between two vectors according to the L<sub>&infin;</sub> norm.
    302         * <p>Calling this method is equivalent to calling:
    303         * <code>p1.subtract(p2).getNormInf()</code> except that no intermediate
    304         * vector is built</p>
    305         * @param p1 first vector
    306         * @param p2 second vector
    307         * @return the distance between p1 and p2 according to the L<sub>&infin;</sub> norm
    308         */
    309        public static double distanceInf(Vector2D p1, Vector2D p2) {
    310            return p1.distanceInf(p2);
    311        }
    312
    313        /** Compute the square of the distance between two vectors.
    314         * <p>Calling this method is equivalent to calling:
    315         * <code>p1.subtract(p2).getNormSq()</code> except that no intermediate
    316         * vector is built</p>
    317         * @param p1 first vector
    318         * @param p2 second vector
    319         * @return the square of the distance between p1 and p2
    320         */
    321        public static double distanceSq(Vector2D p1, Vector2D p2) {
    322            return p1.distanceSq(p2);
    323        }
    324
    325        /**
    326         * Test for the equality of two 2D vectors.
    327         * <p>
    328         * If all coordinates of two 2D vectors are exactly the same, and none are
    329         * <code>Double.NaN</code>, the two 2D vectors are considered to be equal.
    330         * </p>
    331         * <p>
    332         * <code>NaN</code> coordinates are considered to affect globally the vector
    333         * and be equals to each other - i.e, if either (or all) coordinates of the
    334         * 2D vector are equal to <code>Double.NaN</code>, the 2D vector is equal to
    335         * {@link #NaN}.
    336         * </p>
    337         *
    338         * @param other Object to test for equality to this
    339         * @return true if two 2D vector objects are equal, false if
    340         *         object is null, not an instance of Vector2D, or
    341         *         not equal to this Vector2D instance
    342         *
    343         */
    344        @Override
    345        public boolean equals(Object other) {
    346
    347            if (this == other) {
    348                return true;
    349            }
    350
    351            if (other instanceof Vector2D) {
    352                final Vector2D rhs = (Vector2D)other;
    353                if (rhs.isNaN()) {
    354                    return this.isNaN();
    355                }
    356
    357                return (x == rhs.x) && (y == rhs.y);
    358            }
    359            return false;
    360        }
    361
    362        /**
    363         * Get a hashCode for the 2D vector.
    364         * <p>
    365         * All NaN values have the same hash code.</p>
    366         *
    367         * @return a hash code value for this object
    368         */
    369        @Override
    370        public int hashCode() {
    371            if (isNaN()) {
    372                return 542;
    373            }
    374            return 122 * (76 * MathUtils.hash(x) +  MathUtils.hash(y));
    375        }
    376
    377        /** Get a string representation of this vector.
    378         * @return a string representation of this vector
    379         */
    380        @Override
    381        public String toString() {
    382            return Vector2DFormat.getInstance().format(this);
    383        }
    384
    385        /** {@inheritDoc} */
    386        public String toString(final NumberFormat format) {
    387            return new Vector2DFormat(format).format(this);
    388        }
    389
    390    }