Implementation of the a general cyclic value (such as angles in radians/degrees etc). More...

#include <cyclic.h>

Public Member Functions
	cyclic ()
	Default constructor. More...

	cyclic (const flt val)
	Constructor overload. More...

	cyclic (const cyclic &other)
	Copy constructor. More...

	cyclic (const spec &other)
	Copy constructor. More...

flt	value () const
	Getter for `val`. More...

template<class other_t >
other_t	convert () const
	Conversion between two different circular quantities. More...

cyclic &	operator= (const flt nval)
	Assignment operator. More...

cyclic &	operator= (const cyclic &other)
	Assignment operator. More...

cyclic &	operator= (cyclic &&other)
	Move operator. More...

cyclic &	operator+= (const cyclic &other)
	Addition compound operator. More...

cyclic &	operator-= (const cyclic &other)
	Subtraction compound operator. More...

Static Public Member Functions
static bool	inRange (const flt val)
	Checks if `val` is within the valid interval of wrapped values. More...

static flt	wrap (const flt val)
	Returns `val`, converted to the valid interval of values. More...

static flt	unwrap (const flt what, const flt from)
	Returns value of the parameter `what` modified so that there is no "jump" between `from` and \t what. More...

static flt	pdist (const flt from, const flt to)
	Returns length of the shortest walk in the positive direction from the first parameter to the second one. More...

static flt	pdist (const cyclic from, const cyclic to)

static flt	diff (const flt minuend, const flt subtrahend)
	Returns the difference between the two circular values. More...

static flt	diff (const cyclic minuend, const cyclic subtrahend)

static flt	dist (const flt from, const flt to)
	Returns the distance between the two circular values. More...

static flt	dist (const cyclic from, const cyclic to)

static flt	interpUnwrapped (const flt from, const flt to, const flt coeff)
	Interpolation between two circular quantities without wrapping of the result. More...

static flt	interpUnwrapped (const cyclic from, const cyclic to, const flt coeff)

static flt	interp (const flt from, const flt to, const flt coeff)
	Interpolation between two circular quantities. More...

static flt	interp (const cyclic from, const cyclic to, const flt coeff)

static flt	pinterpUnwrapped (const flt from, const flt to, const flt coeff)
	Interpolation between two circular quantities in the positive direction without wrapping of the result. More...

static flt	pinterpUnwrapped (const cyclic from, const cyclic to, const flt coeff)

static flt	pinterp (const flt from, const flt to, const flt coeff)
	Interpolation between two circular quantities in the positive direction. More...

static flt	pinterp (const cyclic from, const cyclic to, const flt coeff)

template<class other_t >
static other_t	convert (const cyclic &what)
	Conversion between two different circular quantities. More...

Static Public Attributes
static constexpr flt	minimum = spec::minimum
	Minimum of the valid interval of wrapped values .

static constexpr flt	supremum = spec::supremum
	Supremum of the valid interval of wrapped values .

static constexpr flt	range
	Range of the valid interval of wrapped values (also the period of the cyclic quantity). More...

static constexpr flt	half_range
	Half of the range of the valid interval of wrapped values (used for some calculations). More...

Protected Attributes
flt	val

Friends
spec	operator+ (const cyclic &lhs, const cyclic &rhs)
	Addition operator. More...

flt	operator- (const cyclic &lhs, const cyclic &rhs)
	Subtraction operator (uses the diff() method). More...

Detailed Description

template<typename flt, class spec>
struct mrs_lib::geometry::cyclic< flt, spec >

Implementation of the a general cyclic value (such as angles in radians/degrees etc).

This class implements a periodical value with a period of $r \in {\rm I\!R}$ so that a general number $v \in {\rm I\!R}$ represents the same value as $v + kr,~k \in {\rm I\!N}$ . For the purposes of calculations in this class, $ v $ is confined to a half-open interval $v \in [~m,~s~[$ , where $ m $ is the minimum of this interval and $ s $ is its supremum, and $ s = m + r $ holds. This approach enables representing $ v $ in different intervals on the real numbers axis; eg. angle in radians may be represented within the interval $v \in [~-\pi,~\pi~[$ or $v \in [~0,~2\pi~[$ , according to the needs of the specific application. The period $ r $ is called range for the purposes of this class, as it represents range of the interval of valid ("wrapped") values of $ v $ .

This class may be used as an object or its static methods may be used on regular floating-point types, avoiding any object-related overheads (see example). Specializations for the most common cyclic values are provided and a new specialization may be easily created simply by inheriting from this class and specifying a different minimum and supremum values.

Implementation inspired by: https://www.codeproject.com/Articles/190833/Circular-Values-Math-and-Statistics-with-Cplusplus

Note: For a better intuitive understanding of the used functions, the term walk is sometimes used in the function explanations. You can imagine walking along the circle from one angle to another (represented by the circular quantities). The walk may be the shortest - then you're walking in such a manner that you reach the other point in the least of steps. The walk may also be oriented - then you're walking in a specific direction (ie. according to the increasing/decreasing angle).

Note: The terms circular quantity and value are used in the function explanations. A circular quantity is eg. an angle and the same quantity may be represented using different values: the same angle is represented by the values of 100 degrees and 460 degrees.

Template Parameters

flt	floating data type to be used by this class.

Examples: geometry/cyclic_example.cpp.

Constructor & Destructor Documentation

◆ cyclic() [1/4]

template<typename flt , class spec >

mrs_lib::geometry::cyclic< flt, spec >::cyclic ( )

inline

Default constructor.

Sets the value to the minimum.

◆ cyclic() [2/4]

template<typename flt , class spec >

mrs_lib::geometry::cyclic< flt, spec >::cyclic ( const flt val )

inline

Constructor overload.

Parameters

val	initialization value (will be wrapped).

◆ cyclic() [3/4]

template<typename flt , class spec >

mrs_lib::geometry::cyclic< flt, spec >::cyclic ( const cyclic< flt, spec > & other )

inline

Copy constructor.

Parameters

val	initialization value.

◆ cyclic() [4/4]

template<typename flt , class spec >

mrs_lib::geometry::cyclic< flt, spec >::cyclic ( const spec & other )

inline

Copy constructor.

Parameters

val	initialization value.

Member Function Documentation

◆ convert() [1/2]

template<typename flt , class spec >

template<class other_t >

other_t mrs_lib::geometry::cyclic< flt, spec >::convert ( ) const

inline

Conversion between two different circular quantities.

This method returns the circular quantity, represented by this object, converted to the other_t type of circular quantity.

Returns: the circular quantity converted to the range of other_t.

Template Parameters

other_t type of the circular quantity to be converted to.

Warning: For the purposes of this function, it is assumed that the range of one type corresponds to the whole range of the other type and zeros of both types correspond to each other (such as when converting eg. degrees to radians).

◆ convert() [2/2]

template<typename flt , class spec >

template<class other_t >

static other_t mrs_lib::geometry::cyclic< flt, spec >::convert ( const cyclic< flt, spec > & what )

inlinestatic

Conversion between two different circular quantities.

This function converts its parameter, interpreted as the circular quantity, represented by this class, to the other_t type of circular quantity.

Parameters

what	the circular quantity to be converted.

Returns: the circular quantity converted to the range of other_t.

Template Parameters

other_t type of the circular quantity to be converted to.

Warning: For the purposes of this function, it is assumed that the range of one type corresponds to the whole range of the other type and zeros of both types correspond to each other (such as when converting eg. degrees to radians).

◆ diff()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::diff	(	const flt	minuend,
		const flt	subtrahend
	)

inlinestatic

Returns the difference between the two circular values.

The difference may also be interpreted as length of the shortest walk between the two values, with a sign according to the direction of the shortest walk.

Parameters

minuend	the `subtrahend` will be subtracted from this value.
subtrahend	this value will be subtracted from the `minuend`.

Returns: the difference of the two circular quantities.

◆ dist()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::dist	(	const flt	from,
		const flt	to
	)

inlinestatic

Returns the distance between the two circular values.

The distance may also be interpreted as length of the shortest walk between the two values.

Parameters

from	the first circular quantity.
to	the second circular quantity.

Returns: distance of the two circular quantities.

Note: The order of the parameters doesn't matter.

◆ inRange()

template<typename flt , class spec >

static bool mrs_lib::geometry::cyclic< flt, spec >::inRange ( const flt val )

inlinestatic

Checks if val is within the valid interval of wrapped values.

Parameters

val	the value to be checked.

Returns: true if val is within the valid interval of wrapped values.

◆ interp()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::interp	(	const flt	from,
		const flt	to,
		const flt	coeff
	)

inlinestatic

Interpolation between two circular quantities.

This function wraps the returned value so that it is in the interval of valid values.

Parameters

from	the first circular quantity.
to	the second circular quantity.
coeff	the interpolation coefficient.

Returns: interpolation of the two circular quantities using the coefficient, wrapped to the interval of valid values.

◆ interpUnwrapped()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::interpUnwrapped	(	const flt	from,
		const flt	to,
		const flt	coeff
	)

inlinestatic

Interpolation between two circular quantities without wrapping of the result.

This function doesn't wrap the returned value.

Parameters

from	the first circular quantity.
to	the second circular quantity.
coeff	the interpolation coefficient.

Returns: interpolation of the two circular quantities using the coefficient.

Warning: Note that the returned value may be outside the valid interval of wrapped values, specified by the minimum and supremum parameters of this class.

◆ operator+=()

template<typename flt , class spec >

cyclic& mrs_lib::geometry::cyclic< flt, spec >::operator+= ( const cyclic< flt, spec > & other )

inline

Addition compound operator.

Parameters

other value to be added.

Returns: reference to self.

◆ operator-=()

template<typename flt , class spec >

cyclic& mrs_lib::geometry::cyclic< flt, spec >::operator-= ( const cyclic< flt, spec > & other )

inline

Subtraction compound operator.

Parameters

other value to be subtracted.

Returns: reference to self.

◆ operator=() [1/3]

template<typename flt , class spec >

cyclic& mrs_lib::geometry::cyclic< flt, spec >::operator= ( const cyclic< flt, spec > & other )

inline

Assignment operator.

Parameters

other value to be assigned.

Returns: reference to self.

◆ operator=() [2/3]

template<typename flt , class spec >

cyclic& mrs_lib::geometry::cyclic< flt, spec >::operator= ( const flt nval )

inline

Assignment operator.

Parameters

nval	value to be assigned (will be wrapped).

Returns: reference to self.

◆ operator=() [3/3]

template<typename flt , class spec >

cyclic& mrs_lib::geometry::cyclic< flt, spec >::operator= ( cyclic< flt, spec > && other )

inline

Move operator.

Parameters

other value to be assigned.

Returns: reference to self.

◆ pdist()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::pdist	(	const flt	from,
		const flt	to
	)

inlinestatic

Returns length of the shortest walk in the positive direction from the first parameter to the second one.

Parameters

from	the positive walk starts at this value.
to	the positive walk ends at this value.

Returns: length of the shortest positive walk from the first parameter to the second one.

Note: The returned value is not necessarily the shortest distance between the two circular quantities (see the dist() function for that).

◆ pinterp()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::pinterp	(	const flt	from,
		const flt	to,
		const flt	coeff
	)

inlinestatic

Interpolation between two circular quantities in the positive direction.

Interpolates the two values in the positive direction from the first parameter to the second by the coefficient. This function wraps the returned value so that it is in the interval of valid values.

Parameters

from	the first circular quantity.
to	the second circular quantity.
coeff	the interpolation coefficient.

Returns: interpolation of the two circular quantities using the coefficient, wrapped to the interval of valid values.

◆ pinterpUnwrapped()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::pinterpUnwrapped	(	const flt	from,
		const flt	to,
		const flt	coeff
	)

inlinestatic

Interpolation between two circular quantities in the positive direction without wrapping of the result.

Interpolates the two values in the positive direction from the first parameter to the second by the coefficient. This function doesn't wrap the returned value.

Parameters

from	the first circular quantity.
to	the second circular quantity.
coeff	the interpolation coefficient.

Returns: interpolation of the two circular quantities using the coefficient.

Warning: Note that the returned value may be outside the valid interval of wrapped values, specified by the minimum and supremum parameters of this class.

◆ unwrap()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::unwrap	(	const flt	what,
		const flt	from
	)

inlinestatic

Returns value of the parameter what modified so that there is no "jump" between from and \t what.

The circular difference between the two input quantities is preserved, but the returned value is modified if necessary so that the linear distance between the values is the smallest. This is useful whenever you need to preserve linear continuity of consecutive values, eg. when commanding a multi-rotational servo motor or when using a simple linear Kalman filter to estimate circular quantities.

An example of inputs and outputs if $ m = 0,~s=360 $ :

`what`	`from`	`return`
20	10	20
20	350	380
0	350	360
200	10	-160

Parameters

what	the value to be unwrapped.
from	the previous value from which the unwrapped value of `what` should have the same circular difference and minimal linear distance.

Returns: the unwrapped value of what.

Warning: Note that the returned value may be outside the valid interval of wrapped values, specified by the minimum and supremum parameters of this class.

◆ value()

template<typename flt , class spec >

flt mrs_lib::geometry::cyclic< flt, spec >::value ( ) const

inline

Getter for val.

Returns: the value.

◆ wrap()

template<typename flt , class spec >

static flt mrs_lib::geometry::cyclic< flt, spec >::wrap ( const flt val )

inlinestatic

Returns val, converted to the valid interval of values.

The wrapped value represents the same quantity as the parameter (ie. $ v' = v + kr $ , where $ v $ is the parameter and $ v' $ is the returned value).

Parameters

val	the value to be wrapped.

Returns: val wrapped to the valid interval of values.

Friends And Related Function Documentation

◆ operator+

template<typename flt , class spec >

spec operator+	(	const cyclic< flt, spec > &	lhs,
		const cyclic< flt, spec > &	rhs
	)

friend

Addition operator.

Parameters

lhs	left-hand-side.
rhs	right-hand-side.

Returns: the result of adding the two angles.

◆ operator-

template<typename flt , class spec >

flt operator-	(	const cyclic< flt, spec > &	lhs,
		const cyclic< flt, spec > &	rhs
	)

friend

Subtraction operator (uses the diff() method).

Parameters

lhs	left-hand-side.
rhs	right-hand-side.

Returns: the result of subtracting rhs from lhs.

Member Data Documentation

◆ half_range

template<typename flt , class spec >

constexpr flt mrs_lib::geometry::cyclic< flt, spec >::half_range

staticconstexpr

Initial value:

=

range / flt(2)

Half of the range of the valid interval of wrapped values $ r/2 $ (used for some calculations).

◆ range

template<typename flt , class spec >

constexpr flt mrs_lib::geometry::cyclic< flt, spec >::range

staticconstexpr

Initial value:

=

supremum - minimum

Range of the valid interval of wrapped values $ r $ (also the period of the cyclic quantity).

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

include/mrs_lib/geometry/cyclic.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Friends

Detailed Description

template<typename flt, class spec> struct mrs_lib::geometry::cyclic< flt, spec >

Constructor & Destructor Documentation

◆ cyclic() [1/4]

◆ cyclic() [2/4]

◆ cyclic() [3/4]

◆ cyclic() [4/4]

Member Function Documentation

◆ convert() [1/2]

◆ convert() [2/2]

◆ diff()

◆ dist()

◆ inRange()

◆ interp()

◆ interpUnwrapped()

◆ operator+=()

◆ operator-=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ pdist()

◆ pinterp()

◆ pinterpUnwrapped()

◆ unwrap()

◆ value()

◆ wrap()

Friends And Related Function Documentation

◆ operator+

◆ operator-

Member Data Documentation

◆ half_range

◆ range

template<typename flt, class spec>
struct mrs_lib::geometry::cyclic< flt, spec >