The SKIRT project
advanced radiative transfer for astrophysics
Public Member Functions | Private Member Functions | List of all members
Direction Class Reference

#include <Direction.hpp>

Inheritance diagram for Direction:
Inheritance graph
[legend]

Public Member Functions

 Direction ()
 
 Direction (double kx, double ky, double kz, bool normalize)
 
 Direction (double theta, double phi)
 
 Direction (Vec k, bool normalize)
 
void cartesian (double &kx, double &ky, double &kz) const
 
double kx () const
 
double ky () const
 
double kz () const
 
Vecoperator*= (Vec v)=delete
 
Vecoperator+= (Vec v)=delete
 
Direction operator- () const
 
Vecoperator-= (Vec v)=delete
 
Vecoperator/= (Vec v)=delete
 
void set (double kx, double ky, double kz, bool normalize)
 
void set (double, double, double)=delete
 
void set (Vec k, bool normalize)
 
void spherical (double &theta, double &phi) const
 
- Public Member Functions inherited from Vec
 Vec ()
 
 Vec (double x, double y, double z)
 
void clear ()
 
bool isNull () const
 
double norm () const
 
double norm2 () const
 
Vecoperator*= (double s)
 
Vecoperator+= (Vec v)
 
Vecoperator-= (Vec v)
 
Vecoperator/= (double s)
 
void set (double x, double y, double z)
 
double x () const
 
double y () const
 
double z () const
 

Private Member Functions

void normalize ()
 

Additional Inherited Members

- Static Public Member Functions inherited from Vec
static Vec cross (Vec a, Vec b)
 
static double dot (Vec a, Vec b)
 
- Protected Attributes inherited from Vec
double _x
 
double _y
 
double _z
 

Detailed Description

An object of the Direction class represents a direction in three-dimensional space. In principle only two coordinates are necessary to fully characterize a direction; a possible choice is spherical coordinates on the unit sphere. However in this class, a direction is internally represented by means of its three cartesian coordinates \((k_x,k_y,k_z)\). These coordinates must satisfy the normalization relation

\[ k_x^2+k_y^2+k_z^2=1. \]

To assist client code using the Direction class with ensuring this normalization, the constructors and the set() functions offer the Boolean normalize argument. If set to true, the constructor or function will automatically normalize the components passed by the caller. If set to false, the components are copied as given without any further verification. This can be used to avoid redundant calculations in case the caller has already ensured normalization.

An important exception to the normalization invariant occurs when all three direction components are zero, resulting in an invalid "null" direction. This can happen, for example, when constructing a direction from user input or from the cross product of two parallel vectors. In situations where a null direction may occur, client code should test for this using the Vec::isNull() function.

The Direction class is publicly based on the Vec class, and the direction coordinates \((k_x,k_y,k_z)\) are stored in the Vec components x, y and z. Consequently the functions and operators defined for Vec are automatically available for Direction, except for functions that would break the normalization (e.g. the compound-assignment operators).

Constructor & Destructor Documentation

◆ Direction() [1/4]

Direction::Direction ( )
inline

The default constructor for the class Direction creates a direction parallel to the \(z\)-axis of the reference frame. The cartesian coordinates of this direction are \((k_x,k_y,k_z)=(0,0,1)\).

◆ Direction() [2/4]

Direction::Direction ( double  kx,
double  ky,
double  kz,
bool  normalize 
)
inline

Constructor for a direction with given cartesian coordinates \(k_x\), \(k_y\) and \(k_z\). If normalize is true, the constructor scales these coordinates so that they conform to the normalization relation \(k_x^2+k_y^2+k_z^2=1\); if this is not possible because the coordinates are zero, the direction is set to the invalid null vector. If normalize is false, the components are copied as given without any further verification. This can be used to avoid redundant calculations in case the caller has already ensured normalization.

◆ Direction() [3/4]

Direction::Direction ( Vec  k,
bool  normalize 
)
inline

Constructor for a direction with given cartesian coordinates \({\bf{k}}_x\), \({\bf{k}}_y\) and \({\bf{k}}_z\). If normalize is true, the constructor scales these coordinates so that they conform to the normalization relation \(k_x^2+k_y^2+k_z^2=1\); if this is not possible because the coordinates are zero, the direction is set to the invalid null vector. If normalize is false, the components are copied as given without any further verification. This can be used to avoid redundant calculations in case the caller has already ensured normalization.

◆ Direction() [4/4]

Direction::Direction ( double  theta,
double  phi 
)

Constructor for a direction with a given azimuth and polar angle. The cartesian coordinates are calculated as

\[ \begin{split} k_x &= \sin\theta\,\cos\varphi, \\ k_y &= \sin\theta\,\sin\varphi, \\ k_z &= \cos\theta. \end{split} \]

It is explicitly checked whether \(\theta\) lies within the interval \([0,\pi]\). If not so, this does not correspond to a viable direction, and a FatalError is thrown.

Member Function Documentation

◆ cartesian()

void Direction::cartesian ( double &  kx,
double &  ky,
double &  kz 
) const

This function returns the three cartesian coordinates \((k_x,k_y,k_z)\) of the direction. Note that these cartesian coordinates are also directly accessible through the functions kx(), ky() and kz(), and the equivalents x(), y() and z() inherited from the Vec class.

◆ kx()

double Direction::kx ( ) const
inline

This function returns the direction coordinate \(k_x\). It is equivalent to the function x() inherited from the Vec class.

◆ ky()

double Direction::ky ( ) const
inline

This function returns the direction coordinate \(k_y\). It is equivalent to the function y() inherited from the Vec class.

◆ kz()

double Direction::kz ( ) const
inline

This function returns the direction coordinate \(k_z\). It is equivalent to the function z() inherited from the Vec class.

◆ normalize()

void Direction::normalize ( )
private

This private function normalizes the coordinates already stored in this instance by dividing them by the value of the Vec::norm() function. As an exception, if the norm() function returns zero, all coordinates are set to zero, resulting in an invalid direction. The function is called from constructors and setters for this class in case the client code sets normalize to true.

◆ operator*=()

Vec & Direction::operator*= ( Vec  v)
inlinedelete

Disable this compound assignment operator inherited from Vec because it breaks the normalization.

◆ operator+=()

Vec & Direction::operator+= ( Vec  v)
inlinedelete

Disable this compound assignment operator inherited from Vec because it breaks the normalization.

◆ operator-()

Direction Direction::operator- ( ) const
inline

This operator returns the opposite direction (negating each coordinate).

◆ operator-=()

Vec & Direction::operator-= ( Vec  v)
inlinedelete

Disable this compound assignment operator inherited from Vec because it breaks the normalization.

◆ operator/=()

Vec & Direction::operator/= ( Vec  v)
inlinedelete

Disable this compound assignment operator inherited from Vec because it breaks the normalization.

◆ set() [1/3]

void Direction::set ( double  kx,
double  ky,
double  kz,
bool  normalize 
)
inline

This function sets the direction to the given cartesian coordinates \({\bf{k}}_x\), \({\bf{k}}_y\) and \({\bf{k}}_z\). If normalize is true, the constructor scales these coordinates so that they conform to the normalization relation \(k_x^2+k_y^2+k_z^2=1\); if this is not possible because the coordinates are zero, the direction is set to the invalid null vector. If normalize is false, the components are copied as given without any further verification. This can be used to avoid redundant calculations in case the caller has already ensured normalization.

◆ set() [2/3]

void Direction::set ( double  ,
double  ,
double   
)
inlinedelete

Disable the setter inherited from Vec so that callers are forced to specify a normalization option.

◆ set() [3/3]

void Direction::set ( Vec  k,
bool  normalize 
)
inline

This function sets the direction to the given cartesian coordinates \({\bf{k}}_x\), \({\bf{k}}_y\) and \({\bf{k}}_z\). If normalize is true, the constructor scales these coordinates so that they conform to the normalization relation \(k_x^2+k_y^2+k_z^2=1\); if this is not possible because the coordinates are zero, the direction is set to the invalid null vector. If normalize is false, the components are copied as given without any further verification. This can be used to avoid redundant calculations in case the caller has already ensured normalization.

◆ spherical()

void Direction::spherical ( double &  theta,
double &  phi 
) const

This function determines the two spherical coordinates \((\theta,\varphi)\) of the direction. They are calculated from the internally stored cartesian coordinates by means of the formulae

\[ \begin{split} \theta &= \arccos\left(k_z\right), \\ \varphi &= \arctan\left(\frac{k_y}{k_x}\right). \end{split} \]


The documentation for this class was generated from the following file: