ODE/manual/衝突検出2 - bambooflow Note

10. 衝突検出2

10.7. Geometry Classes

10.7.1. Sphere Class

dGeomID dCreateSphere (dSpaceID space, dReal radius);

Create a sphere geom of the given radius, and return its ID. If space is nonzero, insert it into that space. The point of reference for a sphere is its center.
与えられたradiusの球体geomを生成し、そのIDを返す。 spaceがゼロでない場合、スペースに挿入する。参照ポイントはその球体の中心である。

void dGeomSphereSetRadius (dGeomID sphere, dReal radius);

Set the radius of the given sphere.
与えられた球体の半径を設定する。

dReal dGeomSphereGetRadius (dGeomID sphere);

Return the radius of the given sphere.
与えられた球体の半径を返す。

dReal dGeomSpherePointDepth (dGeomID sphere, dReal x, dReal y, dReal z);

Return the depth of the point (x,y,z) in the given sphere. Points inside the geom will have positive depth, points outside it will have negative depth, and points on the surface will have zero depth.

10.7.2. Box Class

dGeomID dCreateBox (dSpaceID space, dReal lx, dReal ly, dReal lz);

Create a box geom of the given x/y/z side lengths (lx,ly,lz), and return its ID. If space is nonzero, insert it into that space. The point of reference for a box is its center.
与えられたx/y/zの側面の長さ( lx, ly, lz )のgeomボックスを生成し、そのIDを返す。splaceがゼロでない場合、スペースに挿入する。参照ポイントはそのボックスの中心である。

void dGeomBoxSetLengths (dGeomID box, dReal lx, dReal ly, dReal lz);

Set the side lengths of the given box.
与えられたboxの側面を設定する。

void dGeomBoxGetLengths (dGeomID box, dVector3 result);

Return in result the side lengths of the given box.
与えられたboxの側面をresultとして返す。

dReal dGeomBoxPointDepth (dGeomID box, dReal x, dReal y, dReal z);

Return the depth of the point (x,y,z) in the given box. Points inside the geom will have positive depth, points outside it will have negative depth, and points on the surface will have zero depth.

10.7.3. Plane Class

dGeomID dCreatePlane (dSpaceID space,
                     dReal a, dReal b, dReal c, dReal d);

Create a plane geom of the given parameters, and return its ID. If space is nonzero, insert it into that space. The plane equation is
a*x+b*y+c*z = d
The plane's normal vector is (a,b,c), and it must have length 1. Planes are non-placeable geoms. This means that, unlike placeable geoms, planes do not have an assigned position and rotation. This means that the parameters (a,b,c,d) are always in global coordinates. In other words it is assumed that the plane is always part of the static environment and not tied to any movable object.

void dGeomPlaneSetParams (dGeomID plane, dReal a, dReal b, dReal c, dReal d);

Set the parameters of the given plane.
与えられたplaneのパラメータを設定する。

void dGeomPlaneGetParams (dGeomID plane, dVector4 result);

Return in result the parameters of the given plane.
与えられたplaneのパラメータをresultとして返す。

dReal dGeomPlanePointDepth (dGeomID plane, dReal x, dReal y, dReal z);

Return the depth of the point (x,y,z) in the given plane. Points inside the geom will have positive depth, points outside it will have negative depth, and points on the surface will have zero depth.

10.7.4. Capped Cylinder Class

dGeomID dCreateCCylinder (dSpaceID space, dReal radius, dReal length);
Create a capped cylinder geom of the given parameters, and return its ID. If space is nonzero, insert it into that space.

A capped cylinder is like a normal cylinder except it has half-sphere caps at its ends. This feature makes the internal collision detection code particularly fast and accurate. The cylinder's length, not counting the caps, is given by length. The cylinder is aligned along the geom's local Z axis. The radius of the caps, and of the cylinder itself, is given by radius.

void dGeomCCylinderSetParams (dGeomID ccylinder,
                             dReal radius, dReal length);

Set the parameters of the given capped cylinder.

void dGeomCCylinderGetParams (dGeomID ccylinder,
                             dReal *radius, dReal *length);

Return in radius and length the parameters of the given capped cylinder.

dReal dGeomCCylinderPointDepth (dGeomID ccylinder,
                               dReal x, dReal y, dReal z);

Return the depth of the point (x,y,z) in the given capped cylinder. Points inside the geom will have positive depth, points outside it will have negative depth, and points on the surface will have zero depth.

10.7.5. Ray Class

A ray is different from all the other geom classes in that it does not represent a solid object. It is an infinitely thin line that starts from the geom's position and extends in the direction of the geom's local Z-axis.
rayは固体を表さないので他のすべてのgeomクラスとは異なる。 geomの位置からスタートし、geomのローカルのZ軸の方向に伸びる無限に薄いラインである。

Calling dCollide between a ray and another geom will result in at most one contact point. Rays have their own conventions for the contact information in the dContactGeom structure (thus it is not useful to create contact joints from this information):
線と別のgeomの間のdCollideを呼ぶことは、大部分で1つの 接触ポイントで終わる。線はdContactGeom構造体に接触情報の条約を持つ(したがって、この情報から接触ジョイントを生成のために用いられな い)：

• pos - This is the point at which the ray intersects the surface of the other geom, regardless of whether the ray starts from inside or outside the geom.
• normal - This is the surface normal of the other geom at the contact point. if dCollide is passed the ray as its first geom then the normal will be oriented correctly for ray reflection from that surface (otherwise it will have the opposite sign).
• depth - This is the distance from the start of the ray to the contact point.

Rays are useful for things like visibility testing, determining the path of projectiles or light rays, and for object placement.

dGeomID dCreateRay (dSpaceID space, dReal length);

Create a ray geom of the given length, and return its ID. If space is nonzero, insert it into that space.

void dGeomRaySetLength (dGeomID ray, dReal length);

Set the length of the given ray.
与えられたrayの長さを設定する。

dReal dGeomRayGetLength (dGeomID ray);

Get the length of the given ray.
与えられたrayの長さを取得する。

void dGeomRaySet (dGeomID ray, dReal px, dReal py, dReal pz,
                 dReal dx, dReal dy, dReal dz);

Set the starting position (px,py,pz) and direction (dx,dy,dz) of the given ray. The ray's rotation matrix will be adjusted so that the local Z-axis is aligned with the direction. Note that this does not adjust the ray's length.

void dGeomRayGet (dGeomID ray, dVector3 start, dVector3 dir);

Get the starting position (start) and direction (dir) of the ray. The returned direction will be a unit length vector.

10.7.6. Triangle Mesh Class

A triangle mesh (TriMesh) represents an arbitrary collection of triangles. The triangle mesh collision system has the following features:
三角形メッシュ(TriMesh)は、三角形の任意のコレクションを表 す。三角形メッシュ衝突システムは次の特徴を持つ：

• Any triangle ``soup'' can be represented --- i.e. the triangles are not required to have any particular strip, fan or grid structure.

どんな三角形"スープ"は表すことができる---つまり、三角 形はどんな特殊な一片(ファンか格子構造)も持つことは要求されない。

• Triangle meshes can interact with spheres, boxes, rays and other triangle meshes.

三角形メッシュは球体、箱、線、他の三角形メッシュなどと作用 することができる。

• It works well for relatively large triangles.

比較的大きな三角形にうまく働く。

• It uses temporal coherence to speed up collision tests. When a geom has its collision checked with a trimesh once, data is stored inside the trimesh. This data can be cleared with the dGeomTriMeshClearTCCache function. In the future it will be possible to disable this functionality.

それは、衝突試験をスピードを上げるために一時的に結合する。 geomが一度trimeshとの衝突を確認した場合、データはtrimeshの内部で格納される。このデータは dGeomTriMeshClearTCCache関数で取り除くことができる。今後、この機能性を無効にすることは可能である。

Trimesh/Trimesh collisions, perform quite well, but there are three minor caveats:

• The stepsize you use will, in general, have to be reduced for accurate collision resolution. Non-convex shape collision is much more dependent on the collision geometry than primitive collisions. Further, the local contact geometry will change more rapidly (and in a more complex fashion) for non-convex polytopes than it does for simple, convex polytopes such as spheres and cubes.
• In order to efficiently resolve collisions, dCollideTTL needs the positions of the colliding trimeshes in the previous timestep. This is used to calculate an estimated velocity of each colliding triangle, which is used to find the direction of impact, contact normals, etc. This requires the user to update these variables at every timestep. This update is performed outside of ODE, so it is not included in ODE itself. The code to do this looks something like this:

 const double *DoubleArrayPtr =
   Bodies[BodyIndex].TransformationMatrix->GetArray();
 dGeomTriMeshDataSet( TriMeshData,
   TRIMESH_LAST_TRANSFORMATION,
   (void *) DoubleArrayPtr );

The transformation matrix is the standard 4x4 homogeneous transform matrix, and the "DoubleArray" is the standard flattened array of the 16 matrix values.

NOTE: The triangle mesh class is not final, so in the future API changes might be expected.

dTriMeshDataID dGeomTriMeshDataCreate();

void dGeomTriMeshDataDestroy (dTriMeshDataID g);
Creates and destroys a dTriMeshData object which is used to store mesh data.

void dGeomTriMeshDataBuild (dTriMeshDataID g, const void* Vertices,
                           int VertexStride, int VertexCount,
		    const void* Indices, int IndexCount,
                           int TriStride, const void* Normals);

Used for filling a dTriMeshData object with data. No data is copied here, so the pointers passed into this function must remain valid. This is how the strided data works:

struct StridedVertex {
  dVector3 Vertex;  // 4th component can be left out, reducing memory usage
  // Userdata
};
int VertexStride = sizeof (StridedVertex);

struct StridedTri {
  int Indices[3];
  // Userdata
};
int TriStride = sizeof (StridedTri);

The Normals argument is optional: the normals of the faces of each trimesh object. For example,

 dTriMeshDataID TriMeshData;
 TriMeshData = dGeomTriMeshGetTriMeshDataID (
       Bodies[BodyIndex].GeomID);

 // as long as dReal == floats
 dGeomTriMeshDataBuildSingle (TriMeshData,
       // Vertices
       Bodies[BodyIndex].VertexPositions,
       3*sizeof(dReal), (int) numVertices,
       // Faces
       Bodies[BodyIndex].TriangleIndices,
       (int) NumTriangles, 3*sizeof(unsigned int),
       // Normals
       Bodies[BodyIndex].FaceNormals);

This pre-calculation saves some time during evaluation of the contacts, but isn't necessary. If you don't want to calculate the face normals before construction (or if you have enormous trimeshes and know that only very few faces will be touching and want to save time), just pass a "NULL" for the Normals argument, and dCollideTTL will take care of the normal calculations itself.

void dGeomTriMeshDataBuildSimple (dTriMeshDataID g, const dVector3*Vertices,
                                 int VertexCount, const int* Indices,
                                 int IndexCount);

Simple build function provided for convenience.

typedef int dTriCallback (dGeomID TriMesh, dGeomID RefObject, int TriangleIndex);
void dGeomTriMeshSetCallback (dGeomID g, dTriCallback *Callback);
dTriCallback* dGeomTriMeshGetCallback (dGeomID g);
Optional per triangle callback. Allows the user to say if collision with a particular triangle is wanted. If the return value is zero no contact will be generated.

typedef void dTriArrayCallback (dGeomID TriMesh, dGeomID RefObject,
                               const int* TriIndices, int TriCount);
void dGeomTriMeshSetArrayCallback (dGeomID g, dTriArrayCallback* ArrayCallback);

dTriArrayCallback *dGeomTriMeshGetArrayCallback (dGeomID g);
Optional per geom callback. Allows the user to get the list of all intersecting triangles in one shot.

typedef int dTriRayCallback (dGeomID TriMesh, dGeomID Ray, int TriangleIndex,
                            dReal u, dReal v);
void dGeomTriMeshSetRayCallback (dGeomID g, dTriRayCallback* Callback);

dTriRayCallback *dGeomTriMeshGetRayCallback (dGeomID g);
Optional Ray callback. Allows the user to determine if a ray collides with a triangle based on the barycentric coordinates of an intersection. The user can for example sample a bitmap to determine if a collision should occur.

dGeomID dCreateTriMesh (dSpaceID space, dTriMeshDataID Data,
                       dTriCallback *Callback,
                       dTriArrayCallback * ArrayCallback,
                       dTriRayCallback* RayCallback);

Constructor. The Data member defines the vertex data the newly created triangle mesh will use.

void dGeomTriMeshSetData (dGeomID g, dTriMeshDataID Data);

Replaces the current data.

void dGeomTriMeshClearTCCache (dGeomID g);

Clears the internal temporal coherence caches.

void dGeomTriMeshGetTriangle (dGeomID g, int Index, dVector3 *v0,
                             dVector3 *v1, dVector3 *v2);

Retrieves a triangle in object space. The v0, v1 and v2 arguments are optional.

void dGeomTriMeshGetPoint (dGeomID g, int Index, dReal u, dReal v,
                          dVector3 Out);

Retrieves a position in object space based on the incoming data.

void dGeomTriMeshEnableTC(dGeomID g, int geomClass, int enable);

int dGeomTriMeshIsTCEnabled(dGeomID g, int geomClass);
These functions can be used to enable/disable the use of temporal coherence during tri-mesh collision checks. Temporal coherence can be enabled/disabled per tri-mesh instance/geom class pair, currently it works for spheres and boxes. The default for spheres and boxes is 'false'.

The 'enable' param should be 1 for true, 0 for false.

Temporal coherence is optional because allowing it can cause subtle efficiency problems in situations where a tri-mesh may collide with many different geoms during its lifespan. If you enable temporal coherence on a tri-mesh then these problems can be eased by intermittently calling dGeomTriMeshClearTCCache for it.

10.7.7. Geometry Transform Class

A geometry transform `T' is a geom that encapsulates another geom `E', allowing E to be positioned and rotated arbitrarily with respect to its point of reference.
形状変形’T’は別のgeom’E’をカプセルに入れるgeomで、E が参照ポイントに関して任意に位置し回転することを可能にする。

Most placeable geoms (like the sphere and box) have their point of reference corresponding to their center of mass, allowing them to be easily connected to dynamics objects. Transform objects give you more flexibility - for example, you can offset the center of a sphere, or rotate a cylinder so that its axis is something other than the default.
もっとも配置できるgeom(球体やボックスのような)は、それらの質 量中心に対応する参照ポイントを持ち、力学オブジェクトに容易に接続が可能である。変形オブジェクトは弾力性が与えられる。例えば、球体の中心を補正でき たり、または軸がデフォルトでないようなシリンダの回転を補正できる。

T mimics the object E that it encapsulates: T is inserted into a space and attached to a body as though it was E. E itself must not be inserted into a space or attached to a body. E's position and rotation are set to constant values that say how it is transformed relative to T. If E's position and rotation are left at their default values, T will behave exactly like E would have if you had used it directly.
Tはカプセル化されたEオブジェクトに似た構造である：Tはスペースに 挿入され、Eのような剛体に繋がれる。E自体はスペースに挿入または、剛体に繋がれてはいけない。Eの位置と回転は、Tに関係したものを変形させた一定値 に設定される。Eの位置と回転がデフォルト値で残された場合、それを直接使用していたならば、Eが持つように、Tは正確に作用するだろう。

dGeomID dCreateGeomTransform (dSpaceID space);

Create a new geometry transform object, and return its ID. If space is nonzero, insert it into that space. On creation the encapsulated geometry is set to 0.
新しい形状変形したオブジェクトを生成し、そのIDを返す。space が非ゼロである場合は、そのspaceに挿入する。生成においては、カプセルに入れられた幾何学は0に設定される。

void dGeomTransformSetGeom (dGeomID g, dGeomID obj);

Set the geom that the geometry transform g encapsulates. The object obj must not be inserted into any space, and must not be associated with any body.
カプセルに入った形状変形したgのgeomを設定する。objオブジェ クトは任意のスペースに挿入されてはならない、そして任意の剛体に関係していてはいけない。

If g has its clean-up mode turned on, and it already encapsulates an object, the old object will be destroyed before it is replaced with the new one.
gがクリーンアップ・モードで付けているとき、それが既にオブジェクト をカプセルに入れる場合、新しいものと取り替えられる前に、古いオブジェクトが破棄される。

dGeomID dGeomTransformGetGeom (dGeomID g);

Get the geom that the geometry transform g encapsulates.
カプセル化された幾何学トランスフォームのgであるgeomを取得す る。

void dGeomTransformSetCleanup (dGeomID g, int mode);
int dGeomTransformGetCleanup (dGeomID g);

Set and get the clean-up mode of geometry transform g. If the clean-up mode is 1, then the encapsulated object will be destroyed when the geometry transform is destroyed. If the clean-up mode is 0 this does not happen. The default clean-up mode is 0.
形状変形gのクリーンアップモードの設定取得を行う。クリーンアップ モードが１の場合、カプセル化されたオブジェクトは形状変形が破棄されたとき破棄される。クリーンアップモードが０の場合、なにも起こらない。デフォルト のクリーンアップモードは０である。

void dGeomTransformSetInfo (dGeomID g, int mode);
int dGeomTransformGetInfo (dGeomID g);

Set and get the "information" mode of geometry transform g. The mode can be 0 or 1. The default mode is 0.

With mode 0, when a transform object is collided with another object (using dCollide

(tx_geom,other_geom,...)), the g1 field of the dContactGeom structure is set to the geom that is encapsulated by the transform object. This value of g1 allows the caller to interrogate the type of the geom that is transformed, but it does not allow the caller to determine the position in global coordinates or the associated body, as both of these properties are used differently for encapsulated geoms.

With mode 1, the g1 field of the dContactGeom structure is set to the transform object itself. This makes the object appear just like any other kind of geom, as dGeomGetBody will return the attached body, and dGeomGetPosition will return the global position. To get the actual type of the encapsulated geom in this case, dGeomTransformGetGeom must be used.

10.8. User defined classes

ODE's geometry classes are implemented internally as C++ classes. If you want to define your own geometry classes you can do this in two ways:
Use the C functions in this section. This has the advantage of providing a clean separation between your code and ODE.
Add the classes directly to ODE's source code. This has the advantage that you can use C++ so the implementation will potentially be a bit cleaner. This is also the preferred method if your collision class is generally useful and you want to contribute it to the public source base.
What follows is the C API for user defined geometry classes.

Every user defined geometry class has a unique integer number. A new geometry class (call it `X') must provide the following to ODE:
Functions that will handle collision detection and contact generation between X and one or more other classes. These functions must be of type dColliderFn, which is defined as

typedef int dColliderFn (dGeomID o1, dGeomID o2, int flags,
                        dContactGeom *contact, int skip);

This has exactly the same interface as dCollide. Each function will handle a specific collision case, where o1 has type X and o2 has some other known type.
A "selector" function, of type dGetColliderFnFn, which is defined as
typedef dColliderFn * dGetColliderFnFn (int num);
This function takes a class number (num), and returns the collider function that can handle colliding X with class num. It should return 0 if X does not know how to collide with class num. Note that if classes X and Y are to collide, only one needs to provide a function to collide with the other.

This function is called infrequently - the return values are cached and reused.
A function that will compute the axis aligned bounding box (AABB) of instances of this class. This function must be of type dGetAABBFn, which is defined as
typedef void dGetAABBFn (dGeomID g, dReal aabb[6]);
This function is given g, which has type X, and returns the axis-aligned bounding box for g. The aabb array has elements (minx, maxx,miny,maxy,minz,maxz). If you don't want to compute tight bounds for the AABB, you can just supply a pointer to dInfiniteAABB, which returns +/- infinity in each direction.
The number of bytes of "class data" that instances of this class need. For example a sphere stores its radius in the class data area, and a box stores its side lengths there.
The following things are optional for a geometry class:
A function that will destroy the class data. Most classes will not need this function, but some will want to deallocate heap memory or release other resources. This function must be of type dGeomDtorFn, which is defined as
typedef void dGeomDtorFn (dGeomID o);
The argument o has type X.
A function that will test whether a given AABB intersects with an instance of X. This is used as an early-exit test in the space collision functions. This function must be of type dAABBTestFn, which is defined as
typedef int dAABBTestFn (dGeomID o1, dGeomID o2, dReal aabb2[6]);
The argument o1 has type X. If this function is provided it is called by dSpaceCollide when o1 intersects geom o2, which has an AABB given by aabb2. It returns 1 if aabb2 intersects o1, or 0 if it does not.

This is useful, for example, for large terrains. Terrains typically have very large AABBs, which