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 Cone[source]¶: Bases: ars.model.collision.base.BasicShape

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 by size_z cells at a certain height.

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)]

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.

empty()[source]¶: Remove all the stored contact data instances.

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 to geom2‘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

classmethod calc_collision(geom1, geom2)[source]¶

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:	geom1 (type of `Geom.inner_object`) – geom2 (type of `Geom.inner_object`) –
Returns:	contacts information
Return type:	list of contact data objects

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 library
Return type:	bool

classmethod near_callback(args, geom1, geom2)[source]¶

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:	args (`NearCallbackArgs`) – data structure wrapping the objects necessary to process the collision geom1 (type of `Geom.inner_object`) – geom2 (type of `Geom.inner_object`) –

classmethod process_collision_contacts(args, geom1, geom2, contacts)[source]¶

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:	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()`

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()`

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:

__init__()
attach_body()
get_position(), set_position()
get_rotation(), set_rotation()

attach_body(body)[source]¶

get_attached_body()[source]¶

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¶

set_position(pos)[source]¶

Set the position of the geom.

Parameters:	pos (3-sequence of floats) – position

set_rotation(rot)[source]¶

Set the orientation of the geom.

Parameters:	rot (9-sequence of floats) – rotation matrix

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 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:	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` 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)]

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¶

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)

clear_closer_contact()[source]¶

clear_contacts()[source]¶

clear_last_contact()[source]¶

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.

get_length()[source]¶

set_last_contact(last_contact)[source]¶: Set the contact data of ray’s last collision. It also checks if last_contact is closer than the previously existing one. The result can be obtained with the get_closer_contact method.

set_length(length)[source]¶

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 and shape.

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¶

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()

collide(args, callback)[source]¶

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 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”.

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.

`ode_adapter` Module¶

Classes and functions to interface with the collision library included in ODE.

class BasicShape[source]¶: Bases: ars.model.collision.ode_adapter.Geom

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 ContactGroup[source]¶

Bases: ars.model.collision.base.ContactGroup

empty()[source]¶

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`) –

classmethod calc_collision(geom1, geom2)[source]¶

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:	geom1 (`ode.GeomObject`) – geom2 (`ode.GeomObject`) –
Returns:	contacts information
Return type:	list of `ode.Contact`

classmethod is_ray(geom)[source]¶

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

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`) –

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 attribute `outer_object` references its wrapper (a `base.Ray` object) other_geom (`ode.GeomObject`) – contacts (list of `ode.Contact`) –

class Geom[source]¶

Bases: ars.model.collision.base.Geom

Abstract class, sort of equivalent to ode.GeomObject.

attach_body(body)[source]¶

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

set_position(pos)[source]¶

Set the position of the geom.

Parameters:	pos (3-sequence of floats) – position

set_rotation(rot)[source]¶

Set the orientation of the geom.

Parameters:	rot (9-sequence of floats) – rotation matrix

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

get_length()[source]¶

set_length(length)[source]¶

class Space[source]¶

Bases: ars.model.collision.base.Space

Adapter to ode.SimpleSpace.

collide(args, callback=None)[source]¶

Call callback with args for all potentially intersecting geom pairs.

Function callback must accept 3 arguments: args, geom1, geom2.

Parameters:	args (`NearCallbackArgs`) – data object passed to `callback` in each call callback (function or None) – a function with signature `args, geom1, geom2`

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`

create_ode_capsule(space, length, radius)[source]¶

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:	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`

create_ode_cylinder(space, length, radius)[source]¶

Create an ODE cylinder geom.

Warning

ODE’s constructor parameter order is different: radius first and then length.

Parameters:	space (`ode.Space`) – length (float) – radius (float) –
Returns:	ODE cylinder geom
Return type:	`ode.GeomCylinder`

create_ode_hash_space()[source]¶

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_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

$n_0 \cdot x + n_1 \cdot y + n_2 \cdot z = dist$

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`

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`

create_ode_simple_space()[source]¶

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`

create_ode_sphere(space, radius)[source]¶

Create an ODE sphere geom.

Parameters:	space (`ode.Space`) – radius (float) –
Returns:	ODE sphere geom
Return type:	`ode.GeomSphere`

create_ode_trimesh(space, vertices, faces)[source]¶

Create an ODE trimesh geom.

Parameters:	space (`ode.Space`) – vertices (sequence of 3-sequences of floats) – faces (sequence of 3-sequences of ints) –
Returns:	ODE trimesh geom
Return type:	`ode.GeomTriMesh`

`signals` Module¶

This module contains string values defining different signals related to the ars.model.collision package.

collision Package¶

base Module¶

ode_adapter Module¶

ode_objects_factories Module¶

signals Module¶

`base` Module¶

`ode_adapter` Module¶

`ode_objects_factories` Module¶

`signals` Module¶