Source: geom/Vec3.js

/*
 * Copyright 2015-2017 WorldWind Contributors
 *
 * Licensed 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.
 */
define([
        '../util/Logger',
        '../error/ArgumentError'
    ],
    function (Logger,
              ArgumentError) {
        "use strict";

        /**
         * Constructs a three-component vector.
         * @alias Vec3
         * @classdesc Represents a three-component vector. Access the X component of the vector as v[0], the Y
         * component as v[1] and the Z component as v[2].
         * @augments Float64Array
         * @param {Number} x X component of vector.
         * @param {Number} y Y component of vector.
         * @param {Number} z Z component of vector.
         * @constructor
         */
        var Vec3 = function Vec3(x, y, z) {
            this[0] = x;
            this[1] = y;
            this[2] = z;
        };

        // Vec3 extends Float64Array.
        Vec3.prototype = new Float64Array(3);

        /**
         * A vector corresponding to the origin.
         * @type {Vec3}
         */
        Vec3.ZERO = new Vec3(0, 0, 0);

        /**
         * Computes the average of a specified array of vectors.
         * @param {Vec3[]} vectors The vectors whose average to compute.
         * @param {Vec3} result A pre-allocated Vec3 in which to return the computed average.
         * @returns {Vec3} The result argument set to the average of the specified array of vectors.
         * @throws {ArgumentError} If the specified array of vectors is null, undefined or empty or the specified
         * result argument is null or undefined.
         */
        Vec3.average = function (vectors, result) {
            if (!vectors || vectors.length < 1) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "average", "missingArray"));
            }

            if (!result) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "average", "missingResult"));
            }

            var count = vectors.length,
                vec;

            result[0] = 0;
            result[1] = 0;
            result[2] = 0;

            for (var i = 0, len = vectors.length; i < len; i++) {
                vec = vectors[i];

                result[0] += vec[0] / count;
                result[1] += vec[1] / count;
                result[2] += vec[2] / count;
            }

            return result;
        };

        /**
         * Computes the average of a specified array of points packed into a single array.
         * @param {Float32Array | Float64Array | Number[]} points The points whose average to compute.
         * @param {Vec3} result A pre-allocated Vec3 in which to return the computed average.
         * @returns {Vec3} The result argument set to the average of the specified array of points.
         * @throws {ArgumentError} If the specified array of points is null, undefined or empty or the result argument
         * is null or undefined.
         */
        Vec3.averageOfBuffer = function (points, result) {
            if (!points || points.length < 1) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "averageBuffer", "missingArray"));
            }

            if (!result) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "averageBuffer", "missingResult"));
            }

            var count = points.length / 3;

            result[0] = 0;
            result[1] = 0;
            result[2] = 0;

            for (var i = 0; i < count; i++) {
                result[0] += points[i * 3] / count;
                result[1] += points[i * 3 + 1] / count;
                result[2] += points[i * 3 + 2] / count;
            }

            return result;
        };

        /**
         * Indicates whether three vectors are colinear.
         * @param {Vec3} a The first vector.
         * @param {Vec3} b The second vector.
         * @param {Vec3} c The third vector.
         * @returns {Boolean} true if the vectors are colinear, otherwise false.
         * @throws {ArgumentError} If any of the specified vectors are null or undefined.
         */
        Vec3.areColinear = function (a, b, c) {
            if (!a || !b || !c) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "areColinear", "missingVector"));
            }

           var ab = new Vec3(a[0]-b[0],a[1]-b[1],a[2]-b[2]).normalize(),
               bc = new Vec3(c[0]-b[0],c[1]-b[1],c[2]-b[2]).normalize();

            // ab and bc are considered colinear if their dot product is near +/-1.
            return Math.abs(ab.dot(bc)) > 0.999;
        };

        /**
         * Computes the normal vector of a specified triangle.
         *
         * @param {Vec3} a The triangle's first vertex.
         * @param {Vec3} b The triangle's second vertex.
         * @param {Vec3} c The triangle's third vertex.
         * @returns {Vec3} The triangle's unit-normal vector.
         * @throws {ArgumentError} If any of the specified vectors are null or undefined.
         */
        Vec3.computeTriangleNormal = function (a, b, c) {
            if (!a || !b || !c) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "areColinear", "missingVector"));
            }

            var x = ((b[1] - a[1]) * (c[2] - a[2])) - ((b[2] - a[2]) * (c[1] - a[1])),
                y = ((b[2] - a[2]) * (c[0] - a[0])) - ((b[0] - a[0]) * (c[2] - a[2])),
                z = ((b[0] - a[0]) * (c[1] - a[1])) - ((b[1] - a[1]) * (c[0] - a[0])),
                length = (x * x) + (y * y) + (z * z);

            if (length === 0) {
                return new Vec3(x, y, z);
            }

            length = Math.sqrt(length);

            return new Vec3(x / length, y / length, z / length);
        };

        /**
         * Finds three non-colinear points in an array of coordinates.
         *
         * @param {Number[]} coords The coordinates, in the order x0, y0, z0, x1, y1, z1, ...
         * @param {Number} stride The number of numbers between successive points. 0 indicates that the points
         * are arranged one immediately after the other, as would the value 3.
         * @returns {Vec3[]} Three non-colinear points from the input array of coordinates, or null if three
         * non-colinear points could not be found or the specified coordinates array is null, undefined or
         * contains fewer than three points.
         */
        Vec3.findThreeIndependentVertices = function (coords, stride) {
            var xstride = (stride && stride > 0) ? stride : 3;

            if (!coords || coords.length < 3 * xstride) {
                return null;
            }

            var a = new Vec3(coords[0], coords[1], coords[2]),
                b = null,
                c = null,
                k = xstride;

            for (; k < coords.length; k += xstride) {
                b = new Vec3(coords[k], coords[k + 1], coords[k + 2]);
                if (!(b[0] === a[0] && b[1] === a[1] && b[2] === a[2])) {
                    break;
                }
                b = null;
            }

            if (!b) {
                return null;
            }

            for (k += xstride; k < coords.length; k += xstride) {
                c = new Vec3(coords[k], coords[k + 1], coords[k + 2]);

                // if c is not coincident with a or b, and the vectors ab and bc are not colinear, break and
                // return a, b, c.
                if (!((c[0] === a[0] && c[1] === a[1] && c[2] === a[2])
                    || (c[0] === b[0] && c[1] === b[1] && c[2] === b[2]))) {
                    if (!Vec3.areColinear(a, b, c))
                        break;
                }

                c = null;
            }

            return c ? [a, b, c] : null;
        };

        /**
         * Computes a unit-normal vector for a buffer of coordinate triples. The normal vector is computed from the
         * first three non-colinear points in the buffer.
         *
         * @param {Number[]} coords The coordinates, in the order x0, y0, z0, x1, y1, z1, ...
         * @param {Number} stride The number of numbers between successive points. 0 indicates that the points
         * are arranged one immediately after the other, as would the value 3.
         * @returns {Vec3} The computed unit-length normal vector.
         */
        Vec3.computeBufferNormal = function (coords, stride) {
            var vertices = Vec3.findThreeIndependentVertices(coords, stride);

            return vertices ? Vec3.computeTriangleNormal(vertices[0], vertices[1], vertices[2]) : null;
        };

        /**
         * Assigns the components of this vector.
         * @param {Number} x The X component of the vector.
         * @param {Number} y The Y component of the vector.
         * @param {Number} z The Z component of the vector.
         * @returns {Vec3} This vector with the specified components assigned.
         */
        Vec3.prototype.set = function (x, y, z) {
            this[0] = x;
            this[1] = y;
            this[2] = z;

            return this;
        };

        /**
         * Copies the components of a specified vector to this vector.
         * @param {Vec3} vector The vector to copy.
         * @returns {Vec3} This vector set to the X, Y and Z values of the specified vector.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.copy = function (vector) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "copy", "missingVector"));
            }

            this[0] = vector[0];
            this[1] = vector[1];
            this[2] = vector[2];

            return this;
        };

        /**
         * Indicates whether the components of this vector are identical to those of a specified vector.
         * @param {Vec3} vector The vector to test.
         * @returns {Boolean} true if the components of this vector are equal to those of the specified one,
         * otherwise false.
         */
        Vec3.prototype.equals = function (vector) {
            return this[0] === vector[0] && this[1] === vector[1] && this[2] === vector[2];
        };

        /**
         * Adds a specified vector to this vector.
         * @param {Vec3} addend The vector to add.
         * @returns {Vec3} This vector after adding the specified vector to it.
         * @throws {ArgumentError} If the addend is null or undefined.
         */
        Vec3.prototype.add = function (addend) {
            if (!addend) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "add", "missingVector"));
            }

            this[0] += addend[0];
            this[1] += addend[1];
            this[2] += addend[2];

            return this;
        };

        /**
         * Subtracts a specified vector from this vector.
         * @param {Vec3} subtrahend The vector to subtract
         * @returns {Vec3} This vector after subtracting the specified vector from it.
         * @throws {ArgumentError} If the subtrahend is null or undefined.
         */
        Vec3.prototype.subtract = function (subtrahend) {
            if (!subtrahend) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "subtract", "missingVector"));
            }

            this[0] -= subtrahend[0];
            this[1] -= subtrahend[1];
            this[2] -= subtrahend[2];

            return this;
        };

        /**
         * Multiplies this vector by a scalar.
         * @param {Number} scalar The scalar to multiply this vector by.
         * @returns {Vec3} This vector multiplied by the specified scalar.
         */
        Vec3.prototype.multiply = function (scalar) {
            this[0] *= scalar;
            this[1] *= scalar;
            this[2] *= scalar;

            return this;
        };

        /**
         * Divides this vector by a scalar.
         * @param {Number} divisor The scalar to divide this vector by.
         * @returns {Vec3} This vector divided by the specified scalar.
         */
        Vec3.prototype.divide = function (divisor) {
            this[0] /= divisor;
            this[1] /= divisor;
            this[2] /= divisor;

            return this;
        };

        /**
         * Multiplies this vector by a 4x4 matrix. The multiplication is performed with an implicit W component of 1.
         * The resultant W component of the product is then divided through the X, Y, and Z components.
         *
         * @param {Matrix} matrix The matrix to multiply this vector by.
         * @returns {Vec3} This vector multiplied by the specified matrix.
         * @throws ArgumentError If the specified matrix is null or undefined.
         */
        Vec3.prototype.multiplyByMatrix = function (matrix) {
            if (!matrix) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "multiplyByMatrix", "missingMatrix"));
            }

            var x = matrix[0] * this[0] + matrix[1] * this[1] + matrix[2] * this[2] + matrix[3],
                y = matrix[4] * this[0] + matrix[5] * this[1] + matrix[6] * this[2] + matrix[7],
                z = matrix[8] * this[0] + matrix[9] * this[1] + matrix[10] * this[2] + matrix[11],
                w = matrix[12] * this[0] + matrix[13] * this[1] + matrix[14] * this[2] + matrix[15];

            this[0] = x / w;
            this[1] = y / w;
            this[2] = z / w;

            return this;
        };

        /**
         * Mixes (interpolates) a specified vector with this vector, modifying this vector.
         * @param {Vec3} vector The vector to mix with this one.
         * @param {Number} weight The relative weight of this vector.
         * @returns {Vec3} This vector modified to the mix of itself and the specified vector.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.mix = function (vector, weight) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "mix", "missingVector"));
            }

            var w0 = 1 - weight,
                w1 = weight;

            this[0] = this[0] * w0 + vector[0] * w1;
            this[1] = this[1] * w0 + vector[1] * w1;
            this[2] = this[2] * w0 + vector[2] * w1;

            return this;
        };

        /**
         * Negates the components of this vector.
         * @returns {Vec3} This vector, negated.
         */
        Vec3.prototype.negate = function () {
            this[0] = -this[0];
            this[1] = -this[1];
            this[2] = -this[2];

            return this;
        };

        /**
         * Computes the scalar dot product of this vector and a specified vector.
         * @param {Vec3} vector The vector to multiply.
         * @returns {Number} The dot product of the two vectors.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.dot = function (vector) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "dot", "missingVector"));
            }

            return this[0] * vector[0] +
                this[1] * vector[1] +
                this[2] * vector[2];
        };

        /**
         * Computes the cross product of this vector and a specified vector, modifying this vector.
         * @param {Vec3} vector The vector to cross with this vector.
         * @returns {Vec3} This vector set to the cross product of itself and the specified vector.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.cross = function (vector) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "cross", "missingVector"));
            }

            var x = this[1] * vector[2] - this[2] * vector[1],
                y = this[2] * vector[0] - this[0] * vector[2],
                z = this[0] * vector[1] - this[1] * vector[0];

            this[0] = x;
            this[1] = y;
            this[2] = z;

            return this;
        };

        /**
         * Computes the squared magnitude of this vector.
         * @returns {Number} The squared magnitude of this vector.
         */
        Vec3.prototype.magnitudeSquared = function () {
            return this.dot(this);
        };

        /**
         * Computes the magnitude of this vector.
         * @returns {Number} The magnitude of this vector.
         */
        Vec3.prototype.magnitude = function () {
            return Math.sqrt(this.magnitudeSquared());
        };

        /**
         * Normalizes this vector to a unit vector.
         * @returns {Vec3} This vector, normalized.
         */
        Vec3.prototype.normalize = function () {
            var magnitude = this.magnitude(),
                magnitudeInverse = 1 / magnitude;

            this[0] *= magnitudeInverse;
            this[1] *= magnitudeInverse;
            this[2] *= magnitudeInverse;

            return this;
        };

        /**
         * Computes the squared distance from this vector to a specified vector.
         * @param {Vec3} vector The vector to compute the distance to.
         * @returns {Number} The squared distance between the vectors.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.distanceToSquared = function (vector) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "distanceToSquared", "missingVector"));
            }

            var dx = this[0] - vector[0],
                dy = this[1] - vector[1],
                dz = this[2] - vector[2];

            return dx * dx + dy * dy + dz * dz;
        };

        /**
         * Computes the distance from this vector to another vector.
         * @param {Vec3} vector The vector to compute the distance to.
         * @returns {number} The distance between the vectors.
         * @throws {ArgumentError} If the specified vector is null or undefined.
         */
        Vec3.prototype.distanceTo = function (vector) {
            if (!vector) {
                throw new ArgumentError(
                    Logger.logMessage(Logger.LEVEL_SEVERE, "Vec3", "distanceTo", "missingVector"));
            }

            return Math.sqrt(this.distanceToSquared(vector));
        };

        /**
         * Swaps this vector with that vector. This vector's components are set to the values of the specified
         * vector's components, and the specified vector's components are set to the values of this vector's components.
         * @param {Vec3} that The vector to swap.
         * @returns {Vec3} This vector set to the values of the specified vector.
         */
        Vec3.prototype.swap = function (that) {
            var tmp = this[0];
            this[0] = that[0];
            that[0] = tmp;

            tmp = this[1];
            this[1] = that[1];
            that[1] = tmp;

            tmp = this[2];
            this[2] = that[2];
            that[2] = tmp;

            return this;
        };

        /**
         * Returns a string representation of this vector.
         * @returns {String} A string representation of this vector, in the form "(x, y, z)".
         */
        Vec3.prototype.toString = function () {
            return "(" + this[0] + ", " + this[1] + ", " + this[2] + ")";
        };

        return Vec3;
    }
);