<!-- GENERATED by tools/generators/itemDocsEmitter.py from definitions/ - do not edit -->
```{raw} latex
\clearpage
```

(sec-item-markerbodiesrelativerotationcoordinate)=
# MarkerBodiesRelativeRotationCoordinate

A coordinate-based Marker attached to two rigid bodies or beams which computes the relative rotation between the bodies according to the given axis; this marker can be used together with coordinate-based constraints and connectors (e.g., CoordinateSpringDamper and CoordinateConstraint). NOTE: it is assumed that the two bodies can only rotate about the given axis (e.g., constrained by a revolute joint) -- otherwise results may be unexpected. NOTE: this approach is not compatible with FFRF-based flexible bodies and currently requires and intermediate rigid body.

## Interface

- Provides: `Coordinate`
- Connectors, constraints and loads that can use it: [](#sec-item-objectconnectorcoordinatespringdamper), [](#sec-item-objectconnectorcoordinatespringdamperext), [](#sec-item-objectconnectorcoordinate), [](#sec-item-objectcontactcoordinate), [](#sec-item-loadcoordinate)

## Parameters

The parameters of the item; in a dictionary, its type is 'BodiesRelativeRotationCoordinate':

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | marker's unique name |
| **bodyNumbers** | ArrayObjectIndex |  | [ invalid (-1), invalid (-1) ] | (symbol: $[b_0,b_1]\tp$) list of body numbers for which relative coordinate is computed |
| **nodeNumber** | NodeIndex |  | invalid (-1) | node number of NodeGenericData with 1 coordinate which contains previous angle for continuation of angles (initialize accordingly if needed); if node is not supplied, angles will have jump outside $\pm \pi$ |
| **localPosition0** | Vector3D | 3 | [0.,0.,0.] | (symbol: $\LU{m_0}{\pv}_0$) local position on body 0; i.e. local (body-fixed) position where position is measured and force is applied to |
| **localPosition1** | Vector3D | 3 | [0.,0.,0.] | (symbol: $\LU{m_1}{\pv}_1$) local position on body 1; i.e. local (body-fixed) position where position is measured and force is applied to |
| **axis0** | Vector3D | 3 | [1.,0.,0.] | (symbol: $\LU{m_0}{\av}_0$) axis defined in body 0, along which the relative rotation is measured |
| **offset** | Real |  | 0. | (symbol: $x_\mathrm{off}$) rotation offset [SI:1] subtracted from the measured rotation; can be used to change the zero rotation |
| **visualization** | VMarkerBodiesRelativeRotationCoordinate |  |  | parameters for visualization of item |

## Visualization parameters

The parameters of `VMarkerBodiesRelativeRotationCoordinate`, given as `visualization`:

| name | type | size | default | description |
|---|---|---|---|---|
| **show** | Bool |  | True | set true, if item is shown in visualization and false if it is not shown |

## Drawing

Drawn as [all markers](#sec-drawing-markers).
(description-markerbodiesrelativerotationcoordinate)=
## Detailed description

The marker consists of two bodies, body $b_0$ and body $b_1$ with respective global marker positions $\LU{0}{\pv}_{m0}$ and $\LU{0}{\pv}_{m1}$,
depending on local positions $\LU{m_0}{\pv}_0$ and $\LU{m_1}{\pv}_1$,
and marker orientations $\LU{0,m_0}{\Rot}_{m0}$ and $\LU{0,m_1}{\Rot}_{m1}$.
From the given axis `axis0`, we compute an orthonormal basis (orthonormal to axis0) relative to marker $m_0$,

$$
\LU{m_0,b}{\Rot}_b = \left[\LU{m_0}{\xv}_b, \LU{m_0}{\yv}_b, \LU{m_0}{\av}_0\right]
$$

The relative rotation marker computes the relative rotation according to

$$
\LU{m_0,m_1}{\Rot}_{rel} = \LU{m_0,0}{\Rot}_{m0} \LU{0,m_1}{\Rot}_{m1}
$$

This relative rotation, which represents a rotation about axis $\LU{m_0}{\av}_0$ is then transformed into the orthonormal basis,

$$
\LU{b}{\Rot}_{rel} = \LU{b,m_0}{\Rot}_b \LU{m_0,m_1}{\Rot}_{rel} \LU{m_0,b}{\Rot}_b
$$

and contains the desired rotation about the z-axis, which can be extracted as

$$
\varphi = \mathrm{atan2}(\LU{b}{\Rot}_{rel}[1,0],\LU{b}{\Rot}_{rel}[0,0]) - x_\mathrm{off}
$$

The global axis is computed as

$$
\LU{0}{\av}_0 = \LU{0,m_0}{\Rot}_{m0} \LU{m_0}{\av}_0
$$

Using the angular velocities at the two bodies, $\LU{m_0}{\tomega_0}$ and  $\LU{m_1}{\tomega_1}$, the relative angular velocity, which may be used in coordinate spring-dampers or for velocity-level constraints,
is simply computed as

$$
\dot \varphi = \LU{0}{\av}_0\tp \left( \LU{0,m_1}{\Rot}_{m1} \LU{m_1}{\tomega_1} -
\LU{0,m_0}{\Rot}_{m0} \LU{m_0}{\tomega_0} \right)
$$

Jacobians are computed according to the relative rotation velocity.
Using this approach, coordinate constraints can be added to mechanisms to purely add internal drives, not affecting global momenta.
Furthermore, coupling to a relative translation can be used to create advanced mechanisms and gears.

It is a coordinate marker: coordinate connectors, coordinate constraints and `LoadCoordinate` use it.
Both bodies must provide position and orientation at a local point, as a rigid body does; `Assemble()`
refuses other bodies.

(miniexample-markerbodiesrelativerotationcoordinate)=
## Mini example


```python
#the rotation of body 1 relative to body 0 about an axis of body 0, held by a coordinate constraint;
#the data node continues the angle beyond +-pi
inertia = InertiaCuboid(density=1000, sideLengths=[0.4,0.2,0.1])
node = mbs.AddNode(NodeRigidBodyRxyz(referenceCoordinates=[0,0,0, 0,0,0]))
body = mbs.AddObject(ObjectRigidBody(nodeNumber=node, mass=inertia.Mass(),
                                     inertia=inertia.GetInertia6D()))
nData = mbs.AddNode(NodeGenericData(numberOfDataCoordinates=1, initialCoordinates=[0]))
mRel = mbs.AddMarker(MarkerBodiesRelativeRotationCoordinate(bodyNumbers=[oGround, body], axis0=[0,0,1],
                                                           nodeNumber=nData))
mGround = mbs.AddMarker(MarkerNodeCoordinate(nodeNumber=nGround, coordinate=0))
oHold = mbs.AddObject(ObjectConnectorCoordinate(markerNumbers=[mGround, mRel]))
mbs.AddLoad(LoadTorqueVector(markerNumber=mbs.AddMarker(MarkerNodeRigid(nodeNumber=node)), loadVector=[0,0,2]))

mbs.Assemble()
mbs.SolveDynamic()

#the constraint holds the relative rotation about z against the torque: its force is the reaction torque
exu.sys['testResult'] = mbs.GetObjectOutput(oHold, exu.OutputVariableType.Force) #2
```


Relevant Examples (Ex) and TestModels (TM) with weblink to github: [`involuteGearGraphics.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/involuteGearGraphics.py) (Ex), [`relativeRotationTranslationMechanism.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/relativeRotationTranslationMechanism.py) (TM)