This module defines the basic functionality for collision, as well as the base classes that compose an abstract interface to the library developers choose to use.
Both Space and Geom (parent class of Ray, Trimesh, Box, Sphere, Plane, etc) wrap the corresponding “native” object that the adapted library uses, assigned to private attribute _inner_object. To access (not set) it, these classes have public property inner_object.
This module also contains the auxiliary classes RayContactData and NearCallbackArgs.
The following are common abbreviations present both in code and documentation:
Bases: ars.model.collision.base.Geom
Abstract class from whom every solid object’s shape derive
Bases: ars.model.collision.base.BasicShape
Box shape, aligned along the X, Y and Z axii by default
Bases: ars.model.collision.base.BasicShape
Capsule shape, aligned along the Z-axis by default
Bases: ars.model.collision.base.BasicShape
Cone
Bases: ars.model.collision.base.HeightfieldTrimesh
A trimesh that is a heightfield at constant level.
Note
More than anything, this geom is for demonstration purposes, because it could be easily replaced with a Plane.
Constructor.
Parameters: |
|
---|
Return the vertices of a horizontal grid of size_x by size_z cells at a certain height.
Parameters: |
|
---|
>>> ConstantHeightfieldTrimesh.calc_vertices(2, 4)
[(0, 0.0, 0), (0, 0.0, 1), (0, 0.0, 2), ..., (1, 0.0, 3)]
Bases: object
Wrapper around a collection-like class storing contact data instances.
What these instances are (attributes, behavior) is up to the implementation of the adpater.
Bases: ars.model.collision.base.BasicShape
Cylinder shape, aligned along the Z-axis by default
Bases: object
Collision engine abstract base class.
Return whether geom1‘s body is connected to geom2‘s body.
The connection is checked as whether geoms bodies are connected through a joint or not.
Parameters: |
|
---|---|
Returns: | True if geoms’ bodies are connected; False otherwise |
Return type: | bool |
Calculate information of the collision between these geoms.
Check if geom1 and geom2 actually collide and create a list of contact data objects if they do.
Parameters: |
|
---|---|
Returns: | contacts information |
Return type: | list of contact data objects |
Return whether geom is a ray-like object or not.
Parameters: | geom (type of Geom.inner_object) – |
---|---|
Returns: | True if geom is an instance of the class representing a ray in the adapted library |
Return type: | bool |
Handle possible collision between geom1 and geom2.
The responsible for determining if there is an actual collision is calc_collision(), which will return a list of contact data objects.
That information is passed to either process_collision_contacts() or process_ray_collision_contacts(), depending on whether geom1 or geom2 is a ray or not. It’s an unhandled case that both geoms were rays.
This function is usually the callback function for Space.collide(), although it will probably be handed over to the inner object of a Space subclass.
Parameters: |
|
---|
Process contacts of a collision between geom1 and geom2.
This method should create movement constraints for the bodies attached to the geoms. This is necessary for the simulation to prevent bodies’ volumes from penetrating each other, making them really collide (i.e. exert mutually opposing forces).
Warning
Neither geom1 nor geom2 can be rays. If one of them is, use method process_ray_collision_contacts().
Parameters: |
|
---|
Process special case of collision between a ray and a regular geom.
See also
For regular geoms collision, see process_collision_contacts().
Since rays have no attached body, they can’t “really” collide with other geoms. However, they do intersect, which is of interest to non-physical aspects of the simulation. A common use case is that of laser distance sensors.
Warning
Collision between two rays is a singularity and should never happen.
Parameters: |
|
---|
Bases: object
Geometry object encapsulation.
This class wraps the corresponding “native” object the adapted-to library (e.g. ODE) uses, assigned to _inner_object.
Subclasses must implement these methods:
Get the position of the geom.
Returns: | position |
---|---|
Return type: | 3-sequence of floats |
Get the orientation of the geom.
Returns: | rotation matrix |
---|---|
Return type: | 9-sequence of floats |
Bases: ars.model.collision.base.Trimesh
Return the faces for a horizontal grid of size_x by size_z cells.
Faces are triangular, so each is composed by 3 vertices. Consequently, each returned face is a length-3 sequence of the vertex indices.
Parameters: |
|
---|---|
Returns: | faces for a heightfield trimesh based in a horizontal grid of size_x by size_z cells |
Return type: | list of 3-tuple of ints |
>>> HeightfieldTrimesh.calc_faces(2, 4)
[(0, 1, 4), (1, 5, 4), (1, 6, 5), (1, 2, 6), (2, 3, 6), (3, 7, 6)]
Bases: object
Data structure to save the args passed to Engine.near_callback().
All attributes are read-only (set at initialization).
Constructor.
Parameters: |
|
---|
Bases: ars.model.collision.base.BasicShape
Plane, different from a box
Bases: ars.model.collision.base.Geom
Ray aligned along the Z-axis by default. “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.” (ODE Wiki Manual)
Return the contact object corresponding to the collision closest to the ray’s origin.
It may or may not be the same object returned by get_last_contact.
Return the contact object corresponding to the last collision of the ray with another geom. Note than in each simulation step, several collisions may occur, one for each intersection geom (in ODE). The object returned may or may not be the same returned by get_closer_contact.
Bases: object
Data structure to save the contact information of a collision between ray and shape.
All attributes are read-only (set at initialization).
Constructor.
Parameters: |
|
---|
Bases: object
Collision space abstract base class.
This class wraps the corresponding “native” object the adapted-to library (e.g. ODE) uses, assigned to _inner_object.
Subclasses must implement these methods:
Bases: ars.model.collision.base.BasicShape
Spherical shape
Bases: ars.model.collision.base.Geom
A triangular mesh i.e. a surface composed of triangular faces.
Note
Note that a trimesh need not be closed. For example, it could be used to model the ground surface.
Its geometry is defined by two attributes: vertices and faces, both list of 3-tuple numbers. However, each tuple in vertices designates a 3D point in space whereas each tuple in faces is a group of indices referencing points in vertices.
Warning
The order of vertices indices for each face does matter.
Example:
vertices = [(0, 0.0, 0), (0, 0.0, 1), (0, 0.0, 2), (0, 0.0, 3),
(1, 0.0, 0), (1, 0.0, 1), (1, 0.0, 2), (1, 0.0, 3)]
faces = [(0, 1, 4), (1, 5, 4), (1, 6, 5),
(1, 2, 6), (2, 3, 6), (3, 7, 6)]
The, the first face is defined by points: (0, 0.0, 0), (0, 0.0, 1), (1, 0.0, 0). With that order, the normal to the face is (0, 1.0, 0) i.e. the Y axis. The rationale to determining the inwards and outwards directions follows the well-known “right hand rule”.
Faces had to change their indices to work with ODE. With the initial get_faces, the normal to the triangle defined by the 3 vertices pointed (following the right-hand rule) downwards. Swapping the third with the first index, now the triangle normal pointed upwards.
Classes and functions to interface with the collision library included in ODE.
Bases: ars.model.collision.ode_adapter.BasicShape, ars.model.collision.base.Box
Box shape, aligned along the X, Y and Z axii by default
Bases: ars.model.collision.ode_adapter.BasicShape, ars.model.collision.base.Capsule
Capsule shape, aligned along the Z-axis by default
Bases: ars.model.collision.ode_adapter.BasicShape, ars.model.collision.base.Cylinder
Cylinder shape, aligned along the Z-axis by default
Bases: ars.model.collision.base.Engine
Adapter to the ODE collision engine.
(see parent method)
Parameters: |
|
---|
Calculate information of the collision between these geoms.
Check if geom1 and geom2 actually collide and create a list of contact data objects if they do.
Parameters: |
|
---|---|
Returns: | contacts information |
Return type: | list of ode.Contact |
Return whether geom is a ode.GeomRay object or not.
Parameters: | geom (ode.GeomObject) – |
---|---|
Returns: | True if geom is an instance of ode.GeomRay |
Return type: | bool |
(see parent base.Engine.process_collision_contacts())
Parameters: |
|
---|
(see parent base.Engine.process_ray_collision_contacts())
Parameters: |
|
---|
Bases: ars.model.collision.base.Geom
Abstract class, sort of equivalent to ode.GeomObject.
Get the position of the geom.
Returns: | position |
---|---|
Return type: | 3-sequence of floats |
Get the orientation of the geom.
Returns: | rotation matrix |
---|---|
Return type: | 9-sequence of floats |
Bases: ars.model.collision.ode_adapter.BasicShape, ars.model.collision.base.Plane
Plane, different from a box
Bases: ars.model.collision.ode_adapter.Geom, ars.model.collision.base.Ray
Bases: ars.model.collision.base.Space
Adapter to ode.SimpleSpace.
Call callback with args for all potentially intersecting geom pairs.
Function callback must accept 3 arguments: args, geom1, geom2.
Parameters: |
|
---|
Bases: ars.model.collision.ode_adapter.BasicShape, ars.model.collision.base.Sphere
Spherical shape
Bases: ars.model.collision.ode_adapter.Geom, ars.model.collision.base.Trimesh
ODE objects factories i.e. functions that create ODE objects.
Create an ODE box geom.
Parameters: |
|
---|---|
Returns: | ODE box geom |
Return type: | ode.GeomBox |
Create an ODE capsule geom.
Note
In GeomCCylinder (same as GeomCapsule) CCylinder means Capped Cylinder.
Warning
ODE’s constructor parameter order is different: radius first and then length.
Parameters: |
|
---|---|
Returns: | ODE capsule geom |
Return type: | ode.GeomCCylinder |
Create an ODE cylinder geom.
Warning
ODE’s constructor parameter order is different: radius first and then length.
Parameters: |
|
---|---|
Returns: | ODE cylinder geom |
Return type: | ode.GeomCylinder |
Create a more sophisticated ODE geoms container (i.e. “space”).
Note
ode.HashSpace() equals ode.Space(space_type=1).
Returns: | ODE hash space |
---|---|
Return type: | ode.HashSpace |
Create an ODE joint group.
Returns: | ODE joint group |
---|---|
Return type: | ode.JointGroup |
Create an ODE plane (infinite) geom.
The plane equation is
where normal = (n0, n1, n2).
Warning
This object can’t be attached to a body.
Parameters: |
|
---|---|
Returns: | ODE plane geom |
Return type: | ode.GeomPlane |
Create an ODE ray geom.
Parameters: |
|
---|---|
Returns: | ODE ray geom |
Return type: | ode.GeomRay |
Create an ODE geoms container (i.e. “space”) of the simplest type.
Note
ode.SimpleSpace() equals ode.Space(space_type=0).
Returns: | ODE simple space |
---|---|
Return type: | ode.SimpleSpace |
This module contains string values defining different signals related to the ars.model.collision package.