ODE  0.13.1
Rigid Bodies

## Modules

Automatic Enabling and Disabling

Damping

## Functions

dWorldID dBodyGetWorld (dBodyID)
Retrieves the world attached to te given body. More...

dBodyID dBodyCreate (dWorldID)
Create a body in given world. More...

void dBodyDestroy (dBodyID)
Destroy a body. More...

void dBodySetData (dBodyID, void *data)
Set the body's user-data pointer. More...

void * dBodyGetData (dBodyID)
Get the body's user-data pointer. More...

void dBodySetPosition (dBodyID, dReal x, dReal y, dReal z)
Set position of a body. More...

void dBodySetRotation (dBodyID, const dMatrix3 R)
Set the orientation of a body. More...

void dBodySetQuaternion (dBodyID, const dQuaternion q)
Set the orientation of a body. More...

void dBodySetLinearVel (dBodyID, dReal x, dReal y, dReal z)
Set the linear velocity of a body.

void dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z)
Set the angular velocity of a body.

const dReal * dBodyGetPosition (dBodyID)
Get the position of a body. More...

void dBodyCopyPosition (dBodyID body, dVector3 pos)
Copy the position of a body into a vector. More...

const dReal * dBodyGetRotation (dBodyID)
Get the rotation of a body. More...

void dBodyCopyRotation (dBodyID, dMatrix3 R)
Copy the rotation of a body. More...

const dReal * dBodyGetQuaternion (dBodyID)
Get the rotation of a body. More...

void dBodyCopyQuaternion (dBodyID body, dQuaternion quat)
Copy the orientation of a body into a quaternion. More...

const dReal * dBodyGetLinearVel (dBodyID)
Get the linear velocity of a body.

const dReal * dBodyGetAngularVel (dBodyID)
Get the angular velocity of a body.

void dBodySetMass (dBodyID, const dMass *mass)
Set the mass of a body.

void dBodyGetMass (dBodyID, dMass *mass)
Get the mass of a body.

void dBodyAddForce (dBodyID, dReal fx, dReal fy, dReal fz)
Add force at centre of mass of body in absolute coordinates.

void dBodyAddTorque (dBodyID, dReal fx, dReal fy, dReal fz)
Add torque at centre of mass of body in absolute coordinates.

void dBodyAddRelForce (dBodyID, dReal fx, dReal fy, dReal fz)
Add force at centre of mass of body in coordinates relative to body.

void dBodyAddRelTorque (dBodyID, dReal fx, dReal fy, dReal fz)
Add torque at centre of mass of body in coordinates relative to body.

void dBodyAddForceAtPos (dBodyID, dReal fx, dReal fy, dReal fz, dReal px, dReal py, dReal pz)
Add force at specified point in body in global coordinates.

void dBodyAddForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz, dReal px, dReal py, dReal pz)
Add force at specified point in body in local coordinates.

void dBodyAddRelForceAtPos (dBodyID, dReal fx, dReal fy, dReal fz, dReal px, dReal py, dReal pz)
Add force at specified point in body in global coordinates.

void dBodyAddRelForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz, dReal px, dReal py, dReal pz)
Add force at specified point in body in local coordinates.

const dReal * dBodyGetForce (dBodyID)
Return the current accumulated force vector. More...

const dReal * dBodyGetTorque (dBodyID)
Return the current accumulated torque vector. More...

void dBodySetForce (dBodyID b, dReal x, dReal y, dReal z)
Set the body force accumulation vector. More...

void dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z)
Set the body torque accumulation vector. More...

void dBodyGetRelPointPos (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
Get world position of a relative point on body. More...

void dBodyGetRelPointVel (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
Get velocity vector in global coords of a relative point on body. More...

void dBodyGetPointVel (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
Get velocity vector in global coords of a globally specified point on a body. More...

void dBodyGetPosRelPoint (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
takes a point in global coordinates and returns the point's position in body-relative coordinates. More...

void dBodyVectorToWorld (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
Convert from local to world coordinates. More...

void dBodyVectorFromWorld (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
Convert from world to local coordinates. More...

void dBodySetFiniteRotationMode (dBodyID, int mode)
controls the way a body's orientation is updated at each timestep. More...

void dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z)
sets the finite rotation axis for a body. More...

int dBodyGetFiniteRotationMode (dBodyID)
Get the way a body's orientation is updated each timestep. More...

void dBodyGetFiniteRotationAxis (dBodyID, dVector3 result)
Get the finite rotation axis. More...

int dBodyGetNumJoints (dBodyID b)
Get the number of joints that are attached to this body. More...

dJointID dBodyGetJoint (dBodyID, int index)
Return a joint attached to this body, given by index. More...

void dBodySetDynamic (dBodyID)
Set rigid body to dynamic state (default). More...

void dBodySetKinematic (dBodyID)
Set rigid body to kinematic state. When in kinematic state the body isn't simulated as a dynamic body (it's "unstoppable", doesn't respond to forces), but can still affect dynamic bodies (e.g. in joints). Kinematic bodies can be controlled by position and velocity. More...

int dBodyIsKinematic (dBodyID)
Check wether a body is in kinematic state. More...

void dBodyEnable (dBodyID)
Manually enable a body. More...

void dBodyDisable (dBodyID)
Manually disable a body. More...

int dBodyIsEnabled (dBodyID)
Check wether a body is enabled. More...

void dBodySetGravityMode (dBodyID b, int mode)
Set whether the body is influenced by the world's gravity or not. More...

int dBodyGetGravityMode (dBodyID b)
Get whether the body is influenced by the world's gravity or not. More...

void dBodySetMovedCallback (dBodyID b, void(*callback)(dBodyID))
Set the 'moved' callback of a body. More...

dGeomID dBodyGetFirstGeom (dBodyID b)
Return the first geom associated with the body. More...

dGeomID dBodyGetNextGeom (dGeomID g)
returns the next geom associated with the same body. More...

dReal dBodyGetMaxAngularSpeed (dBodyID b)
Get the body's maximum angular speed. More...

void dBodySetMaxAngularSpeed (dBodyID b, dReal max_speed)
Set the body's maximum angular speed. More...

int dBodyGetGyroscopicMode (dBodyID b)
Get the body's gyroscopic state. More...

void dBodySetGyroscopicMode (dBodyID b, int enabled)
Enable/disable the body's gyroscopic term. More...

## Detailed Description

A rigid body has various properties from the point of view of the simulation. Some properties change over time:

• Position vector (x,y,z) of the body's point of reference. Currently the point of reference must correspond to the body's center of mass.
• Linear velocity of the point of reference, a vector (vx,vy,vz).
• Orientation of a body, represented by a quaternion (qs,qx,qy,qz) or a 3x3 rotation matrix.
• Angular velocity vector (wx,wy,wz) which describes how the orientation changes over time.

Other body properties are usually constant over time:

• Mass of the body.
• Position of the center of mass with respect to the point of reference. In the current implementation the center of mass and the point of reference must coincide.
• Inertia matrix. This is a 3x3 matrix that describes how the body's mass is distributed around the center of mass. Conceptually each body has an x-y-z coordinate frame embedded in it that moves and rotates with the body.

The origin of this coordinate frame is the body's point of reference. Some values in ODE (vectors, matrices etc) are relative to the body coordinate frame, and others are relative to the global coordinate frame.

Note that the shape of a rigid body is not a dynamical property (except insofar as it influences the various mass properties). It is only collision detection that cares about the detailed shape of the body.

## Function Documentation

 void dBodyCopyPosition ( dBodyID body, dVector3 pos )

Copy the position of a body into a vector.

Parameters
 body the body to query pos a copy of the body position
dBodyGetPosition
 void dBodyCopyQuaternion ( dBodyID body, dQuaternion quat )

Copy the orientation of a body into a quaternion.

Parameters
 body the body to query quat a copy of the orientation quaternion
dBodyGetQuaternion
 void dBodyCopyRotation ( dBodyID , dMatrix3 R )

Copy the rotation of a body.

Parameters
 body the body to query R a copy of the rotation matrix
dBodyGetRotation
 dBodyID dBodyCreate ( dWorldID )

Create a body in given world.

Remarks
Default mass parameters are at position (0,0,0).
 void dBodyDestroy ( dBodyID )

Destroy a body.

Remarks
All joints that are attached to this body will be put into limbo: i.e. unattached and not affecting the simulation, but they will NOT be deleted.
 void dBodyDisable ( dBodyID )

Manually disable a body.

Remarks
A disabled body that is connected through a joint to an enabled body will be automatically re-enabled at the next simulation step.
 void dBodyEnable ( dBodyID )

Manually enable a body.

Parameters
 dBodyID identification of body.
 void* dBodyGetData ( dBodyID )

Get the body's user-data pointer.

Returns
a pointer to the user's data.
 void dBodyGetFiniteRotationAxis ( dBodyID , dVector3 result )

Get the finite rotation axis.

Parameters
 result will contain the axis.
 int dBodyGetFiniteRotationMode ( dBodyID )

Get the way a body's orientation is updated each timestep.

Returns
the mode 0 (infitesimal) or 1 (finite).
 dGeomID dBodyGetFirstGeom ( dBodyID b )

Return the first geom associated with the body.

You can traverse through the geoms by repeatedly calling dBodyGetNextGeom().

Returns
the first geom attached to this body, or 0.
 const dReal* dBodyGetForce ( dBodyID )

Return the current accumulated force vector.

Returns
points to an array of 3 reals.
Remarks
The returned values are pointers to internal data structures, so the vectors are only valid until any changes are made to the rigid body system.
 int dBodyGetGravityMode ( dBodyID b )

Get whether the body is influenced by the world's gravity or not.

Returns
nonzero means gravity affects this body.
 int dBodyGetGyroscopicMode ( dBodyID b )

Get the body's gyroscopic state.

Returns
nonzero if gyroscopic term computation is enabled (default), zero otherwise.
 dJointID dBodyGetJoint ( dBodyID , int index )

Return a joint attached to this body, given by index.

Parameters
 index valid range is 0 to n-1 where n is the value returned by dBodyGetNumJoints().
 dReal dBodyGetMaxAngularSpeed ( dBodyID b )

Get the body's maximum angular speed.

dWorldGetMaxAngularSpeed()
 dGeomID dBodyGetNextGeom ( dGeomID g )

returns the next geom associated with the same body.

Parameters
 g a geom attached to some body.
Returns
the next geom attached to the same body, or 0.
dBodyGetFirstGeom
 int dBodyGetNumJoints ( dBodyID b )

Get the number of joints that are attached to this body.

Returns
nr of joints
 void dBodyGetPointVel ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

Get velocity vector in global coords of a globally specified point on a body.

Parameters
 result will contain the result.
 const dReal* dBodyGetPosition ( dBodyID )

Get the position of a body.

Remarks
When getting, the returned values are pointers to internal data structures, so the vectors are valid until any changes are made to the rigid body system structure.
dBodyCopyPosition
 void dBodyGetPosRelPoint ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

takes a point in global coordinates and returns the point's position in body-relative coordinates.

Remarks
This is the inverse of dBodyGetRelPointPos()
Parameters
 result will contain the result.
 const dReal* dBodyGetQuaternion ( dBodyID )

Get the rotation of a body.

Returns
pointer to 4 scalars that represent the quaternion.
 void dBodyGetRelPointPos ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

Get world position of a relative point on body.

Parameters
 result will contain the result.
 void dBodyGetRelPointVel ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

Get velocity vector in global coords of a relative point on body.

Parameters
 result will contain the result.
 const dReal* dBodyGetRotation ( dBodyID )

Get the rotation of a body.

Returns
pointer to a 4x3 rotation matrix.
 const dReal* dBodyGetTorque ( dBodyID )

Return the current accumulated torque vector.

Returns
points to an array of 3 reals.
Remarks
The returned values are pointers to internal data structures, so the vectors are only valid until any changes are made to the rigid body system.
 dWorldID dBodyGetWorld ( dBodyID )

Retrieves the world attached to te given body.

Remarks
 int dBodyIsEnabled ( dBodyID )

Check wether a body is enabled.

Returns
1 if a body is currently enabled or 0 if it is disabled.
 int dBodyIsKinematic ( dBodyID )

Check wether a body is in kinematic state.

Returns
1 if a body is kinematic or 0 if it is dynamic.
 void dBodySetData ( dBodyID , void * data )

Set the body's user-data pointer.

Parameters
 data arbitraty pointer
 void dBodySetDynamic ( dBodyID )

Set rigid body to dynamic state (default).

Parameters
 dBodyID identification of body.
 void dBodySetFiniteRotationAxis ( dBodyID , dReal x, dReal y, dReal z )

sets the finite rotation axis for a body.

Remarks
This is axis only has meaning when the finite rotation mode is set If this axis is zero (0,0,0), full finite rotations are performed on the body. If this axis is nonzero, the body is rotated by performing a partial finite rotation along the axis direction followed by an infinitesimal rotation along an orthogonal direction.
This can be useful to alleviate certain sources of error caused by quickly spinning bodies. For example, if a car wheel is rotating at high speed you can call this function with the wheel's hinge axis as the argument to try and improve its behavior.
 void dBodySetFiniteRotationMode ( dBodyID , int mode )

controls the way a body's orientation is updated at each timestep.

Parameters
 mode can be 0 or 1: 0: An infinitesimal'' orientation update is used. This is fast to compute, but it can occasionally cause inaccuracies for bodies that are rotating at high speed, especially when those bodies are joined to other bodies. This is the default for every new body that is created. 1: A finite'' orientation update is used. This is more costly to compute, but will be more accurate for high speed rotations.
Remarks
Note however that high speed rotations can result in many types of error in a simulation, and the finite mode will only fix one of those sources of error.
 void dBodySetForce ( dBodyID b, dReal x, dReal y, dReal z )

Set the body force accumulation vector.

Remarks
This is mostly useful to zero the force and torque for deactivated bodies before they are reactivated, in the case where the force-adding functions were called on them while they were deactivated.
 void dBodySetGravityMode ( dBodyID b, int mode )

Set whether the body is influenced by the world's gravity or not.

Parameters
 mode when nonzero gravity affects this body.
Remarks
Newly created bodies are always influenced by the world's gravity.
 void dBodySetGyroscopicMode ( dBodyID b, int enabled )

Enable/disable the body's gyroscopic term.

Disabling the gyroscopic term of a body usually improves stability. It also helps turning spining objects, like cars' wheels.

Parameters
 enabled nonzero (default) to enable gyroscopic term, 0 to disable.
 void dBodySetKinematic ( dBodyID )

Set rigid body to kinematic state. When in kinematic state the body isn't simulated as a dynamic body (it's "unstoppable", doesn't respond to forces), but can still affect dynamic bodies (e.g. in joints). Kinematic bodies can be controlled by position and velocity.

Note
A kinematic body has infinite mass. If you set its mass to something else, it loses the kinematic state and behaves as a normal dynamic body.
Parameters
 dBodyID identification of body.
 void dBodySetMaxAngularSpeed ( dBodyID b, dReal max_speed )

Set the body's maximum angular speed.

dWorldSetMaxAngularSpeed() dBodyResetMaxAngularSpeed() The default value is dInfinity, but it's a good idea to limit it at less than 500 if the body has the gyroscopic term enabled.
 void dBodySetMovedCallback ( dBodyID b, void(*)(dBodyID) callback )

Set the 'moved' callback of a body.

Whenever a body has its position or rotation changed during the timestep, the callback will be called (with body as the argument). Use it to know which body may need an update in an external structure (like a 3D engine).

Parameters
 b the body that needs to be watched. callback the callback to be invoked when the body moves. Set to zero to disable.
 void dBodySetPosition ( dBodyID , dReal x, dReal y, dReal z )

Set position of a body.

Remarks
After setting, the outcome of the simulation is undefined if the new configuration is inconsistent with the joints/constraints that are present.
 void dBodySetQuaternion ( dBodyID , const dQuaternion q )

Set the orientation of a body.

Remarks
After setting, the outcome of the simulation is undefined if the new configuration is inconsistent with the joints/constraints that are present.
 void dBodySetRotation ( dBodyID , const dMatrix3 R )

Set the orientation of a body.

Remarks
After setting, the outcome of the simulation is undefined if the new configuration is inconsistent with the joints/constraints that are present.
 void dBodySetTorque ( dBodyID b, dReal x, dReal y, dReal z )

Set the body torque accumulation vector.

Remarks
This is mostly useful to zero the force and torque for deactivated bodies before they are reactivated, in the case where the force-adding functions were called on them while they were deactivated.
 void dBodyVectorFromWorld ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

Convert from world to local coordinates.

Parameters
 result will contain the result.
 void dBodyVectorToWorld ( dBodyID , dReal px, dReal py, dReal pz, dVector3 result )

Convert from local to world coordinates.

Parameters
 result will contain the result.