ODE  0.13.1
 All Data Structures Functions Variables Typedefs Enumerations Groups
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:

Other body properties are usually constant over time:

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
bodythe body to query
posa copy of the body position
See Also
dBodyGetPosition
void dBodyCopyQuaternion ( dBodyID  body,
dQuaternion  quat 
)

Copy the orientation of a body into a quaternion.

Parameters
bodythe body to query
quata copy of the orientation quaternion
See Also
dBodyGetQuaternion
void dBodyCopyRotation ( dBodyID  ,
dMatrix3  R 
)

Copy the rotation of a body.

Parameters
bodythe body to query
Ra copy of the rotation matrix
See Also
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
dBodyIDidentification 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
resultwill 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
indexvalid 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.

See Also
dWorldGetMaxAngularSpeed()
dGeomID dBodyGetNextGeom ( dGeomID  g)

returns the next geom associated with the same body.

Parameters
ga geom attached to some body.
Returns
the next geom attached to the same body, or 0.
See Also
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
resultwill 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.
See Also
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
resultwill 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
resultwill 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
resultwill 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
dataarbitraty pointer
void dBodySetDynamic ( dBodyID  )

Set rigid body to dynamic state (default).

Parameters
dBodyIDidentification 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
modecan 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
modewhen 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
enablednonzero (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
dBodyIDidentification of body.
void dBodySetMaxAngularSpeed ( dBodyID  b,
dReal  max_speed 
)

Set the body's maximum angular speed.

See Also
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
bthe body that needs to be watched.
callbackthe 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
resultwill contain the result.
void dBodyVectorToWorld ( dBodyID  ,
dReal  px,
dReal  py,
dReal  pz,
dVector3  result 
)

Convert from local to world coordinates.

Parameters
resultwill contain the result.