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

(sec-item-objectcontactspheretriangle)=
# ObjectContactSphereTriangle

A simple contact connector between a sphere (marker0) and a triangle (marker1). Penalty-based contact is computed from penetration of the sphere with the triangle, including contact with edges if desired.

Author: Gerstmayr Johannes

**Simpler**: [`mbs.CreateSphereTriangleContact`](#sec-mainsystemextensions-createspheretrianglecontact) or [`mbs.CreateSphereQuadContact`](#sec-mainsystemextensions-createspherequadcontact) add this item, with what it needs, in one call.

## Interface

- Nodes it takes: [](#sec-item-nodegenericdata)
- Markers it acts on: those providing `Position` (and `Orientation` if `dynamicFriction` is not zero): [](#sec-item-markerbodyposition), [](#sec-item-markerbodyrigid), [](#sec-item-markernodeposition), [](#sec-item-markernoderigid), [](#sec-item-markersuperelementposition), [](#sec-item-markersuperelementrigid), [](#sec-item-markerkinematictreerigid)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | constraints's unique name |
| **markerNumbers** | ArrayMarkerIndex | 2 | [ invalid (-1), invalid (-1) ] | (symbol: $[m0,m1]\tp$) list of markers representing the center of the sphere (marker 0) and the reference point of the triangle (marker 1), where triangle nodal positions are defined in the local coordinates of marker 1. |
| **nodeNumber** | NodeIndex |  | invalid (-1) | (symbol: $n_d$) node number of a NodeGenericData with numberOfDataCoordinates = 4 dataCoordinates, needed for discontinuous iteration (friction and contact); data variables contain values from last PostNewton iteration: data[0] is the gap, data[1] is the norm of the tangential velocity (and thus contains information if it is stick or slip); data[2] is the impact velocity; data[3] is unused. |
| **sphereRadius** | PReal |  | 0. | (symbol: $r_S$) radius of sphere [SI:m]; **must be given**: the default is only a placeholder |
| **trianglePoints** | Vector3DList |  | [] | (symbol: $[\LU{m_1}{\pv}_0,\LU{m_1}{\pv}_1,\LU{m_1}{\pv}_2]$) triangle points, defined in marker 1 local coordinates |
| **includeEdges** | UInt |  | 7 | Binary flag, where 1 defines contact with edges 0, 2 with edge 1 and 4 with edge 2; 7 means that contact with all edges is included; edge 0 is the edge between node 0 and node 1 |
| **dynamicFriction** | UReal |  | 0. | (symbol: $\mu_d$) dynamic friction coefficient for friction model, see StribeckFunction in exudyn.physics, [](#sec-module-physics) |
| **frictionProportionalZone** | UReal |  | 0.001 | (symbol: $v_{reg}$) limit velocity [m/s] up to which the friction is proportional to velocity (for regularization / avoid numerical oscillations), see StribeckFunction in exudyn.physics (named regVel there!), [](#sec-module-physics) |
| **contactStiffness** | UReal |  | 0. | (symbol: $k_c$) normal contact stiffness [SI:N/m] (units in case that $n_\mathrm{exp}=1$) |
| **contactDamping** | UReal |  | 0. | (symbol: $d_c$) linear normal contact damping [SI:N/(m s)]; this damping should be used (!=0) if the restitution coefficient is < 1, as it changes its behavior. |
| **contactStiffnessExponent** | PReal |  | 1. | (symbol: $n_\mathrm{exp}$) exponent in normal contact model [SI:1] |
| **restitutionCoefficient** | PReal |  | 1. | (symbol: $e_\mathrm{res}$) coefficient of restitution [SI:1]; used in particular for impact mechanics; different models available within parameter impactModel; the coefficient must be > 0, but can become arbitrarily small to emulate plastic impact (however very small values may lead to numerical problems) |
| **minimumImpactVelocity** | UReal |  | 0. | (symbol: $\dot\delta_\mathrm{-,min}$) minimal impact velocity for coefficient of restitution [SI:1]; this value adds a lower bound for impact velocities for calculation of viscous impact force; it can be used to apply a larger damping behavior for low impact velocities (or permanent contact) |
| **impactModel** | UInt |  | 0 | (symbol: $m_\mathrm{impact}$) number of impact model: 0) linear model (only linear damping is used); 1) Hunt-Crossley model; 2) Gonthier/EtAl-Carvalho/Martins mixed model; model 2 is much more accurate regarding the coefficient of restitution, in the full range [0,1] except for 0; NOTE: in all models, the linear contactDamping is added, if not set to zero! |
| **activeConnector** | Bool |  | True | flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint |
| **visualization** | VObjectContactSphereTriangle |  |  | parameters for visualization of item |


Renamed parameters, still taken with a `DeprecationWarning`: `radiusSphere` (deprecated since 1.12.258, removed in 2031): use `sphereRadius`.

## Visualization parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **show** | Bool |  | False | set true, if item is shown in visualization and false if it is not shown; draws spheres by given radii |
| **color** | Float4 | 4 | [0.7,0.7,0.7,1.] | RGBA connector color; if R==-1, use default color |

## Drawing

Drawn as [all connectors](#sec-drawing-objectsconnector); the sphere with `contact.showSpheres` and the triangle with `contact.showTriangles`.

Settings beyond those of all connectors: [`contact.colorSpheres`](#sec-vsettingscontact), [`contact.colorTriangles`](#sec-vsettingscontact), [`contact.showSpheres`](#sec-vsettingscontact), [`contact.showTriangles`](#sec-vsettingscontact), [`general.sphereTiling`](#sec-vsettingsgeneral).

## Output variables

Available as `OutputVariableType` in sensors, `Get...Output()` and other functions:

```{tabularcolumns} \Y{0.25}\Y{0.25}\Y{0.5}
```

| output variable | symbol | description |
|---|---|---|
| Position |  | contact center point (also given for positive gap, when no contact occurs) |
| Displacement |  | global vector from the sphere center (marker 0) to the closest point of the triangle |
| Velocity |  | velocity of the closest point of the triangle, with the rotation of its body, relative to the sphere center |
| DisplacementLocal |  | 1D Vector, containing only gap |
| Director1 |  | normalized vector from sphere midpoint (marker 0) to triangle contact point |
| Force |  | global contact force vector |
| Torque |  | global torque due to friction on marker 0 |

(description-objectcontactspheretriangle)=
## Detailed description

### Definition of quantities

| intermediate variables | symbol | description |
|---|---|---|
| marker m0 position | $\LU{0}{\pv}_{m0}$ | center of the sphere, provided by marker m0 |
| marker m1 position | $\LU{0}{\pv}_{m1}$ | reference point of the triangle, provided by marker m1 |
| marker m1 orientation | $\LU{0,m1}{\Rot}$ | rotation of the triangle, provided by marker m1 |
| triangle points | $\LU{0}{\pv}_{i} = \LU{0}{\pv}_{m1} + \LU{0,m1}{\Rot}\, \LU{m1}{\pv}_i$ | the three `trianglePoints` in the global frame |
| marker velocities | $\LU{0}{\vv}_{m0}$, $\LU{0}{\vv}_{m1}$ | global velocities |
| data coordinates | $\xv=[x_0,\,x_1,\,x_2,\,x_3]\tp$ | the gap (0), the norm of the tangential velocity (1), the impact velocity (2); (3) is unused |

### Geometric relations

The point $\LU{0}{\pv}_T$ of the triangle closest to the sphere center is found - inside the triangle or
on one of its edges -, and with $\Delta\pv = \LU{0}{\pv}_T - \LU{0}{\pv}_{m0}$

$$
g = \Vert \Delta\pv \Vert - r_S , \quad \LU{0}{\nv} = \frac{\Delta\pv}{\Vert \Delta\pv \Vert} .
$$

A contact on an edge counts only if `includeEdges` contains that edge (bit 1: edge 0 from point 0 to
1, bit 2: edge 1, bit 4: edge 2). The velocity of the contact point on the triangle includes the
rotation of marker 1; that of the sphere includes its rotation only if friction is used, because
only then does marker 0 need an orientation.

### Connector forces

The normal force - from the penetration $\delta = -g$, with `contactStiffness` $k_c$, the exponent
$n_\mathrm{exp}$, `contactDamping` $d_c$ and the impact model `impactModel` with the restitution
coefficient - and the regularized dry friction with $\mu_d$ and `frictionProportionalZone` are
computed exactly as for `ObjectContactSphereSphere`, see [](#sec-item-objectcontactspheresphere),
with the normal $\LU{0}{\nv}$ and the relative velocity at the contact point of this contact. The force
on marker 1 is $\LU{0}{\fv}$, the force on marker 0 is $-\LU{0}{\fv}$; the friction force also gives a
torque about the centers. The data coordinates hold the gap, the tangential velocity and the impact
velocity of the last post Newton step, which decide on contact and on the friction regime during the
Newton iterations (active set).

(miniexample-objectcontactspheretriangle)=
## Mini example


```python
#a ball dropped onto a triangle fixed to the ground
inertia = InertiaSphere(mass=1, radius=0.1)
node = mbs.AddNode(NodeRigidBodyEP(referenceCoordinates=[0.2,0.2,0.2]+eulerParameters0))
ball = mbs.AddObject(ObjectRigidBody(nodeNumber=node, mass=inertia.Mass(), inertia=inertia.GetInertia6D()))
mbs.AddLoad(LoadMassProportional(markerNumber=mbs.AddMarker(MarkerBodyMass(bodyNumber=ball)), loadVector=[0,0,-9.81]))
mGround = mbs.AddMarker(MarkerBodyRigid(bodyNumber=oGround, localPosition=[0,0,0]))
mBall = mbs.AddMarker(MarkerBodyRigid(bodyNumber=ball, localPosition=[0,0,0]))
nData = mbs.AddNode(NodeGenericData(numberOfDataCoordinates=4, initialCoordinates=[0,0,0,0]))
mbs.AddObject(ObjectContactSphereTriangle(markerNumbers=[mBall, mGround], nodeNumber=nData, sphereRadius=0.1,
                                          trianglePoints=exu.Vector3DList([[0,0,0],[1,0,0],[0,1,0]]),
                                          contactStiffness=1e5, contactDamping=1e3))

mbs.Assemble()
simulationSettings = exu.SimulationSettings()
simulationSettings.timeIntegration.numberOfSteps = 1000
mbs.SolveDynamic(simulationSettings)

#at rest on the triangle: 0.1 - m*g/k
exu.sys['testResult'] = mbs.GetNodeOutput(node, exu.OutputVariableType.Position)[2] #0.0999
```


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