# Class: dgeom

Geoms are solid objects that can collide with other geoms.

## Hierarchy

    o-+ ode
      o-+ dgeom
        o-- dbody
        o-- dgeombox
        o-- dgeomccylinder
        o-- dgeomcylinder
        o-- dgeomplane
        o-- dgeomray
        o-- dgeomsphere
        o-- dgeomtransform
        o-- dgeomtrimesh
        o-- dgeomtrimeshdata
        o-+ dspace
        | o-- dspacehash
        | o-- dspacequad
        | o-- dspacesimple
        o-- dterrain

## Interfaces:

- hashid

## Methods:

### Method overview:

- body
- category
- delete
- disabledspace
- enabledspace
- fdirnormal
- fdirpriority
- getcontactinfo
- local2world
- matrix
- maxcontactinfo
- maxcontacts
- motion1
- motion2
- nocontactgenerator
- pos
- rotaxis
- rotdeg
- rotquat
- rotrad
- setcategory
- surfaceid
- test
- testnear
- testtriarray
- transformer
- world2local

body (dgeom geom, [dbody body/other])
  returns: (dbody body)
  sets/gets the geom - if 2nd arg is not a dbody, it removes the geom from the body. The geom must not be transformed if a body is set. If the geom is transformed and the body is requested, the function will look look up the body of the transformer in a loop.
category (dgeom,int set {0-1}, int bit {0-31}, [boolean on])
  returns: ([boolean])

  Sets ODE's collide and category bits. A geom can gollidewith other geoms if cat1&col2 or cat2&col1 are not zero.

  ODE uses collide and categorybits to reject geoms for collision. They can be used to prevent collision between certain geoms. A collision is rejected if both the bitset 1 of geom A doesn't have bits in common with the bitset 2 of geom B, and if the bitset 2 of geom A doesn't have bits in common with bitset 1 of geom B.
delete (dgeom geom)
  returns: ()
  deletes a geom
disabledspace (dgeom geom,[dspace])
  returns: ([dspace])
  The disabledspace is the space a geom is put into if it has a body that is disabled. This is usefull if you have a large amount of bodies that should collide with each other but that are disabled most of the time.
enabledspace (dgeom geom,[dspace])
  returns: ([dspace])
  The enabledspace is the space a geom is put into if it has no body or if its body is enabled. This is usefull if you have a large amount of bodies that should collide with each other but that are disabled most of the time.
fdirnormal (dgeom geom,[float x,y,z])
  returns: ([float x,y,z])
  sets/gets normal vector to the friction direction vector that defines a direction along which frictional force is applied. The friction direction vector is computed as the crossproduct of the contactnormal and the normal vector that is defined here.
fdirpriority (dgeom geom,[float])
  returns: ([float])
  sets/gets priority of the fdirnormal. The priority can be used in different ways.
getcontactinfo
  (int / float x,y,z, nx,ny,nz, depth, dgeom othergeom):(dgeom geom, [int index])If contacts have been generated in your simulation and you have set the maxcontactinfo value for this geom to a value>0, a collision generation that creates contacts will also store the contact results in the contactinfo of the geom. You can read out the values for contact generation with this function. If no index is given as argument, the number of stored contactinformation are returned for this geom. If an index is passed, the contactinformation for this index is returned. The index must be >=0 and <contactcount in order to return valid values. The returned values are the position, the normalvector and the depth (distance) of the penetraction.
local2world (dgeom geom,float x,y,z)
  returns: (float x,y,z)
  transforms the given coordinates with the matrix of the geom, as if x,y,z are local coordinates of the geom and world coordinates are returned.
matrix (dgeom geom,[matrix16])
  returns: ([matrix16])
  sets/gets matrix of geom
maxcontactinfo (dgeom geom, [int])
  returns: ([int])
  sets/gets the maximum number of generated contact info. The contactinfo is a structure that stores the coordinates, the normal and the depth of a contact. This is normaly also stored in a contactjoint that is generated from a contact. However, if you want to create a geom that only works as a sensor for collision (i.e. if a door should open if someone stands in front of it), and turn nocontactgeneration on, you can retrieve contactinformation from such geoms.
maxcontacts (dgeom geom,[int])
  returns: ([int])
  sets/gets maximum number of contacts for this geom. If two geoms are tested for collision, multiple contacts can be generated for this case. If a geom has a limited number of possible contacts (set <=0 for deactivation of maximum), the minimum of maxcontacts of both geoms is chosen. Reducing the number of contacts max boost up the simulation, but can cause jittering of bodies, making autodisabling useless. Defaultvalue is 0 (no limit), but the general limit of contacts per geom is 128. The effect depends on the geom type. For example, two colliding spheres will never generate more than one contact, while two colliding boxes can generate not more than 4 contacts. Only if a geom collides with a complex trimesh, the limit can be exceeded.
motion1 (dgeom geom,[float])
  returns: ([float])
  sets/gets motion values of surface. This means that the contact will look like in motion for other objects that are in contact with this geom. Behavior is undefined if the fdirmixing is set to priority or average.
motion2 (dgeom geom,[float])
  returns: ([float])
  sets/gets motion values of surface. This means that the contact will look like in motion for other objects that are in contact with this geom. Behavior is undefined if the fdirmixing is set to priority or average.
nocontactgenerator (dgeom geom, [boolean])
  returns: ([boolean])
  sets/gets if contacts should be generated for this geom. You might want to deactivate contactgeneration for geoms that only should act as sensors in your physical environment.
pos (dgeom geom,[float x,y,z])
  returns: ([float x,y,z])
  sets/gets position of geom
rotaxis (dgeom geom,[float Xx,Xy,Xz, Yx,Yy,Yz, Zx,Zy,Zz]))
  returns: ([float Xx,Xy,Xz, Yx,Yy,Yz, Zx,Zy,Zz])
  returns or sets local rotation axis, make sure they make a orthogonal basis.
rotdeg (dgeom geom,[float x,y,z])
  returns: ([float x,y,z])
  sets/gets rotation of geom. The angles must be calculated from a matrix, so the results can differ from what you set. These matrix calculations are quite expensive, so use it with care. This function uses x,y,z as angles in degrees (180°==PI).
rotquat (dgeom geom,[float x,y,z,w])
  returns: ([float x,y,z,w])
  sets/gets rotation of geom as quaternion.
rotrad (dgeom geom,[float x,y,z])
  returns: ([float x,y,z])
  sets/gets rotation of geom. The angles must be calculated from a matrix, so the results can differ from what you set. These matrix calculations are quite expensive, so use it with care. This functions uses x,y,z as angles in radians (180°==PI)
setcategory (dgeom,int set {0,1})
  returns: ([int])
  sets/gets raw category bits as number
surfaceid (dgeom,[int])
  returns: ([int])
  sets/gets surfaceid of geom (0-255). If two geoms generate a contact, the surfaceproperties must be specified. These properties can be rather complicated and may depend from the type of the surface (rubber on glas won't slide, wood on glas slides, both slides on ice, but both don't slide at each other very well, etc.). In order to give you as much control as possible, yet keeping it as simple as possible, you can specify every surfacecombination that you wish by defining a list of contactparameters and defining the surface to be used by a combination of surfaceids.
test (dgeom,dgeom, [string whichresults])
  returns: (int count,[table pos, table normal, table depth, table geom, table tri])

  tests two geoms against each other and returns the number of contacts, the position coordinates as a floatarray (x,y,z,...), the normals as a floatarray, the depth as a floatarray (d1,d2,...), the contactgeoms as a table and triangle data as floatarry (index,u,v,...).

  The whichresults string describes which kind of results are returned. Each characterstands for a tableresult where the characters are:

  1. 'p': positional arrayinformation
  2. 'n': collision normals
  3. 'd': depth information
  4. 'g': geom information
  5. 't': triangle information
  If no string is passed, the returned values are as shown above, otherwise the appropriate arrays are returned in the given order specified by the passed string. If the string contains other characters, an error is thrown. Triangle information is only accurate when testing with rays and raytrisresult-enabled dgeomtrimeshes, else the triangle index is -1
testnear (dgeom a, dgeom b, int maxcount)
  returns: (int count,table geomi])
  tests two geoms if they are near each other (aaboxes overlap).
testtriarray (dgeom a, dgeom b, int maxcount)
  returns: (int count,table geomi,table tristart,table triall])
  tests two geoms for intersecting triangles. Only works if triarrayresult is activated for the included trimeshgeoms. Each collision pair results into trigeom/geom pair in geomi table. Associated with startindex/numberoftris pair tristart. Startindex maps as offset index into triall, which then has numberoftris*3 int indices.
transformer (dgeom)
  returns: ([dgeomtransform])
  returns the geomtransform that transforms the geom or returns nothing if the geom is not transformed. Note that you might get the 'final' geom in the transformhierarchy if you get a collision feedback, what may not be what you want / need.
world2local (dgeom geom,float x,y,z)
  returns: (float x,y,z)
  transforms the given coordinates from world coordinates into local coordinates of the geom.

## Inherited Methods: