# Ignition Physics

## API Reference

5.1.0
RelativeQuantity< Q, Dim, CoordinateSpace > Class Template Reference

The RelativeQuantity class is a wrapper for classes that represent mathematical quantities (e.g. points, vectors, matrices, transforms). The purpose of this wrapper is to endow raw mathematical quantities with frame semantics, so that they can express the frame of reference of their values. More...

#include <RelativeQuantity.hh>

## Public Types

enum  { Dimension = Dim }
The number of physical (spatial) dimensions that this quantity exists in. Only values of 2 or 3 are supported. More...

using Quantity = Q
The underlying type of the quantity that is being expressed. More...

using Space = CoordinateSpace
The mathematical space which defines how this quantity is transformed between reference frames. More...

## Public Member Functions

template<typename... Args>
RelativeQuantity (const FrameID &_parentID, Args &&... _args)
This constructor will specify the parent frame and then forward the remaining arguments to the constructor of the underlying quantity. More...

RelativeQuantity (const Q &_rawValue)
Implicit conversion constructor. More...

void MoveToNewParentFrame (const FrameID &_newParentFrame)
This function will change the parent frame of your RelativeQuantity. More...

const FrameIDParentFrame () const
Get the ID of this RelativeQuantity's parent frame. More...

Q & RelativeToParent ()
Get the value of this RelativeQuantity relative to its parent frame. To get the value of this RelativeQuantity with respect to the world frame, use the FrameSemantics::Resolve(~) function of your physics engine like so: More...

const Q & RelativeToParent () const
const-qualified version of RelativeToParent. More...

## Detailed Description

### template<typename Q, std::size_t Dim, typename CoordinateSpace> class ignition::physics::RelativeQuantity< Q, Dim, CoordinateSpace >

The RelativeQuantity class is a wrapper for classes that represent mathematical quantities (e.g. points, vectors, matrices, transforms). The purpose of this wrapper is to endow raw mathematical quantities with frame semantics, so that they can express the frame of reference of their values.

Note that the raw value of the quantity being held can only be retrieved through the member function RelativeToParent(). We choose to contain the quantity like this instead of inheriting it to avoid a situation where a user might add two relative quantities like

u = v + w

where v and w belong to different frames. That would be an ill-formed expression, since values that are being expressed in different reference frames are not directly compatible. Use the Resolve(~) or Reframe(~) function in the FrameSemantics interface of your physics engine plugin to transform a RelativeQuantity into a different reference frame.

## ◆ Quantity

 using Quantity = Q

The underlying type of the quantity that is being expressed.

## ◆ Space

 using Space = CoordinateSpace

The mathematical space which defines how this quantity is transformed between reference frames.

## ◆ anonymous enum

 anonymous enum

The number of physical (spatial) dimensions that this quantity exists in. Only values of 2 or 3 are supported.

Enumerator
Dimension

## ◆ RelativeQuantity() [1/2]

 RelativeQuantity ( const FrameID & _parentID, Args &&... _args )
explicit

This constructor will specify the parent frame and then forward the remaining arguments to the constructor of the underlying quantity.

## ◆ RelativeQuantity() [2/2]

 RelativeQuantity ( const Q & _rawValue )

Implicit conversion constructor.

## ◆ MoveToNewParentFrame()

 void MoveToNewParentFrame ( const FrameID & _newParentFrame )

This function will change the parent frame of your RelativeQuantity.

## ◆ ParentFrame()

 const FrameID& ParentFrame ( ) const

Get the ID of this RelativeQuantity's parent frame.

To change the parent frame of this RelativeQuantity, use the Reframe(~) function of your physics engine's FrameSemantics interface like this:

fq = engine->GetInterface<FrameSemantics>()->Reframe(fq, A);

where A is the FrameID of the new frame. The Reframe function will keep the values of your RelativeQuantity consistent (with respect to the World Frame) as it reassigns the parent frame.

Alternatively, to change the parent frame of this RelativeQuantity while making its values relative to the new frame equal to what its values were relative to the old frame, you can use the MoveToNewParentFrame(~) function below.

Referenced by ignition::physics::operator<<().

## ◆ RelativeToParent() [1/2]

 Q& RelativeToParent ( )

Get the value of this RelativeQuantity relative to its parent frame. To get the value of this RelativeQuantity with respect to the world frame, use the FrameSemantics::Resolve(~) function of your physics engine like so:

Q quantity = engine->GetInterface<FrameSemantics>()->Resolve(fq)

where Q is your quantity type, and fq is your RelativeQuantity instance.

To get the value of this RelativeQuantity with respect to an arbitrary reference frame, again use the Resolve function:

Q quantity = engine->GetInterface<FrameSemantics>()->Resolve(fq, F);

where F is the FrameID of the desired reference frame.

Referenced by ignition::physics::operator<<().

## ◆ RelativeToParent() [2/2]

 const Q& RelativeToParent ( ) const

const-qualified version of RelativeToParent.

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