collision Package¶
base
Module¶
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:
- geom: geometry object
- trimesh: triangular mesh
-
class
BasicShape
[source]¶ Bases:
ars.model.collision.base.Geom
Abstract class from whom every solid object’s shape derive
-
class
Box
(space, size)[source]¶ Bases:
ars.model.collision.base.BasicShape
Box shape, aligned along the X, Y and Z axii by default
-
class
Capsule
(space, length, radius)[source]¶ Bases:
ars.model.collision.base.BasicShape
Capsule shape, aligned along the Z-axis by default
-
class
ConstantHeightfieldTrimesh
(space, size_x, size_z, height)[source]¶ 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: - space (
Space
) – - size_x (positive int) – number of cells along the X axis
- size_z (positive int) – number of cells along the Z axis
- height (float) –
-
static
calc_vertices
(size_x, size_z, height=0.0)[source]¶ Return the vertices of a horizontal grid of
size_x
bysize_z
cells at a certainheight
.Parameters: - size_x (positive int) – number of cells along the X axis
- size_z (positive int) – number of cells along the Z axis
- height (float) –
>>> ConstantHeightfieldTrimesh.calc_vertices(2, 4) [(0, 0.0, 0), (0, 0.0, 1), (0, 0.0, 2), ..., (1, 0.0, 3)]
- space (
-
class
ContactGroup
[source]¶ 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.
-
inner_object
¶
-
-
class
Cylinder
(space, length, radius)[source]¶ Bases:
ars.model.collision.base.BasicShape
Cylinder shape, aligned along the Z-axis by default
-
class
Engine
[source]¶ Bases:
object
Collision engine abstract base class.
-
classmethod
are_geoms_connected
(geom1, geom2)[source]¶ Return whether
geom1
‘s body is connected togeom2
‘s body.The connection is checked as whether geoms bodies are connected through a joint or not.
Parameters: - geom1 (type of
Geom.inner_object
) – - geom2 (type of
Geom.inner_object
) –
Returns: True if geoms’ bodies are connected; False otherwise
Return type: bool
- geom1 (type of
-
classmethod
calc_collision
(geom1, geom2)[source]¶ Calculate information of the collision between these geoms.
Check if
geom1
andgeom2
actually collide and create a list of contact data objects if they do.Parameters: - geom1 (type of
Geom.inner_object
) – - geom2 (type of
Geom.inner_object
) –
Returns: contacts information
Return type: list of contact data objects
- geom1 (type of
-
classmethod
is_ray
(geom)[source]¶ 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 libraryReturn type: bool
-
classmethod
near_callback
(args, geom1, geom2)[source]¶ Handle possible collision between
geom1
andgeom2
.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()
orprocess_ray_collision_contacts()
, depending on whethergeom1
orgeom2
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 aSpace
subclass.Parameters: - args (
NearCallbackArgs
) – data structure wrapping the objects necessary to process the collision - geom1 (type of
Geom.inner_object
) – - geom2 (type of
Geom.inner_object
) –
- args (
-
classmethod
process_collision_contacts
(args, geom1, geom2, contacts)[source]¶ Process
contacts
of a collision betweengeom1
andgeom2
.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
norgeom2
can be rays. If one of them is, use methodprocess_ray_collision_contacts()
.Parameters: - args (
NearCallbackArgs
) – - geom1 (type of
Geom.inner_object
) – - geom2 (type of
Geom.inner_object
) – - contacts (list of contact data objects) – collision data returned by
calc_collision()
- args (
-
classmethod
process_ray_collision_contacts
(ray, other_geom, contacts)[source]¶ 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: - ray (type of
Ray.inner_object
) – - other_geom (type of
Geom.inner_object
) – - contacts (list of contact data objects) – collision data returned by
calc_collision()
- ray (type of
-
classmethod
-
class
Geom
[source]¶ 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_position
()[source]¶ Get the position of the geom.
Returns: position Return type: 3-sequence of floats
-
get_rotation
()[source]¶ Get the orientation of the geom.
Returns: rotation matrix Return type: 9-sequence of floats
-
inner_object
¶
-
-
class
HeightfieldTrimesh
(space, size_x, size_z, vertices)[source]¶ Bases:
ars.model.collision.base.Trimesh
-
static
calc_faces
(size_x, size_z)[source]¶ Return the faces for a horizontal grid of
size_x
bysize_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: - size_x (positive int) – number of cells along the X axis
- size_z (positive int) – number of cells along the Z axis
Returns: faces for a heightfield trimesh based in a horizontal grid of
size_x
bysize_z
cellsReturn 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)]
-
static
-
class
NearCallbackArgs
(world=None, contact_group=None, ignore_connected=True)[source]¶ Bases:
object
Data structure to save the args passed to
Engine.near_callback()
.All attributes are read-only (set at initialization).
Constructor.
Parameters: - world (
physics.base.World
) – - contact_group (
ContactGroup
) – - ignore_connected (bool) – whether to ignore collisions of geoms whose bodies are connected, or not
-
contact_group
¶
-
ignore_connected
¶
-
world
¶
- world (
-
class
Plane
(space, normal, dist)[source]¶ Bases:
ars.model.collision.base.BasicShape
Plane, different from a box
-
class
Ray
(space, length)[source]¶ 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)
-
get_closer_contact
()[source]¶ 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.
-
get_last_contact
()[source]¶ 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.
-
-
class
RayContactData
(ray=None, shape=None, pos=None, normal=None, depth=None)[source]¶ Bases:
object
Data structure to save the contact information of a collision between
ray
andshape
.All attributes are read-only (set at initialization).
Constructor.
Parameters: - ray (the type of
Ray
subclass’inner_object
) – - shape (the type of
Geom
subclass’inner_object
) – - pos (3-tuple of floats) – point at which the ray intersects the surface of the other shape/geom
- normal (3-tuple of floats) – vector normal to the surface of the other geom at the contact point
- depth (float) – distance from the origin of the ray to the contact point
-
depth
¶
-
normal
¶
-
position
¶
-
ray
¶
-
shape
¶
- ray (the type of
-
class
Space
[source]¶ 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:
__init__()
collide()
-
inner_object
¶
-
class
Sphere
(space, radius)[source]¶ Bases:
ars.model.collision.base.BasicShape
Spherical shape
-
class
Trimesh
(space, vertices, faces)[source]¶ 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
andfaces
, both list of 3-tuple numbers. However, each tuple invertices
designates a 3D point in space whereas each tuple infaces
is a group of indices referencing points invertices
.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”.-
static
swap_faces_indices
(faces)[source]¶ 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.
-
static
ode_adapter
Module¶
Classes and functions to interface with the collision library included in ODE.
-
class
Box
(space, size)[source]¶ Bases:
ars.model.collision.ode_adapter.BasicShape
,ars.model.collision.base.Box
Box shape, aligned along the X, Y and Z axii by default
-
class
Capsule
(space, length, radius)[source]¶ Bases:
ars.model.collision.ode_adapter.BasicShape
,ars.model.collision.base.Capsule
Capsule shape, aligned along the Z-axis by default
-
class
Cylinder
(space, length, radius)[source]¶ Bases:
ars.model.collision.ode_adapter.BasicShape
,ars.model.collision.base.Cylinder
Cylinder shape, aligned along the Z-axis by default
-
class
Engine
[source]¶ Bases:
ars.model.collision.base.Engine
Adapter to the ODE collision engine.
-
classmethod
are_geoms_connected
(geom1, geom2)[source]¶ (see parent method)
Parameters: - geom1 (
ode.GeomObject
) – - geom2 (
ode.GeomObject
) –
- geom1 (
-
classmethod
calc_collision
(geom1, geom2)[source]¶ Calculate information of the collision between these geoms.
Check if
geom1
andgeom2
actually collide and create a list of contact data objects if they do.Parameters: - geom1 (
ode.GeomObject
) – - geom2 (
ode.GeomObject
) –
Returns: contacts information
Return type: list of
ode.Contact
- geom1 (
-
classmethod
is_ray
(geom)[source]¶ Return whether
geom
is aode.GeomRay
object or not.Parameters: geom ( ode.GeomObject
) –Returns: True if geom
is an instance ofode.GeomRay
Return type: bool
-
classmethod
process_collision_contacts
(args, geom1, geom2, contacts)[source]¶ (see parent
base.Engine.process_collision_contacts()
)Parameters: - geom1 (
ode.GeomObject
) – - geom2 (
ode.GeomObject
) – - contacts (list of
ode.Contact
) –
- geom1 (
-
classmethod
process_ray_collision_contacts
(ray, other_geom, contacts)[source]¶ (see parent
base.Engine.process_ray_collision_contacts()
)Parameters: - ray (
ode.GeomRay
) – monkey-patched object whose attributeouter_object
references its wrapper (abase.Ray
object) - other_geom (
ode.GeomObject
) – - contacts (list of
ode.Contact
) –
- ray (
-
classmethod
-
class
Geom
[source]¶ Bases:
ars.model.collision.base.Geom
Abstract class, sort of equivalent to
ode.GeomObject
.-
get_position
()[source]¶ Get the position of the geom.
Returns: position Return type: 3-sequence of floats
-
get_rotation
()[source]¶ Get the orientation of the geom.
Returns: rotation matrix Return type: 9-sequence of floats
-
-
class
Plane
(space, normal, dist)[source]¶ Bases:
ars.model.collision.ode_adapter.BasicShape
,ars.model.collision.base.Plane
Plane, different from a box
-
class
Ray
(space, length)[source]¶ Bases:
ars.model.collision.ode_adapter.Geom
,ars.model.collision.base.Ray
-
class
Space
[source]¶ Bases:
ars.model.collision.base.Space
Adapter to
ode.SimpleSpace
.-
collide
(args, callback=None)[source]¶ Call
callback
withargs
for all potentially intersecting geom pairs.Function
callback
must accept 3 arguments:args, geom1, geom2
.Parameters: - args (
NearCallbackArgs
) – data object passed tocallback
in each call - callback (function or None) – a function with signature
args, geom1, geom2
- args (
-
-
class
Sphere
(space, radius)[source]¶ Bases:
ars.model.collision.ode_adapter.BasicShape
,ars.model.collision.base.Sphere
Spherical shape
-
class
Trimesh
(space, vertices, faces)[source]¶ Bases:
ars.model.collision.ode_adapter.Geom
,ars.model.collision.base.Trimesh
ode_objects_factories
Module¶
ODE objects factories i.e. functions that create ODE objects.
-
create_ode_box
(space, size)[source]¶ Create an ODE box geom.
Parameters: - space (
ode.Space
) – - size (3-sequence of floats) –
Returns: ODE box geom
Return type: ode.GeomBox
- space (
-
create_ode_capsule
(space, length, radius)[source]¶ Create an ODE capsule geom.
Note
In
GeomCCylinder
(same asGeomCapsule
) CCylinder means Capped Cylinder.Warning
ODE’s constructor parameter order is different:
radius
first and thenlength
.Parameters: - space (
ode.Space
) – - length (float) – of the cylindrical section i.e. caps are not included
- radius (float) –
Returns: ODE capsule geom
Return type: ode.GeomCCylinder
- space (
-
create_ode_cylinder
(space, length, radius)[source]¶ Create an ODE cylinder geom.
Warning
ODE’s constructor parameter order is different:
radius
first and thenlength
.Parameters: - space (
ode.Space
) – - length (float) –
- radius (float) –
Returns: ODE cylinder geom
Return type: ode.GeomCylinder
- space (
-
create_ode_hash_space
()[source]¶ Create a more sophisticated ODE geoms container (i.e. “space”).
Note
ode.HashSpace()
equalsode.Space(space_type=1)
.Returns: ODE hash space Return type: ode.HashSpace
-
create_ode_joint_group
()[source]¶ Create an ODE joint group.
Returns: ODE joint group Return type: ode.JointGroup
-
create_ode_plane
(space, normal, dist)[source]¶ 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: - space (
ode.Space
) – - normal (3-sequence of floats) – vector normal to the plane
- dist (float) – constant of the plane equation
Returns: ODE plane geom
Return type: ode.GeomPlane
- space (
-
create_ode_ray
(space, length)[source]¶ Create an ODE ray geom.
Parameters: - space (
ode.Space
) – - length (float) –
Returns: ODE ray geom
Return type: ode.GeomRay
- space (
-
create_ode_simple_space
()[source]¶ Create an ODE geoms container (i.e. “space”) of the simplest type.
Note
ode.SimpleSpace()
equalsode.Space(space_type=0)
.Returns: ODE simple space Return type: ode.SimpleSpace
signals
Module¶
This module contains string values defining different signals related to
the ars.model.collision
package.