ODE/manual/剛体関数 - bambooflow Note

6. 剛体関数

6.1. 剛体の生成および破棄

dBodyID dBodyCreate (dWorldID);

位置(0,0,0)に、デフォルトの質量パラメータで、世界に剛体を作成する。そのIDを返す。

void dBodyDestroy (dBodyID);

剛体を破棄する。この剛体に付けられるジョイントはすべて中ぶらりんな状態(つまり、独立してシミュレーションに影響を受けずに削除されないでいる)の中に入れられる。

6.2. 位置(position)と方位(orientation)

void dBodySetPosition   (dBodyID, dReal x, dReal y, dReal z);
void dBodySetRotation   (dBodyID, const dMatrix3 R);
void dBodySetQuaternion (dBodyID, const dQuaternion q);
void dBodySetLinearVel  (dBodyID, dReal x, dReal y, dReal z);
void dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z);
const dReal * dBodyGetPosition   (dBodyID);
const dReal * dBodyGetRotation   (dBodyID);
const dReal * dBodyGetQuaternion (dBodyID);
const dReal * dBodyGetLinearVel  (dBodyID);
const dReal * dBodyGetAngularVel (dBodyID);

これらの関数は剛体の位置、回転、線速度および角速度の設定と取得を行う。剛体の1グループを設定した後に、新しい配置が存在するジョイント/制約と食い違っている場合、シミュレーションの結果は不確定となる。取得する場合、返した値は内部のデータ構造体へのポインタである。したがって、剛体のシステム構造体が変更されるまでは、ベクトルは有効となる。

なるほど、dBodyGetRotationは4x3回転マトリックスを返す。

6.3. 質量(mass)と力(force)

void dBodySetMass (dBodyID, const dMass *mass);
void dBodyGetMass (dBodyID, dMass *mass);

剛体の質量を設定・取得する（質量(mass)関数を参照)。

void dBodyAddForce            (dBodyID, dReal fx, dReal fy, dReal fz);
void dBodyAddTorque           (dBodyID, dReal fx, dReal fy, dReal fz);
void dBodyAddRelForce         (dBodyID, dReal fx, dReal fy, dReal fz);
void dBodyAddRelTorque        (dBodyID, dReal fx, dReal fy, dReal fz);
void dBodyAddForceAtPos       (dBodyID, dReal fx, dReal fy, dReal fz,
                                       dReal px, dReal py, dReal pz);
void dBodyAddForceAtRelPos    (dBodyID, dReal fx, dReal fy, dReal fz,
                                       dReal px, dReal py, dReal pz);
void dBodyAddRelForceAtPos    (dBodyID, dReal fx, dReal fy, dReal fz,
                                       dReal px, dReal py, dReal pz);
void dBodyAddRelForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz,
                                       dReal px, dReal py, dReal pz);

剛体に力を加える(絶対座標または相対座標)。力はそれぞれの剛体上に累積され、累積された力は各時間ステップ後にゼロにされる。

The ...RelForce and ...RelTorque functions take force vectors that are relative to the body's own frame of reference.
...RelForceと...RelTorque関数は剛体フレーム参照に関連した力ベクトルを有する。

...ForceAtPosと...ForceAtRelPos関数 は、力が適用される点を指定する過剰な位置ベクトル(絶対座標かそれぞれの剛体の相対座標)を有する。他すべての関数は質量の中心で力を適用する。

const dReal * dBodyGetForce  (dBodyID);
const dReal * dBodyGetTorque (dBodyID);

現在の累積された力とトルクベクトルを返す。返されたポインタは3つのdRealの配列を指す。返り値は内部データ構造体へのポインタである。よって、剛体システムが作られるような変更があるまで、そのベクトルは有効である。

void dBodySetForce  (dBodyID b, dReal x, dReal y, dReal z);
void dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z);

Set the body force and torque accumulation vectors. 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.
剛体の力とトルク累積ベクトルの設定。剛体が無効である間に力加算関数が呼ばれる場合については、これは主に、再開される前の無効な、力とトルクがゼロの剛体に対して有用とある。

6.4. ユーティリティ

void dBodyGetRelPointPos (dBodyID, dReal px, dReal py, dReal pz,
                         dVector3 result);
void dBodyGetRelPointVel (dBodyID, dReal px, dReal py, dReal pz,
                         dVector3 result);
void dBodyGetPointVel    (dBodyID, dReal px, dReal py, dReal pz,
                         dVector3 result);

ユーティリティ関数は剛体上の(px, py, pz)の点を受け取って、(その結果における)絶対座標での位置もしくは速度を返す。dBodyGetRelPointXXX関数は剛体の相対座標での点が与えられて、dBodyGetPointVel関数は絶対座標における点が与えられる。

void dBodyGetPosRelPoint (dBodyID, dReal px, dReal py, dReal pz,
                      	  dVector3 result);

これは、dBodyGetRelPointPosの逆の動作である。絶対座標(x,y,z)の点を受け取って、(結果)剛体の相対座標位置の点を返す。

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

Given a vector expressed in the body (or world) coordinate system (x,y,z), rotate it to the world (or body) coordinate system (result).
剛体(もしくは世界)の座標系(x,y,z)上に表現された速度を与えられる。

6.5. 自動的な有効化と無効化

すべての剛体は有効化もしくは無効化にすることができる。有効な剛体はシミュレーションに参加して、無効な剛体はターンオフしてシミュレーションステップで更新しない。新しい剛体はいつも有効な状態で生成される。

有効な剛体とジョイントを介して接続された無効だった剛体は、次のシミュレーションステップで自動的に再有効となる。

無効な剛体はCPU時間を消費しない。そのため、シミュレーションを速度向上させるためには、剛体が静止しているときには無効化させるべきである。これは自動無効化特性(auto-disable feature)で自動化することができるようになる。

剛体がその自動無効化フラグが入った状態のとき、剛体は自動的に無効になる

1. 既定のシミュレーションステップ数に何もしないとき
2. 既定のシミュレーション時間に何もしないとき

剛体は、線速度と角速度の両方の大きさが閾値より低い場合は、何もしていないとみなされる。

したがって、すべての剛体は有効化フラグ、アイドルステップカウント、アイドル時間、線速度/角速度の閾値の5つの自動無効化パラメータを持っている。新たに生成された剛体は、これらのパラメータを世界から取得する。

The following functions set and get the enable/disable parameters of a body.
次の関数は剛体の有効/無効パラメータを設定・取得する。

void dBodyEnable (dBodyID);
void dBodyDisable (dBodyID);

手動での剛体の有効化と無効化。注意として、有効な剛体にジョイントを介して接続される無効だった剛体は、次のシミュレーションステップで自動的に再有効となる。

int dBodyIsEnabled (dBodyID);

剛体が現在有効な場合は１を返して、無効な場合は0を返す。

void  dBodySetAutoDisableFlag (dBodyID, int do_auto_disable);
int   dBodyGetAutoDisableFlag (dBodyID);

剛体の自動無効化フラグの設定と取得。自動無効化がゼロでなかった場合、剛体は十分な長さのアイドル状態であるときに自動的に無効にされる。

void  dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_threshold);
dReal dBodyGetAutoDisableLinearThreshold (dBodyID);

Set and get a body's linear velocity threshold for automatic disabling. The body's linear velocity magnitude must be less than this threshold for it to be considered idle. Set the threshold to dInfinity to prevent the linear velocity from being considered.
自動的に無効化するための剛体の線速度に対する閾値の取得と設定。剛体の線速度の大きさはアイドル状態と見なされたときの閾値より小さくなければならない。線速度を考慮してdInifinityの閾値を設定する。

void  dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_threshold);
dReal dBodyGetAutoDisableAngularThreshold (dBodyID);

Set and get a body's angular velocity threshold for automatic disabling. The body's linear angular magnitude must be less than this threshold for it to be considered idle. Set the threshold to dInfinity to prevent the angular velocity from being considered.
自動的な無効化のための剛体の角速度に対する閾値の設定と取得。剛体の角速度の大きさはアイドル状態と見なされたときの閾値よりも小さくなければならない。角速度を考慮してdInfinityの閾値を設定する。

void  dBodySetAutoDisableSteps (dBodyID, int steps);
int   dBodyGetAutoDisableSteps (dBodyID);

Set and get the number of simulation steps that a body must be idle before it is automatically disabled. Set this to zero to disable consideration of the number of steps.
自動的に無効化されるまでの剛体のアイドル状態のシミュレーションステップ数の取得と設定。ステップ(steps)の数の考慮を無効にするためにはこれをゼロに設定する。

void  dBodySetAutoDisableTime (dBodyID, dReal time);
dReal dBodyGetAutoDisableTime (dBodyID);

Set and get the amount of simulaton time that a body must be idle before it is automatically disabled. Set this to zero to disable consideration of the amount of simulation time.
自動的に無効化されるまでの剛体のアイドル状態のシミュレーション時間の量の設定と取得。シミュレーション時間(time)の量の考慮を無効似するためにこれをゼロに設定する。

void  dBodySetAutoDisableDefaults (dBodyID);

Set the auto-disable parameters of the body to the default parameters that have been set on the world.
世界に設定されているデフォルトパラメータのために剛体の自動無効化パラメータの設定する。

6.6. いろいろな剛体関数

void  dBodySetData (dBodyID, void *data);
void *dBodyGetData (dBodyID);

Get and set the body's user-data pointer.
剛体のユーザデータ・ポインタの取得と設定。

void dBodySetFiniteRotationMode (dBodyID, int mode);

この関数は剛体の方位が各時間ステップで更新される方法を制御する。mode引数は次の値が指定できる：

• 0: "無限小(infinitesimal)"方位更新がなされる。これは計算が高速であるが、たまに剛体が高速で回転するような間違いの原因となる。特にそれらの剛体が他の剛体と接続されているときに起こる。これはすべての新しく剛体が生成されたときのデフォルトである。
• 1: "有限(finite)"方位更新がなされる。これは計算の負担がより大きくなるが、より正確な高速回転が行える。しかしながら注意が必要で、高速回転はシミュレーション上の様々なエラーとなるが、このモードはそれらのエラーの原因の1つを単に修復することになる。

int dBodyGetFiniteRotationMode (dBodyID);

剛体の現在の有限回転モードを返す。(0または1)

void dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z);

これは剛体に有限回転軸を設定する。これは単に有限回転モードが設定されたときの軸を意味する(dBodySetFiniteRotationModeを参照)。

この軸がゼロ(0,0,0)の場合、完全な有限回転は剛体において形成される。

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 dBodyGetFiniteRotationAxis (dBodyID, dVector3 result);

剛体の現在の有限回転軸を返す。

int dBodyGetNumJoints (dBodyID b);

剛体へ接続されたジョイントの数を返す。

dJointID dBodyGetJoint (dBodyID, int index);

indexにより与えられた剛体に接続されたジョイントを返す。有効なindexは、0からn-1である。ここで、nはdBodyGetNumJointsより返された値である。

void dBodySetGravityMode (dBodyID b, int mode);
int dBodyGetGravityMode (dBodyID b);

剛体が世界の重力に影響を受けるかどうかの設定/取得。modeが0のとき影響し、modeが1のときしない。新たに生成された剛体はいつも世界の重力に影響を受ける。