vertex.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::Vertex class. A class for manipulating 3D vertices.

  \par Copyright Information

  Copyright (c) 2015 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef _VERTEX_H
#define _VERTEX_H

#include "disti_include.h"
#include "display_types.h"
#include "gls_color.h"
#include "unhide_globals.h"

#include <iosfwd> //Forward references for the stream operators
#include <math.h>

#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif

// DEG_TO_RAD Converts degrees to radians
#ifndef DEG_TO_RAD
#define DEG_TO_RAD (M_PI/180.0)
#endif

namespace disti
{

class Vertex;
class VertexNoColor;

/** This typedef is a changed from pre 3.0 versions.
  * Now Vector is different from Vertex.  It now contains no color
  * information 
  */
typedef VertexNoColor Vector;

/** Rotation axis enumeration.  Passed into rotation calls */
typedef enum
{
   X_AXIS,  /**< Rotate around the X Axis */
   Y_AXIS,  /**< Rotate around the Y Axis */
   Z_AXIS   /**< Rotate around the Z Axis */
} RotationAxis;

/**
  The Vertex class: Implements a 3D cartesian coordianate and operations
  for manipulating them.
*/
class VertexNoColor
{
   public:

    float x,y,z;

    /** Simple constructor.  Ensures all values are initialized */
    inline VertexNoColor() :
       x(0.0f),
       y(0.0f),
       z(0.0f)
    {}

   /** Position only constructor.  Color values are set to defaults
       \param _x   The X value of the vertex, in logical units
       \param _y   The Y value of the vertex, in logical units
       \param _z   The Z value of the vertex, in logical units */
    inline VertexNoColor(float _x,float _y,float _z) :
       x(_x),
       y(_y),
       z(_z)
    {}

   /** Compute the square of the cartesian distance between this point and
       another one , in 3D
       \param v  The vertex to compute distance squared to
       \return   The square of the distance between the two points */
   inline float Distance3Squared(const VertexNoColor &v) const
       { return ((v.x-x)*(v.x-x)) + ((v.y-y)*(v.y-y)) + ((v.z-z)*(v.z-z)); }

   /** Returns the squared distance of this point from the line defined by start 
       and direction, in 3D
       \param startx starting x coordinate of the line.
       \param starty starting y coordinate of the line.
       \param startz starting z coordinate of the line.
       \param direction Normalized direction vector for the line.
       \return  the distance from this point. */
   inline float DistanceFromLineSquared(const float startx, const float starty, const float startz, const VertexNoColor &direction) const
       {
           // Distance from point to line
           // Algorithm from Mgc::SqrDistance http://www.magic-software.com/License/free.pdf

           VertexNoColor kDiff(x, y, z);

           //kDiff = rkPoint - linePoint;           
           kDiff.x -= startx;
           kDiff.y -= starty;
           kDiff.z -= startz;

           float fSqrLen = direction.MagnitudeSquared();
           float fT = kDiff.DotProduct(direction)/fSqrLen;

           //kDiff.minusAssign(direction.multiply(fT));
           kDiff.x -= direction.x * fT;
           kDiff.y -= direction.y * fT;
           kDiff.z -= direction.z * fT;           

           float dist_squared = kDiff.MagnitudeSquared();

           return dist_squared;
       }

   /** Compute cartesian distance between this point and another one , in 3D
       \param v  The vertex to compute distance to.
       \return   The distance between the two points */
   inline float Distance3(const VertexNoColor &v) const
       { return float(sqrt( ((v.x-x)*(v.x-x)) + ((v.y-y)*(v.y-y)) + ((v.z-z)*(v.z-z)))); }

   /** Compute the square of the cartesian distance between this point and
       another one , in 2D
       \param v  The vertex to compute distance squared to
       \return   The square of the distance between the two points */
   inline float Distance2Squared(const VertexNoColor &v) const
       { return ((v.x-x)*(v.x-x))+ ((v.y-y)*(v.y-y)); }

   /** Compute cartesian distance between this point and another one , in 2D
       \param v  The vertex to compute distance to
       \return   The distance between the two points */
   inline float Distance2(const VertexNoColor &v) const
       {  return float(sqrt(((v.x-x)*(v.x-x))+ ((v.y-y)*(v.y-y)))); }

   /** Compute the result of adding this point to another one, in 3D
       \param arg  The vertex to add to this one
       \return     A new vertex V2 where V2 = this + v */
   inline VertexNoColor operator + (const VertexNoColor &arg) const
     { return VertexNoColor(x + arg.x,y + arg.y,z + arg.z);  }

   /** Negation operator */
   inline VertexNoColor operator - () const
     { return VertexNoColor(-x,-y,-z);}

   /** Compute the result of multiplying this point by a scalar
       \param s  The Scalar to multiply by
       \return   A new vertex V2 where V2 = this * s */
   inline VertexNoColor operator * (const float s) const
       { return VertexNoColor(x*s,y*s,z*s);  }
         
   /** Compute the result of multiplying this point by a scalar
       \param s  The Scalar to multiply by
       \return   V = V * s */
   inline VertexNoColor& operator *= (const float s)
       { x *= s; y *= s; z *= s;
         return *this; }

     /** Compute the result of dividing this point by a scalar
       \param s  The Scalar to divide by
       \return   A new vertex V2 where V2 = this / s */
   inline VertexNoColor operator / (const float s) const
       { return VertexNoColor(x/s,y/s,z/s);  }
         
   /** Compute the result of dividing this point by a scalar
       \param s  The Scalar to divide by
       \return   V = V / s */
   inline VertexNoColor& operator /= (const float s)
       { x /= s; y /= s; z /= s;
         return *this; }

   /** Compute the result of adding this point to another one, in 3D
       \param arg  The vertex to add to this one
       \return     V = V + arg */
   inline VertexNoColor& operator += (const VertexNoColor &arg)
       { x += arg.x; y += arg.y; z += arg.z;
         return *this; }

   /** Compute the result of subtracting this point from another one, in 3D
       \param arg  The vertex to subtract from this one
       \return     A new vertex V2 where V2 = this - v */
   inline VertexNoColor operator - (const VertexNoColor &arg) const
   { return VertexNoColor(x - arg.x,y - arg.y,z - arg.z);  }
         
   /** Compute the result of subtracting this point from another one, in 3D
       \param arg  The vertex to subtract from this one
       \return     V = V - arg */
   inline VertexNoColor& operator -= (const VertexNoColor &arg)
       { x -= arg.x; y -= arg.y; z -= arg.z;
         return *this; }

    /** Determines if the vertex is identical to the supplied vertex, ignoring color
      \param arg vertex to compare to
      \return TRUE if equal, else FALSE
      */
    inline bool operator == (const VertexNoColor &arg) const
        { return ((x == arg.x) && (y == arg.y) && (z == arg.z)); }

    /** Determines if the vertex is identical to the supplied vertex, ignoring color
      \param arg vertex to compare to
      \return TRUE if equal, else FALSE
      */
    inline bool operator != (const VertexNoColor &arg) const
        { return ((x != arg.x) || (y != arg.y) || (z != arg.z)); }

    /** Computes the result of muliplying this point to another one.
     \param arg vertex to multiple with
     \return resulting vertex
     */
    inline VertexNoColor operator * (const VertexNoColor &arg) const
    { 
        return VertexNoColor(x * arg.x,y * arg.y,z * arg.z);
    }

   /** Rotate this point in 2D clockwise around the z axis.
       \param angle  The angle to rotate around, in degrees.
       \return       The rotated vertex */
   DISTI_EXPORT VertexNoColor Rotate(const float angle) const;

   /** Rotate this point around a different point in 2D counter-clockwise around the z axis.
       \param orig    The rotation origin to rotate around.
       \param angle   The angle to rotate around, in degrees.
       \return       The rotated vertex */
   DISTI_EXPORT VertexNoColor Rotate(const VertexNoColor &orig,const float angle) const;

    /** Rotate this point around a different point in 2D clockwise around the z axis.
       \param orig    The rotation origin to rotate around.
       \param angle   The angle to rotate around, in degrees.
       \param axis    The axis to rotate around. See RotationAxis enum.
       \return       The rotated vertex */
   DISTI_EXPORT VertexNoColor Rotate(const VertexNoColor &orig,const float angle,const int axis) const;

   /** Rotate this vertex by angle theta counter-clockwise around an arbitrary axis r.
       \param orig    The rotation origin to rotate around.
       \param angle   The angle to rotate around, in degrees.
       \param r       The axis to rotate around.
       \return       The rotated vertex
       */
   DISTI_EXPORT VertexNoColor Rotate(const VertexNoColor &orig, const float angle, const Vector &r) const;
   
   /** Normalizes the vector into a unit vector */
   inline void Normalize(void)
   {
        float length, inv_length;
      
        length = Magnitude();
        if (length != 0.0f)
        {
            // Divide is slow so calculate 1/length and multiply to save time
            inv_length = 1.0f / length;

            x = x * inv_length;
            y = y * inv_length;
            z = z * inv_length;
        }
    }

   /** Returns the magnitude of the vector
    * \return  The resulting scalar
    */
   inline float Magnitude() const
   { return float( sqrt( ((x)*(x)) + ((y)*(y)) + ((z)*(z))) ); }

   /** Returns the magnitude of the vector squared
    * \return  The resulting scalar
    */
   inline float MagnitudeSquared() const
   { return x*x + y*y + z*z; }

   /** Returns the vector cross-product of this vector with the argument vector
    *  HS Algebra review:  vector cross-product is the vector that is
    *  perpendicular to the two given vectors.
    * \param w Second vector
    * \return  The resulting cross-product (vector)
    */
   inline VertexNoColor CrossProduct(const VertexNoColor &w) const
       { return VertexNoColor((y * w.z) - (z * w.y),
                  (z * w.x) - (x * w.z),
                  (x * w.y) - (y * w.x));
       }

   /** Returns the vector dot-product of this vector with the argument vector
    * \param w Second vector
    * \return  The resulting dot-product (scalar)
    */
   inline float DotProduct(const VertexNoColor &w) const
       { return ((x * w.x) + (y * w.y) + (z * w.z)); }

   /** Returns the angle (in radians) between this vector and the argument vect.
    * \param arg  Second vector
    * \return  The resulting angle (in radians)
    */
   DISTI_EXPORT float AngleToVector(const VertexNoColor &arg) const;

   /** Returns true if this vertex is in the given triangle specified by abc 
     * \param a First triangle vertex
     * \param b Second triangle vertex
     * \param c Third triangle vertex
     * \return true if this point is inside the triangle, false otherwise
     */
   inline bool PointInTriangle(const VertexNoColor &a,const VertexNoColor &b,const VertexNoColor &c) const
   {
        float fAB,fBC,fCA;

        fAB = (y-a.y)*(b.x-a.x) - (x-a.x)*(b.y-a.y);
        fBC = (y-b.y)*(c.x-b.x) - (x-b.x)*(c.y-b.y);
        fCA = (y-c.y)*(a.x-c.x) - (x-c.x)*(a.y-c.y);

        return (((fAB*fBC) > 0)  && ((fBC*fCA) > 0));
   }

   /** Returns true if this vertex is within the radius specified by tolerance 
     * \param arg        vertex to compare with
     * \param tolerance  the tolerance value
     * \return           true if this point within the tolerance
     */
   DISTI_EXPORT bool CloseTo(const VertexNoColor &arg, float tolerance = 0.0001f) const;

   /** Returns the distance of this point from the line defined by start and direction
     * \param start  Starting point of the line
     * \param direction  Normalized direction vector for the line
     */
   DISTI_EXPORT float DistanceFromLine(const VertexNoColor &start, const VertexNoColor &direction) const;

   /** Returns the projection of this point onto the line defined by origin and direction
     * \param origin     Starting point of the line
     * \param direction  Normalized direction vector for the line
     */
   DISTI_EXPORT VertexNoColor ProjectPointToLine(const VertexNoColor &origin, const VertexNoColor &direction) const;
};
// Stream operators
GLS_EXPORT std::istream& operator>>(std::istream& instr, Vector& vert) ;
GLS_EXPORT std::ostream& operator<<(std::ostream& outstr, const Vector& vert); 

/** A 3D coordinate in space with an RGBA color value */
class Vertex : public VertexNoColor
{
public:

    glsColor color;

    /** Simple constructor.  Ensures all values are initialized */
    Vertex() : VertexNoColor()
    { 
        color.RGBA(DEF_FILL_RCOLOR,DEF_FILL_GCOLOR,DEF_FILL_BCOLOR,DEF_FILL_ALPHA);
    }

    /** Just add the default color  constructor */
    Vertex(const VertexNoColor& noColor) : VertexNoColor(noColor)
    {
        color.RGBA(DEF_FILL_RCOLOR,DEF_FILL_GCOLOR,DEF_FILL_BCOLOR,DEF_FILL_ALPHA);
    }

    /** Just add the color  constructor */
    Vertex(const VertexNoColor& noColor, const glsColor& _color) : VertexNoColor(noColor),
        color(_color)
    {
    }

   /** Position only constructor.  Color values are set to defaults
       \param _x   The X value of the vertex, in logical units
       \param _y   The Y value of the vertex, in logical units
       \param _z   The Z value of the vertex, in logical units */
    Vertex(float _x,float _y,float _z) : VertexNoColor( _x, _y, _z)
    {
        color.RGBA(DEF_FILL_RCOLOR,DEF_FILL_GCOLOR,DEF_FILL_BCOLOR,DEF_FILL_ALPHA);
    }

   /** Position only constructor.  Color values are set to defaults
       \param _x   The X value of the vertex, in logical units
       \param _y   The Y value of the vertex, in logical units
       \param _z   The Z value of the vertex, in logical units 
       \param _r   The R value of the color of the vertex 0-255
       \param _g   The G value of the color of the vertex 0-255
       \param _b   The B value of the color of the vertex 0-255
       \param _a   The A value of the color of the vertex 0-255
   */
   Vertex(float _x,float _y,float _z, 
          unsigned char _r, unsigned char _g, unsigned char _b, unsigned char _a) :
     VertexNoColor(_x, _y, _z)
   {
            color.RGBA(_r,_g,_b,_a);
   }

   /** Position only constructor.  Color values are set to defaults
       \param _x       The X value of the vertex, in logical units
       \param _y       The Y value of the vertex, in logical units
       \param _z       The Z value of the vertex, in logical units 
       \param _color   The value of the color of the vertex
   */
     Vertex(float _x,float _y,float _z, const glsColor& _color) :
       VertexNoColor( _x, _y, _z )
     {
           color = _color;
     }

   /** Compute the result of adding this point to another one, in 3D
       \param arg  The vertex to add to this one
       \return     A new vertex V2 where V2 = this + v */
   inline Vertex operator + (const VertexNoColor &arg) const
     { return Vertex(x + arg.x,y + arg.y,z + arg.z, color);  }

   /** Compute the result of multiplying this point by a scalar
       \param s  The Scalar to multiply by
       \return   A new vertex V2 where V2 = this * s */
   inline Vertex operator * (const float s) const
       { return Vertex(x*s,y*s,z*s, color);  }

      /** Rotate this point in 2D around the z axis
       \param angle  The angle to rotate around, in degrees.
       \return       The rotated vertex */
   DISTI_EXPORT Vertex Rotate(const float angle) const;

   /** Rotate this point around a different point in 2D around the z axis
       \param orig    The rotation origin to rotate around.
       \param angle   The angle to rotate around, in degrees.
       \return       The rotated vertex */
   DISTI_EXPORT Vertex Rotate(const VertexNoColor &orig,const float angle) const;

    /** Rotate this point around a different point in 2D around the z axis
       \param orig    The rotation origin to rotate around.
       \param angle   The angle to rotate around, in degrees.
       \param axis    The axis to rotate 180 degrees around. x = 1, y = 2, z = 3.
       \return        The rotated vertex */
   DISTI_EXPORT Vertex Rotate(const VertexNoColor &orig,const float angle,const int axis) const;

   /** Rotate this vertex by angle theta around an arbitrary axis r
       Return the rotated point.
       Positive angles are anticlockwise looking down the axis
       towards the origin. */
   DISTI_EXPORT Vertex Rotate(const VertexNoColor &orig, const float theta, const Vector &r) const;

   /** Compute the result of subtracting this point from another one, in 3D
    \param arg  The vertex to subtract from this one
    \return     A new vertex V2 where V2 = this - v */
   inline Vertex operator - (const VertexNoColor &arg) const
   { return Vertex(x - arg.x,y - arg.y,z - arg.z, color);  }

   /** Negation operator */
   inline Vertex operator - () const
     { return Vertex(-x,-y,-z,color);  }

     /** Computes the result of muliplying this point to another one.
     \param arg vertex to multiple with
     \return resulting vertex
     */
    inline Vertex operator * (const VertexNoColor &arg) const
    { 
        return Vertex(x * arg.x,y * arg.y,z * arg.z, color);
    }

   /** Returns the vector cross-product of this vector with the argument vector
    *  HS Algebra review:  vector cross-product is the vector that is
    *  perpendicular to the two given vectors.
    * \param w Second vector
    * \return  The resulting cross-product (vector)
    */
   inline Vertex CrossProduct(const VertexNoColor &w) const
   { return Vertex(VertexNoColor::CrossProduct(w), color); }
};

/**
  The PlaneClass class: Implements a 3D plane
*/
class PlaneClass
{
   public:

   float a,b,c,d;  /** Coefficients to describe a 3D plane:  aX + bY + cZ + d = 0 */

   PlaneClass(void) { a = 0.0f; b = 0.0f; c = 0.0f; d = 0.0f; }

   PlaneClass(float A,float B,float C,float D) { a = A; b = B; c = C; d = D; }
};

// Stream operators
DISTI_EXPORT std::istream& operator>>(std::istream& instr, Vertex& vert) ;
DISTI_EXPORT std::ostream& operator<<(std::ostream& outstr, const Vertex& vert); 

/** Computes whether or not a vector intersects a plane.
  * \param point       Returned parameter, contains intersection point on success
  * \param lineVector  Direction of the vector
  * \param linePoint   Origin point of the vector
  * \param planeNormal Surface normal of the plane
  * \param planePoint  A point on the plane
  * \return Non-zero if the vector intersects the plane
  */
DISTI_EXPORT int IntersectionVectorAndPlane(VertexNoColor &point, const Vector &lineVector, const VertexNoColor &linePoint, const Vector &planeNormal, const Vector &planePoint);


/** Finds the point that (1) lies along the plane passing through p3
  * and perpendicular to the vector p1-p2 and (2) lies along the line defined by
  * p1 and p2
  *
  * Method: We have 3 unknowns (x,y,z) and 3 equations:
  *          The first known equation is the equation of the plane where
  *          vA is the vector p2 - p1
  *          eq 1:  (x - p3.x)vA.x + (y - p3.y)vA.y + (z - p3.z)vA.z = 0
  *          The second and third equations are the projection form of the
  *          line defined by the points p1 and p2.
  *          eq 2:  (x - p1.x) / (p2.x - p1.x) = (y - p1.y) / (p2.y - p1.y)
  *          eq 3:  (x - p1.x) / (p2.x - p1.x) = (z - p1.z) / (p2.z - p1.z)
  *
  * \param p1 First point in the vector
  * \param p2 Second point in the vector
  * \param p3 A point in the plane p1,p2,p3
  * \return The point of intersection
  */
DISTI_EXPORT VertexNoColor ProjectedIntersectingPoint(const VertexNoColor& p1,const VertexNoColor& p2,const VertexNoColor& p3);

/** Determines if a line intersects a triangle, and optionally where.
  * \param origin          The origin of the line to test
  * \param direction       The direction vector of the line
  * \param v0              The first triangle point
  * \param v1              The second triangle point
  * \param v2              The third triangle point
  * \param collisionPoint  Returns where the triangle was hit (only set if the triangle was actually hit)
  * \return                True if the triangle is hit
  * \note This function does what TriangleHit() and DoesLineIntersectTriangle() used to do, namely checking the intersection of a line with a triangle. 
  *       Most users should use RayHitsTriangle() instead because using a line may return a collision in the opposite direction to the direction vector,
  *       which could result in a pick behind the viewer, for instance.
  */
DISTI_EXPORT bool LineHitsTriangle(const Vector &origin,const Vector &direction,const Vector &v0,const Vector &v1,const Vector &v2,Vector *collisionPoint = 0);

/** Determines if a ray intersects a triangle, and optionally where.
  * \param origin          The origin of the ray to test
  * \param direction       The direction vector of the ray
  * \param v0              The first triangle point
  * \param v1              The second triangle point
  * \param v2              The third triangle point
  * \param collisionPoint  Returns where the triangle was hit (only set if the triangle was actually hit)
  * \return                True if the triangle is hit
  * \note                  See note on LineHitsTriangle().
  */
DISTI_EXPORT bool RayHitsTriangle(const Vector &origin,const Vector &direction,const Vector &v0,const Vector &v1,const Vector &v2,Vector *collisionPoint = 0);

/** Find the point at which a line intersects a plane.  Helper/preparer function for 
  * IntersectionVectorAndPlane.
  * /param point            Origin of the line
  * /param vert1            First point defining the plane
  * /param vert2            Second point defining the plane
  * /param vert3            Third point defining the plane
  * /param collisionPoint   This will be set to the intersection point
  * /param directionVector  Vector to which the line is parallel
  */
DISTI_EXPORT void FindCollision(const Vector &origin,const Vector &vert1, const Vector &vert2,const Vector &vert3, VertexNoColor *collisionPoint, const Vector &directionVector);

/** Computes the Normal vector for the plane formed from the three given points.
  * \param p1 First point
  * \param p2 Second point
  * \param p3 Third point
  * \return The "normal" vector to the plane formed by p2,p2,p3 
  */
DISTI_EXPORT VertexNoColor Normal(const VertexNoColor& p1, const VertexNoColor& p2, const VertexNoColor& p3);

} // namespace disti

#endif