Direction Class Reference

#include <Direction.hpp>

Inheritance diagram for Direction:

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
Vec &	operator*= (Vec v)=delete
Vec &	operator+= (Vec v)=delete
Direction	operator- () const
Vec &	operator-= (Vec v)=delete
Vec &	operator/= (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
Vec &	operator*= (double s)
Vec &	operator+= (Vec v)
Vec &	operator-= (Vec v)
Vec &	operator/= (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 ${\mathbf{k}}_x$, ${\mathbf{k}}_y$ and ${\mathbf{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{array}{rl}{k}_x& =\sin \theta \cos \phi ,\\ k_y& =\sin \theta \sin \phi ,\\ k_z& =\cos \theta .\end{array}$$

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 ${\mathbf{k}}_x$, ${\mathbf{k}}_y$ and ${\mathbf{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 ${\mathbf{k}}_x$, ${\mathbf{k}}_y$ and ${\mathbf{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 ,\phi )$ of the direction. They are calculated from the internally stored cartesian coordinates by means of the formulae

$$\begin{array}{rl}\theta & =\arccos \left(k_z\right),\\ \phi & =\arctan \left(\frac{k_y}{k_x}\right).\end{array}$$

---

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

• Direction.hpp