Rigid Bodies

Functions
ODE_API dReal	dBodyGetAutoDisableLinearThreshold (dBodyID)
	Get auto disable linear average threshold.
ODE_API void	dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_average_threshold)
	Set auto disable linear average threshold.
ODE_API dReal	dBodyGetAutoDisableAngularThreshold (dBodyID)
	Get auto disable angular average threshold.
ODE_API void	dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_average_threshold)
	Set auto disable angular average threshold.
ODE_API int	dBodyGetAutoDisableAverageSamplesCount (dBodyID)
	Get auto disable average size (samples count).
ODE_API void	dBodySetAutoDisableAverageSamplesCount (dBodyID, unsigned int average_samples_count)
	Set auto disable average buffer size (average steps).
ODE_API int	dBodyGetAutoDisableSteps (dBodyID)
	Get auto steps a body must be thought of as idle to disable.
ODE_API void	dBodySetAutoDisableSteps (dBodyID, int steps)
	Set auto disable steps.
ODE_API dReal	dBodyGetAutoDisableTime (dBodyID)
	Get auto disable time.
ODE_API void	dBodySetAutoDisableTime (dBodyID, dReal time)
	Set auto disable time.
ODE_API int	dBodyGetAutoDisableFlag (dBodyID)
	Get auto disable flag.
ODE_API void	dBodySetAutoDisableFlag (dBodyID, int do_auto_disable)
	Set auto disable flag.
ODE_API void	dBodySetAutoDisableDefaults (dBodyID)
	Set auto disable defaults.
ODE_API dWorldID	dBodyGetWorld (dBodyID)
	Retrives the world attached to te given body.
ODE_API dBodyID	dBodyCreate (dWorldID)
	Create a body in given world.
ODE_API void	dBodyDestroy (dBodyID)
	Destroy a body.
ODE_API void	dBodySetData (dBodyID, void *data)
	Set the body's user-data pointer.
ODE_API void *	dBodyGetData (dBodyID)
	Get the body's user-data pointer.
ODE_API void	dBodySetPosition (dBodyID, dReal x, dReal y, dReal z)
	Set position of a body.
ODE_API void	dBodySetRotation (dBodyID, const dMatrix3 R)
	Set the orientation of a body.
ODE_API void	dBodySetQuaternion (dBodyID, const dQuaternion q)
	Set the orientation of a body.
ODE_API void	dBodySetLinearVel (dBodyID, dReal x, dReal y, dReal z)
	Set the linear velocity of a body.
ODE_API void	dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z)
	Set the angular velocity of a body.
ODE_API const dReal *	dBodyGetPosition (dBodyID)
	Get the position of a body.
ODE_API void	dBodyCopyPosition (dBodyID body, dVector3 pos)
	Copy the position of a body into a vector.
ODE_API const dReal *	dBodyGetRotation (dBodyID)
	Get the rotation of a body.
ODE_API void	dBodyCopyRotation (dBodyID, dMatrix3 R)
	Copy the rotation of a body.
ODE_API const dReal *	dBodyGetQuaternion (dBodyID)
	Get the rotation of a body.
ODE_API void	dBodyCopyQuaternion (dBodyID body, dQuaternion quat)
	Copy the orientation of a body into a quaternion.
ODE_API const dReal *	dBodyGetLinearVel (dBodyID)
	Get the linear velocity of a body.
ODE_API const dReal *	dBodyGetAngularVel (dBodyID)
	Get the angular velocity of a body.
ODE_API void	dBodySetMass (dBodyID, const dMass *mass)
	Set the mass of a body.
ODE_API void	dBodyGetMass (dBodyID, dMass *mass)
	Get the mass of a body.
ODE_API void	dBodyAddForce (dBodyID, dReal fx, dReal fy, dReal fz)
	Add force at centre of mass of body in absolute coordinates.
ODE_API void	dBodyAddTorque (dBodyID, dReal fx, dReal fy, dReal fz)
	Add torque at centre of mass of body in absolute coordinates.
ODE_API void	dBodyAddRelForce (dBodyID, dReal fx, dReal fy, dReal fz)
	Add force at centre of mass of body in coordinates relative to body.
ODE_API void	dBodyAddRelTorque (dBodyID, dReal fx, dReal fy, dReal fz)
	Add torque at centre of mass of body in coordinates relative to body.
ODE_API 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.
ODE_API 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.
ODE_API 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.
ODE_API 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.
ODE_API const dReal *	dBodyGetForce (dBodyID)
	Return the current accumulated force vector.
ODE_API const dReal *	dBodyGetTorque (dBodyID)
	Return the current accumulated torque vector.
ODE_API void	dBodySetForce (dBodyID b, dReal x, dReal y, dReal z)
	Set the body force accumulation vector.
ODE_API void	dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z)
	Set the body torque accumulation vector.
ODE_API void	dBodyGetRelPointPos (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
	Get world position of a relative point on body.
ODE_API void	dBodyGetRelPointVel (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
	Get velocity vector in global coords of a relative point on body.
ODE_API 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.
ODE_API 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.
ODE_API void	dBodyVectorToWorld (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
	Convert from local to world coordinates.
ODE_API void	dBodyVectorFromWorld (dBodyID, dReal px, dReal py, dReal pz, dVector3 result)
	Convert from world to local coordinates.
ODE_API void	dBodySetFiniteRotationMode (dBodyID, int mode)
	controls the way a body's orientation is updated at each timestep.
ODE_API void	dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z)
	sets the finite rotation axis for a body.
ODE_API int	dBodyGetFiniteRotationMode (dBodyID)
	Get the way a body's orientation is updated each timestep.
ODE_API void	dBodyGetFiniteRotationAxis (dBodyID, dVector3 result)
	Get the finite rotation axis.
ODE_API int	dBodyGetNumJoints (dBodyID b)
	Get the number of joints that are attached to this body.
ODE_API dJointID	dBodyGetJoint (dBodyID, int index)
	Return a joint attached to this body, given by index.
ODE_API void	dBodyEnable (dBodyID)
	Manually enable a body.
ODE_API void	dBodyDisable (dBodyID)
	Manually disable a body.
ODE_API int	dBodyIsEnabled (dBodyID)
	Check wether a body is enabled.
ODE_API void	dBodySetGravityMode (dBodyID b, int mode)
	Set whether the body is influenced by the world's gravity or not.
ODE_API int	dBodyGetGravityMode (dBodyID b)
	Get whether the body is influenced by the world's gravity or not.

---

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

ODE_API 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

See also:

dBodyGetPosition

ODE_API 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

See also:

dBodyGetQuaternion

ODE_API void dBodyCopyRotation	(	dBodyID	,
		dMatrix3	R
	)

Copy the rotation of a body.

Parameters:

	body	the body to query
	R	a copy of the rotation matrix

See also:

dBodyGetRotation

ODE_API dBodyID dBodyCreate

(

dWorldID

)

Create a body in given world.

Remarks:

Default mass parameters are at position (0,0,0).

ODE_API 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.

ODE_API 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.

ODE_API void dBodyEnable

(

dBodyID

)

Manually enable a body.

Parameters:

dBodyID

identification of body.

ODE_API dReal dBodyGetAutoDisableAngularThreshold

(

dBodyID

)

Get auto disable angular average threshold.

Returns:

the threshold

ODE_API int dBodyGetAutoDisableAverageSamplesCount

(

dBodyID

)

Get auto disable average size (samples count).

Returns:

the nr of steps/size.

ODE_API int dBodyGetAutoDisableFlag

(

dBodyID

)

Get auto disable flag.

Returns:

0 or 1

ODE_API dReal dBodyGetAutoDisableLinearThreshold

(

dBodyID

)

Get auto disable linear average threshold.

Returns:

the threshold

ODE_API int dBodyGetAutoDisableSteps

(

dBodyID

)

Get auto steps a body must be thought of as idle to disable.

Returns:

the nr of steps

ODE_API dReal dBodyGetAutoDisableTime

(

dBodyID

)

Get auto disable time.

Returns:

nr of seconds

ODE_API void* dBodyGetData

(

dBodyID

)

Get the body's user-data pointer.

Returns:

a pointer to the user's data.

ODE_API void dBodyGetFiniteRotationAxis	(	dBodyID	,
		dVector3	result
	)

Get the finite rotation axis.

Parameters:

result

will contain the axis.

ODE_API int dBodyGetFiniteRotationMode

(

dBodyID

)

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

Returns:

the mode 0 (infitesimal) or 1 (finite).

ODE_API 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.

ODE_API int dBodyGetGravityMode

(

dBodyID

b

)

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

Returns:

nonzero means gravity affects this body.

ODE_API 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().

ODE_API int dBodyGetNumJoints

(

dBodyID

b

)

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

Returns:

nr of joints

ODE_API 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.

ODE_API 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

ODE_API 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.

ODE_API const dReal* dBodyGetQuaternion

(

dBodyID

)

Get the rotation of a body.

Returns:

pointer to 4 scalars that represent the quaternion.

ODE_API 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.

ODE_API 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.

ODE_API const dReal* dBodyGetRotation

(

dBodyID

)

Get the rotation of a body.

Returns:

pointer to a 4x3 rotation matrix.

ODE_API 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.

ODE_API dWorldID dBodyGetWorld

(

dBodyID

)

Retrives the world attached to te given body.

Remarks:

ODE_API int dBodyIsEnabled

(

dBodyID

)

Check wether a body is enabled.

Returns:

1 if a body is currently enabled or 0 if it is disabled.

ODE_API void dBodySetAutoDisableAngularThreshold	(	dBodyID	,
		dReal	angular_average_threshold
	)

Set auto disable angular average threshold.

Returns:

the threshold

ODE_API void dBodySetAutoDisableAverageSamplesCount	(	dBodyID	,
		unsigned int	average_samples_count
	)

Set auto disable average buffer size (average steps).

Parameters:

average_samples_count

the nr of samples to review.

ODE_API void dBodySetAutoDisableDefaults

(

dBodyID

)

Set auto disable defaults.

Remarks:

Set the values for the body to those set as default for the world.

ODE_API void dBodySetAutoDisableFlag	(	dBodyID	,
		int	do_auto_disable
	)

Set auto disable flag.

Parameters:

do_auto_disable

0 or 1

ODE_API void dBodySetAutoDisableLinearThreshold	(	dBodyID	,
		dReal	linear_average_threshold
	)

Set auto disable linear average threshold.

Returns:

the threshold

ODE_API void dBodySetAutoDisableSteps	(	dBodyID	,
		int	steps
	)

Set auto disable steps.

Parameters:

steps

the nr of steps.

ODE_API void dBodySetAutoDisableTime	(	dBodyID	,
		dReal	time
	)

Set auto disable time.

Parameters:

time

nr of seconds.

ODE_API void dBodySetData	(	dBodyID	,
		void *	data
	)

Set the body's user-data pointer.

Parameters:

data

arbitraty pointer

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API 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.

ODE_API void dBodyVectorFromWorld	(	dBodyID	,
		dReal	px,
		dReal	py,
		dReal	pz,
		dVector3	result
	)

Convert from world to local coordinates.

Parameters:

result

will contain the result.

ODE_API void dBodyVectorToWorld	(	dBodyID	,
		dReal	px,
		dReal	py,
		dReal	pz,
		dVector3	result
	)

Convert from local to world coordinates.

Parameters:

result

will contain the result.

---