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

(sec-item-markerbodiesrelativetranslationcoordinate)=
# MarkerBodiesRelativeTranslationCoordinate

A coordinate-based Marker attached to two rigid bodies or beams which computes the relative translation 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 move along the given axis (e.g., constrained by a prismatic 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 'BodiesRelativeTranslationCoordinate':

| 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 |
| **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 translation is measured |
| **offset** | Real |  | 0. | (symbol: $x_\mathrm{off}$) translation offset [SI:m] subtracted from the translation; can be used to change the zero position |
| **visualization** | VMarkerBodiesRelativeTranslationCoordinate |  |  | parameters for visualization of item |

## Visualization parameters

The parameters of `VMarkerBodiesRelativeTranslationCoordinate`, 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-markerbodiesrelativetranslationcoordinate)=
## 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}$.
The global axis is computed as

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

The relative translation marker computes the relative translation from the equation

$$
t =  \LU{0}{\av}_0\tp (\pv_{m1} - \pv_{m0}) - x_\mathrm{off}
$$

The translational velocity, which may be used in coordinate spring-dampers or for velocity-level constraints, is computed as

$$
\dot t = \LU{0}{\av}_0\tp (\dot \pv_{m1} - \dot \pv_{m0}) + \LU{0}{\dot \av}_0\tp (\pv_{m1} - \pv_{m0})
$$

Jacobians are computed according to the relative translational velocity, ignoring the $\dot \av_0$ part.
Using this approach, coordinate constraints can be added to mechanisms to purely add internal drives, not affecting global momenta.
Furthermore, coupling to a relative rotation marker MarkerBodiesRelativeRotationCoordinate can be used to
create advanced mechanisms and gears.

It is a coordinate marker: coordinate connectors, coordinate constraints and `LoadCoordinate` use it.
Body 0 must provide position and orientation, body 1 a position, both at a local point - a rigid body,
and for body 1 also a mass point; `Assemble()` refuses other bodies.

(miniexample-markerbodiesrelativetranslationcoordinate)=
## Mini example


```python
#the translation of body 1 relative to body 0 along an axis of body 0, held by a coordinate constraint
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()))
mRel = mbs.AddMarker(MarkerBodiesRelativeTranslationCoordinate(bodyNumbers=[oGround, body], axis0=[1,0,0]))
mGround = mbs.AddMarker(MarkerNodeCoordinate(nodeNumber=nGround, coordinate=0))
mbs.AddObject(ObjectConnectorCoordinate(markerNumbers=[mGround, mRel], offset=0.3))

mbs.Assemble()
mbs.SolveDynamic()

#the body is held 0.3 along x of the ground
exu.sys['testResult'] = mbs.GetNodeOutput(node, exu.OutputVariableType.Position)[0] #0.3
```


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)