Class vector3

Objects of class vector3 represent a point in a 3-dimensional space.

Files

Header File

The interface and implementation are both supplied by the header file vector3.hpp.

Test Program

The file vector3_test.cpp tests the vector3 operations for float, double, and long double.

Usage

Synopsis

namespace	boost { namespace math {

    template
    class vector3
    {
    public:
        explicit vector3();
        explicit vector3( const _Tp& x, const _Tp& y, const _Tp& z );

        static const    vector3<_Tp>    unit_x;
        static const    vector3<_Tp>    unit_y;
        static const    vector3<_Tp>    unit_z;

        enum    ECoordinates
        {
            ceLinear,
            ceSpherical,
            ceCylindrical
        };

        explicit vector3( const _Tp& c1, const _Tp& c2, const _Tp& c3,
                          ECoordinates eType );
        
        template
        vector3( const vector3<_Up>& rhs );

        _Tp& x();
        _Tp& y();
        _Tp& z();
        const _Tp& x() const;
        const _Tp& y() const;
        const _Tp& z() const;
        _Tp& operator[]( size_t i );
        const _Tp& operator[]( size_t i ) const;


        _Tp cylindrical_rho( ) const;
        _Tp cylindrical_phi( ) const;
        _Tp cylindrical_z( ) const;

        _Tp spherical_r( ) const;
        _Tp spherical_theta( ) const;
        _Tp spherical_phi( ) const;
        
        template
        vector3<_Tp>& operator=( const vector3<_Up>& rhs );

        template
        vector3<_Tp>& operator+=( const vector3<_Up>& rhs );
        template
        vector3<_Tp>& operator-=( const vector3<_Up>& rhs );
        template
        vector3<_Tp>& operator*=( const _Up& rhs );
        template
        vector3<_Tp>& operator/=( const _Up& rhs );

        _Tp norm() const;
        _Tp norm2() const;
        vector3<_Tp>& unit_vector( );

        vector3<_Tp>&   rotate_x( const _Tp& theta );
        vector3<_Tp>&   rotate_y( const _Tp& theta );
        vector3<_Tp>&   rotate_z( const _Tp& theta );
        vector3<_Tp>&   rotate( const vector3<_Tp>& dir, const _Tp& theta );

        vector3<_Tp>&   reflect( const vector3<_Tp>& surface );

        template
        vector3<_Tp>&
        refract_dir( const vector3<_Tp>& surface_in, const _Up& nRel );

        template
        vector3<_Tp>&
        refract_velocity( const vector3<_Tp>& surface_in, const _Up& nRel );
        
    };
    
    template
    inline bool
    operator==( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    inline bool
    operator!=( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    inline vector3<_Tp>
    operator +( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    inline vector3<_Tp>
    operator -( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    inline vector3<_Tp>
    operator -( const vector3<_Tp>& lhs );

    template
    inline vector3<_Tp>
    operator *( const vector3<_Tp>& lhs, const _Up& rhs );

    template
    inline vector3<_Tp>
    operator *( const _Up& lhs, const vector3<_Tp>& rhs );

    template
    inline vector3<_Tp>
    operator /( const vector3<_Tp>& lhs, const _Up& rhs );

    // Vector products. 
    template
    _Tp
    dot( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    _Tp
    cos_angle( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
    
    template
    inline vector3<_Tp>
    cross( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

    template
    inline _Tp
    norm( const vector3<_Tp>& lhs );
    
    template
    inline _Tp
    norm2( const vector3<_Tp>& lhs );
    
    template
    vector3<_Tp>
    unit_vector( const vector3<_Tp>& lhs );

    template
    inline vector3<_Tp>
    rotate_x( const vector3<_Tp>& ray, const _Tp& theta );

    template
    inline vector3<_Tp>
    rotate_y( const vector3<_Tp>& ray, const _Tp& theta );

    template
    inline vector3<_Tp>
    rotate_z( const vector3<_Tp>& ray, const _Tp& theta );

    template
    inline vector3<_Tp>
    rotate( const vector3<_Tp>& ray, const vector3<_Tp>& dir, const _Tp& theta );

    template
    inline vector3<_Tp>
    reflect( const vector3<_Tp>& ray, const vector3<_Tp>& surface );

    template
    inline vector3<_Tp>
    refract_dir( const vector3<_Tp>& ray,
                 const vector3<_Tp>& surface,
                 const _Up& nRel );

    template
    inline vector3<_Tp>
    refract_velocity( const vector3<_Tp>& ray,
                      const vector3<_Tp>& surface,
                      const _Up& nRel );

    template
    vector3<_Tp>&
    vector3<_Tp>::rotate( const vector3<_Tp>& dir, const _Tp& theta );

    template
    std::basic_ostream&
    operator << (std::basic_ostream& os, const vector3<_Tp>& rhs);

    template
    std::basic_istream&
    operator >> (std::basic_istream& is, vector3<_Tp>& rhs);

} };

Constructors and Assignment

Member functions

explicit vector3();
explicit vector3( const _Tp& x, const _Tp& y, const _Tp& z );
The default constructor constructs a null vector (With all coordinates zero. The constructor with three base type arguments constructs the vector with those x, y, z coordinates.
template
vector3( const vector3<_Up>& rhs );

template
vector3<_Tp>& operator=( const vector3<_Up>& rhs );
There is a templetized copy constructor and assignment operator from other vector3 types.
enum	ECoordinates
{
	ceLinear,
	ceSpherical,
	ceCylindrical
};
explicit vector3( const _Tp& c1, const _Tp& c2, const _Tp& c3,
				  ECoordinates eType )
This constructor allows a vector3 object to be created from non carteasean coordinates. For ceSpherical the c1, c2, and c3 are r, phi, and theta. For ceCylindrical c1, c2, and c3 are rho, phi, and z. For ceLinear the c1, c2, c3 are x, y, z.

TBD: Is this the best form for constructors in other coordinate systems (polar and spherical)? Note that the std complex uses a stand alone template function of polar() that constructs the polar version. I could have a cylindrical() and sperical() that can do this. But, this seems likely to cause conflicts with other libraries since only the return value identifies this as a vector3 method.

static const	vector3<_Tp>	unit_x;
static const	vector3<_Tp>	unit_y;
static const	vector3<_Tp>	unit_z;
The class provides three constants for the unit vectors along the principal axes.

Free functions

template
inline bool
operator==( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

template
inline bool
operator!=( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
These are the normal equality operators. a vector is considered equal if all the (x, y, z) components are equal.

Accessing the Components

Free functions

_Tp& x();
_Tp& y();
_Tp& z();

const _Tp& x() const;
const _Tp& y() const;
const _Tp& z() const;
The class provides access to the x, y, and z coordinates by named functions.
_Tp& operator[]( size_t i );
const _Tp& operator[]( size_t i );
The class also provides array indexes (0-2) for the x, y, z coordinates.
_Tp cylindrical_rho( ) const;
_Tp cylindrical_phi( ) const;
_Tp cylindrical_z( ) const;
These members define accessors for the components in a cylindrical representation.
_Tp spherical_r( ) const;
_Tp spherical_theta( ) const;
_Tp spherical_phi( ) const;
These members define accessors for the components on a spherical representation.

TBD: Do the cylindrical_ and spherical_ prefixes help or hurt readability. For the shared cases of phi, and z, the quantities are the same in both representations.

Vector Sums

Member functions

template
vector3<_Tp>& operator+=( const vector3<_Up>& rhs );

template
vector3<_Tp>& operator-=( const vector3<_Up>& rhs )
These perform the usual in place addition and subtraction of the vectors.

Free functions

template
inline vector3<_Tp>
operator +( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );

template
inline vector3<_Tp>
operator -( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
The usual vector addition and subtraction.
template
inline vector3<_Tp>
operator -( const vector3<_Tp>& lhs );
This returns the negative (reflection about the origin) of the vector.

Products

Member functions

template
vector3<_Tp>& operator*=( const _Up& rhs );
template
vector3<_Tp>& operator/=( const _Up& rhs );
These perform the usual (member wise) multiplication and division by a scaler.

Free functions

template
inline vector3<_Tp>
operator *( const vector3<_Tp>& lhs, const _Up& rhs );

template
inline vector3<_Tp>
operator *( const _Up& lhs, const vector3<_Tp>& rhs );

template
inline vector3<_Tp>
operator /( const vector3<_Tp>& lhs, const _Up& rhs );
These perform the right and left multiplication, and right division by a scaler.
template
_Tp
dot( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
This returns the dot product of two vectors.
template
_Tp
cos_angle( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
This returns the cosine of the angle between the two vectors.
template
inline vector3<_Tp>
cross( const vector3<_Tp>& lhs, const vector3<_Tp>& rhs );
This returns the cross product of two vectors.

Vector Properties

Member functions

_Tp norm() const;
_Tp norm2() const;
These return the norm (length) of the vector, and the square of the norm respectively.
vector3<_Tp>& unit_vector( );
Scales the vector to be a unit vector (norm equal to 1) in the same direction as the original vector. It returns a reference to itself. The input vector must not have zero length.

Free functions

template
inline _Tp
norm( const vector3<_Tp>& lhs );

template
inline _Tp
norm2( const vector3<_Tp>& lhs );

template
vector3<_Tp>
unit_vector( const vector3<_Tp>& lhs );
The same member functions also exist as free functions, but with a vector3 argument.

Rotations

Member functions

vector3<_Tp>&   rotate_x( const _Tp& theta );
vector3<_Tp>&   rotate_y( const _Tp& theta );
vector3<_Tp>&   rotate_z( const _Tp& theta );
These rotate (assuming a right handled coordinate system) the vector around a principle axis by the angle given. They then return a reference to themselves.
vector3<_Tp>&   rotate( const vector3<_Tp>& dir, const _Tp& theta );
This rotates the vector (assuming a right handled coordinate system) around a generic direction the requested angle. It then return a reference to itself.

Free functions

template
inline vector3<_Tp>
rotate_x( const vector3<_Tp>& ray, const _Tp& theta );

template
inline vector3<_Tp>
rotate_y( const vector3<_Tp>& ray, const _Tp& theta );

template
inline vector3<_Tp>
rotate_z( const vector3<_Tp>& ray, const _Tp& theta );

template
inline vector3<_Tp>
rotate( const vector3<_Tp>& ray, const vector3<_Tp>& dir, const _Tp& theta );
These are the same rotations as free functions. They do the same things as the member functions, but have a passed in vector that is adjusted without change.

Reflection and Refraction

Member functions

vector3<_Tp>&   reflect( const vector3<_Tp>& surface );

This changes the vector to be the reflection of this vector against a
surface that is perpendicular to the passed in vector.  (The component
perpendicular to the surface is inverted, and the parallel component is
unchanged.) Note that the (norm) length of the vector is unchanged. It
then returns a reference to itself.

template
void
refract_dir( const vector3<_Tp>& surface_in, const _Up& nRel );

template
void
refract_velocity( const vector3<_Tp>& surface_in, const _Up& nRel );
This changes the vector to be the refraction (following Snell's law) of this vector against a surface that is perpendicular to the passed in vector. The nRel argument is the ratio of the refractive index of the incident side divided by the refractive index of the transmitted side.

The dir version does not change the norm (length) of the vector. This is appropriate if you are tracing just directions (unit vectors). The velocity version changes norm (length) of the vector by a factor of nRel. This is appropriate for tracing velocity vectors.

Free functions

template
inline vector3<_Tp>
reflect( const vector3<_Tp>& ray, const vector3<_Tp>& surface );

template
inline vector3<_Tp>
refract_dir( const vector3<_Tp>& ray,
             const vector3<_Tp>& surface,
             const _Up& nRel );

template
inline vector3<_Tp>
refract_velocity( const vector3<_Tp>& ray,
                  const vector3<_Tp>& surface,
                  const _Up& nRel );
These are the same reflection and refraction, but as free functions. They do the same things as the member functions, but have a passed in vector that is adjusted without change.

Stream Operations

template
std::basic_ostream&
operator << (std::basic_ostream& os, const vector3<_Tp>& rhs);

template
std::basic_istream&
operator >> (std::basic_istream& is, vector3<_Tp>& rhs);
These perform the usual stream input and output operations. The format of the vector is "(x,y,z)". Where x, y, and z are the format for the components.

Administrative

Outstanding Issues

History


Revised 19 Apr 2005

© Copyright Stefan Koch 2005. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.