ARS: Python robotics simulator¶

pydispatch Package¶

Multi-consumer multi-producer dispatching mechanism

dispatcher Module¶

Multiple-producer-multiple-consumer signal-dispatching

dispatcher is the core of the PyDispatcher system, providing the primary API and the core logic for the system.

Module attributes of note:

Any – Singleton used to signal either “Any Sender” or

“Any Signal”. See documentation of the _Any class.

Anonymous – Singleton used to signal “Anonymous Sender”

See documentation of the _Anonymous class.

Internal attributes:

WEAKREF_TYPES – tuple of types/classes which represent

weak references to receivers, and thus must be de- referenced on retrieval to retrieve the callable object

connections – { senderkey (id) : { signal : [receivers...]}}

senders – { senderkey (id) : weakref(sender) }

used for cleaning up sender references on sender deletion

sendersBack – { receiverkey (id) : [senderkey (id)...] }

used for cleaning up receiver references on receiver deletion, (considerably speeds up the cleanup process vs. the original code.)

connect(receiver, signal=_Any, sender=_Any, weak=True)[source]¶

Connect receiver to sender for signal

receiver – a callable Python object which is to receive

messages/signals/events. Receivers must be hashable objects.

if weak is True, then receiver must be weak-referencable (more precisely saferef.safeRef() must be able to create a reference to the receiver).

Receivers are fairly flexible in their specification, as the machinery in the robustApply module takes care of most of the details regarding figuring out appropriate subsets of the sent arguments to apply to a given receiver.

Note:

if receiver is itself a weak reference (a callable), it will be de-referenced by the system’s machinery, so generally weak references are not suitable as receivers, though some use might be found for the facility whereby a higher-level library passes in pre-weakrefed receiver references.

signal – the signal to which the receiver should respond

if Any, receiver will receive any signal from the indicated sender (which might also be Any, but is not necessarily Any).

Otherwise must be a hashable Python object other than None (DispatcherError raised on None).

sender – the sender to which the receiver should respond

if Any, receiver will receive the indicated signals from any sender.

if Anonymous, receiver will only receive indicated signals from send/sendExact which do not specify a sender, or specify Anonymous explicitly as the sender.

Otherwise can be any python object.

weak – whether to use weak references to the receiver

By default, the module will attempt to use weak references to the receiver objects. If this parameter is false, then strong references will be used.

returns None, may raise DispatcherTypeError

disconnect(receiver, signal=_Any, sender=_Any, weak=True)[source]¶

Disconnect receiver from sender for signal

receiver – the registered receiver to disconnect signal – the registered signal to disconnect sender – the registered sender to disconnect weak – the weakref state to disconnect

disconnect reverses the process of connect, the semantics for the individual elements are logically equivalent to a tuple of (receiver, signal, sender, weak) used as a key to be deleted from the internal routing tables. (The actual process is slightly more complex but the semantics are basically the same).

Note:

Using disconnect is not required to cleanup routing when an object is deleted, the framework will remove routes for deleted objects automatically. It’s only necessary to disconnect if you want to stop routing to a live object.

returns None, may raise DispatcherTypeError or

DispatcherKeyError

getAllReceivers(sender=_Any, signal=_Any)[source]¶

Get list of all receivers from global tables

This gets all receivers which should receive the given signal from sender, each receiver should be produced only once by the resulting generator

getReceivers(sender=_Any, signal=_Any)[source]¶

Get list of receivers from global tables

This utility function allows you to retrieve the raw list of receivers from the connections table for the given sender and signal pair.

Note:

there is no guarantee that this is the actual list stored in the connections table, so the value should be treated as a simple iterable/truth value rather than, for instance a list to which you might append new records.

Normally you would use liveReceivers( getReceivers( ...)) to retrieve the actual receiver objects as an iterable object.

liveReceivers(receivers)[source]¶

Filter sequence of receivers to get resolved, live receivers

This is a generator which will iterate over the passed sequence, checking for weak references and resolving them, then returning all live receivers.

send(signal=_Any, sender=_Anonymous, *arguments, **named)[source]¶

Send signal from sender to all connected receivers.

signal – (hashable) signal value, see connect for details

sender – the sender of the signal

if Any, only receivers registered for Any will receive the message.

if Anonymous, only receivers registered to receive messages from Anonymous or Any will receive the message

Otherwise can be any python object (normally one registered with a connect if you actually want something to occur).

arguments – positional arguments which will be passed to

all receivers. Note that this may raise TypeErrors if the receivers do not allow the particular arguments. Note also that arguments are applied before named arguments, so they should be used with care.

named – named arguments which will be filtered according

to the parameters of the receivers to only provide those acceptable to the receiver.

Return a list of tuple pairs [(receiver, response), ... ]

if any receiver raises an error, the error propagates back through send, terminating the dispatch loop, so it is quite possible to not have all receivers called if a raises an error.

sendExact(signal=_Any, sender=_Anonymous, *arguments, **named)[source]¶

Send signal only to those receivers registered for exact message

sendExact allows for avoiding Any/Anonymous registered handlers, sending only to those receivers explicitly registered for a particular signal on a particular sender.

errors Module¶

Error types for dispatcher mechanism

exception DispatcherError[source]¶

Bases: exceptions.Exception

Base class for all Dispatcher errors

exception DispatcherKeyError[source]¶

Bases: exceptions.KeyError, ars.lib.pydispatch.errors.DispatcherError

Error raised when unknown (sender,signal) set specified

exception DispatcherTypeError[source]¶

Bases: exceptions.TypeError, ars.lib.pydispatch.errors.DispatcherError

Error raised when inappropriate signal-type specified (None)

robust Module¶

Module implementing error-catching version of send (sendRobust)

sendRobust(signal=_Any, sender=_Anonymous, *arguments, **named)[source]¶

Send signal from sender to all connected receivers catching errors

signal – (hashable) signal value, see connect for details

sender – the sender of the signal

if Any, only receivers registered for Any will receive the message.

if Anonymous, only receivers registered to receive messages from Anonymous or Any will receive the message

Otherwise can be any python object (normally one registered with a connect if you actually want something to occur).

arguments – positional arguments which will be passed to

all receivers. Note that this may raise TypeErrors if the receivers do not allow the particular arguments. Note also that arguments are applied before named arguments, so they should be used with care.

named – named arguments which will be filtered according

to the parameters of the receivers to only provide those acceptable to the receiver.

Return a list of tuple pairs [(receiver, response), ... ]

if any receiver raises an error (specifically any subclass of Exception), the error instance is returned as the result for that receiver.

robustapply Module¶

Robust apply mechanism

Provides a function “call”, which can sort out what arguments a given callable object can take, and subset the given arguments to match only those which are acceptable.

function(receiver)[source]¶

Get function-like callable object for given receiver

returns (function_or_method, codeObject, fromMethod)

If fromMethod is true, then the callable already has its first argument bound

robustApply(receiver, *arguments, **named)[source]¶

Call receiver with arguments and an appropriate subset of named

saferef Module¶

Refactored “safe reference” from dispatcher.py

class BoundMethodWeakref(target, onDelete=None)[source]¶

Bases: object

‘Safe’ and reusable weak references to instance methods

BoundMethodWeakref objects provide a mechanism for referencing a bound method without requiring that the method object itself (which is normally a transient object) is kept alive. Instead, the BoundMethodWeakref object keeps weak references to both the object and the function which together define the instance method.

Attributes:

key – the identity key for the reference, calculated

by the class’s calculateKey method applied to the target instance method

deletionMethods – sequence of callable objects taking

single argument, a reference to this object which will be called when either the target object or target function is garbage collected (i.e. when this object becomes invalid). These are specified as the onDelete parameters of safeRef calls.

weakSelf – weak reference to the target object

weakFunc – weak reference to the target function

Class Attributes:

_allInstances – class attribute pointing to all live

BoundMethodWeakref objects indexed by the class’s calculateKey(target) method applied to the target objects. This weak value dictionary is used to short-circuit creation so that multiple references to the same (object, function) pair produce the same BoundMethodWeakref instance.

Return a weak-reference-like instance for a bound method

target – the instance-method target for the weak

reference, must have <im_self> and <im_func> attributes and be reconstructable via:

target.<im_func>.__get__( target.<im_self> )

which is true of built-in instance methods.

onDelete – optional callback which will be called

when this weak reference ceases to be valid (i.e. either the object or the function is garbage collected). Should take a single argument, which will be passed a pointer to this object.

classmethod calculateKey(target)[source]¶

Calculate the reference key for this reference

Currently this is a two-tuple of the id()’s of the target object and the target function respectively.

safeRef(target, onDelete=None)[source]¶

Return a safe weak reference to a callable target

target – the object to be weakly referenced, if it’s a

bound method reference, will create a BoundMethodWeakref, otherwise creates a simple weakref.

onDelete – if provided, will have a hard reference stored

to the callable to be called after the safe reference goes out of scope with the reference object, (either a weakref or a BoundMethodWeakref) as argument.

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

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.

contrib Package¶

Container for contributed modules or packages that could be helpful for other ARS users (other than its own developers, which are encouraged to improve their contributions and spread the word about them).

Later on, the most popular and stable parts of the code should be integrated in the official package.

geometry Package¶

base Module¶

class Body(mass=None, density=None, pos=None, rot=None, *args, **kwargs)[source]¶

Bases: object

attach_geom(geom)[source]¶

calc_potential_energy(gravity)[source]¶

Calculate the potential energy of the body due to its position (x) and the gravitational acceleration (g).

Parameters:	gravity (tuple of 3 floats) – gravitational acceleration vector
Returns:	potential energy
Return type:	float

calc_rotation_kinetic_energy()[source]¶

Calculate the kinetic energy of the body due to rotational movement.

Returns:	kinetic energy
Return type:	float

calc_translation_kinetic_energy()[source]¶

Calculate the kinetic energy of the body due to translational movement.

Returns:	kinetic energy
Return type:	float

get_angular_velocity()[source]¶

get_attached_geom()[source]¶

get_center_of_gravity()[source]¶

get_inertia_tensor()[source]¶

get_linear_velocity()[source]¶

get_mass()[source]¶

get_position()[source]¶

Get the position of the body.

Returns:	position
Return type:	3-sequence of floats

get_rotation()[source]¶

Get the orientation of the body.

Returns:	rotation matrix
Return type:	9-sequence of floats

get_saved_velocities()[source]¶

Return last saved velocities (linear and angular).

inner_object¶

save_velocities()[source]¶

Retrieve the actual velocities (linear and angular) of the body and save them.

set_position(pos)[source]¶

Set the position of the body.

Sends signals.BODY_PRE_SET_POSITION and signals.BODY_POST_SET_POSITION.

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

set_rotation(rot)[source]¶

Set the orientation of the body.

Sends signals.BODY_PRE_SET_ROTATION and signals.BODY_POST_SET_ROTATION.

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

class Box(size, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.Body

size¶

class Capsule(length, radius, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.Body

length¶

radius¶

class Cone(height, radius, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.Body

height¶

radius¶

class Cylinder(length, radius, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.Body

length¶

radius¶

class Engine[source]¶

Bases: object

world_class = None¶

class Sphere(radius, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.Body

radius¶

class World(gravity, *args, **kwargs)[source]¶

Bases: object

gravity¶

inner_object¶

step(time_step)[source]¶

Subclasses implementing this method must send the corresponding signals, defined in ars.model.physics.signals.

ode_adapter Module¶

Classes and functions to interface the ODE physics engine with the API defined in physics.

class Body(world, space, mass=None, density=None, *args, **kwargs)[source]¶

Bases: object

Abstract class, sort of equivalent to ode.Body.

Constructor.

Parameters:	world (base.World) – space (collision.base.Space) – mass (float or None) – density (float or None) –

get_angular_velocity()[source]¶

get_center_of_gravity()[source]¶

get_inertia_tensor()[source]¶

get_linear_velocity()[source]¶

get_mass()[source]¶

get_position()[source]¶

Get the position of the body.

Returns:	position
Return type:	3-sequence of floats

get_rotation()[source]¶

Get the orientation of the body.

Returns:	rotation matrix
Return type:	9-sequence of floats

set_position(pos)[source]¶

Set the position of the body.

Sends signals.BODY_PRE_SET_POSITION and signals.BODY_POST_SET_POSITION.

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

set_rotation(rot)[source]¶

Set the orientation of the body.

Sends signals.BODY_PRE_SET_ROTATION and signals.BODY_POST_SET_ROTATION.

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

class Box(world, space, size, mass=None, density=None)[source]¶

Bases: ars.model.physics.ode_adapter.Body, ars.model.physics.base.Box

class Capsule(world, space, length, radius, mass=None, density=None)[source]¶

Bases: ars.model.physics.ode_adapter.Body, ars.model.physics.base.Capsule

create capsule body (aligned along the z-axis so that it matches the Geom created below, which is aligned along the Z-axis by default)

class Cylinder(world, space, length, radius, mass=None, density=None)[source]¶

Bases: ars.model.physics.ode_adapter.Body, ars.model.physics.base.Cylinder

create cylinder body (aligned along the z-axis so that it matches the Geom created below, which is aligned along the Z-axis by default)

class Engine[source]¶

Bases: ars.model.physics.base.Engine

Adapter to the ODE physics engine

world_class¶

alias of World

class Sphere(world, space, radius, mass=None, density=None)[source]¶

Bases: ars.model.physics.ode_adapter.Body, ars.model.physics.base.Sphere

class World(gravity=(0.0, -9.81, 0.0), ERP=0.2, CFM=1e-10, *args, **kwargs)[source]¶

Bases: ars.model.physics.base.World

Adapter to ode.World.

See also

Read abouth ERP and CFM in ODE’s wiki http://ode-wiki.org/wiki/index.php?title=Manual:_Concepts

Constructor.

Parameters:	gravity (3-sequence of floats) – gravity acceleration vector ERP (float) – Error Reduction Parameter CFM (float) – Constraint Force Mixing

gravity¶

step(time_step)[source]¶

ode_objects_factories Module¶

ODE objects factories i.e. functions that create ODE objects.

create_ode_box(world, size, mass=None, density=None)[source]¶

Create an ODE body with box-like mass parameters.

Parameters:	world (ode.World) – size (3-sequence of floats) – mass (float or None) – density (float or None) –
Returns:	box body
Return type:	ode.Body

create_ode_capsule(world, length, radius, mass=None, density=None)[source]¶

Create an ODE body with capsule-like mass parameters.

Parameters:	world (ode.World) – length (float) – radius (float) – mass (float or None) – density (float or None) –
Returns:	capsule body
Return type:	ode.Body

create_ode_cylinder(world, length, radius, mass=None, density=None)[source]¶

Create an ODE body with cylinder-like mass parameters.

Parameters:	world (ode.World) – length (float) – radius (float) – mass (float or None) – density (float or None) –
Returns:	cylinder body
Return type:	ode.Body

create_ode_sphere(world, radius, mass=None, density=None)[source]¶

Create an ODE body with sphere-like mass parameters.

Parameters:	world (ode.World) – radius (float) – mass (float or None) – density (float or None) –
Returns:	sphere body
Return type:	ode.Body

create_ode_world(gravity=(0.0, -9.81, 0.0), ERP=0.8, CFM=1e-10)[source]¶

Create an ODE world object.

Parameters:	gravity (3-sequence of floats) – gravity acceleration vector ERP (float) – Error Reduction Parameter CFM (float) – Constraint Force Mixing
Returns:	world
Return type:	ode.World

signals Module¶

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

joints Module¶

Module of all the classes related to physical joints. These are objects that link 2 bodies together.

There are two base abstract classes for all joints: Joint and ActuatedJoint. They are not coupled (at all) with ODE or any other physics or collision library/engine.

The classes that implement at least one of those interfaces are these:

• Fixed
• Rotary
• Universal
• BallSocket
• Slider

There is also an auxiliary class: JointFeedback.

class ActuatedJoint(world, inner_joint, body1=None, body2=None)[source]¶

Bases: ars.model.robot.joints.Joint

A joint with an actuator that can exert force and/or torque to connected bodies.

This is an abstract class.

Constructor.

Parameters:	world (physics.base.World) – inner_joint (ode.Joint) – body1 (physics.base.Body) – body2 (physics.base.Body) –

class BallSocket(world, body1, body2, anchor)[source]¶

Bases: ars.model.robot.joints.Joint

Constructor.

Parameters:	world (physics.base.World) – body1 (physics.base.Body) – body2 (physics.base.Body) – anchor (3-tuple of floats) – joint anchor point

class Fixed(world, body1, body2)[source]¶

Bases: ars.model.robot.joints.Joint

Constructor.

Parameters:	world (physics.base.World) – body1 (physics.base.Body) – body2 (physics.base.Body) –

class Joint(world, inner_joint, body1=None, body2=None)[source]¶

Bases: object

Entity that links 2 bodies together, enforcing one or more movement constraints.

This is an abstract class.

Constructor.

Parameters:	world (physics.base.World) – inner_joint (ode.Joint) – body1 (physics.base.Body) – body2 (physics.base.Body) –

body1¶

body2¶

class JointFeedback(body1, body2, force1=None, force2=None, torque1=None, torque2=None)[source]¶

Bases: object

Data structure to hold the forces and torques resulting from the interaction of 2 bodies through a joint.

All attributes are private. The results (force1, force2, torque1, torque2) are all length-3 tuples of floats.

Constructor.

Parameters:	body1 (physics.base.Body) – body2 (physics.base.Body) – force1 (3-tuple of floats) – force2 (3-tuple of floats) – torque1 (3-tuple of floats) – torque2 (3-tuple of floats) –

body1¶

body2¶

force1¶

force2¶

torque1¶

torque2¶

class Rotary(world, body1, body2, anchor, axis)[source]¶

Bases: ars.model.robot.joints.ActuatedJoint

Constructor.

Parameters:	world (physics.base.World) – body1 (physics.base.Body) – body2 (physics.base.Body) – anchor (3-tuple of floats) – joint anchor point axis (3-tuple of floats) – rotation axis

add_torque(torque)[source]¶

Apply torque about the rotation axis.

Parameters:	torque (float) – magnitude

angle¶

Return the angle between the two bodies.

The zero angle is determined by the position of the bodies when joint’s anchor was set.

Returns:	value ranging -pi and +pi
Return type:	float

angle_rate¶

Return the rate of change of the angle between the two bodies.

Returns:	angle rate
Return type:	float

set_speed(speed, max_force=None)[source]¶

Set rotation speed to speed.

The joint will set that speed by applying a force up to max_force, so it is not guaranteed that speed will be reached.

Parameters:	speed (float) – speed to set max_force (float or None) – if not None, the maximum force the joint can apply when trying to set the rotation speed

class Slider(world, body1, body2, axis)[source]¶

Bases: ars.model.robot.joints.ActuatedJoint

Joint with one DOF that constrains two objects to line up along an axis.

It is different from a Piston joint (which has two DOF) in that the Slider does not allow rotation.

Constructor.

Parameters:	world (physics.base.World) – body1 (physics.base.Body) – body2 (physics.base.Body) – axis (3-tuple of floats) – rotation axis

add_force(force)[source]¶

Apply a force of magnitude force along the joint’s axis.

position¶

Return position of the joint with respect to its initial position.

The zero position is established when the joint’s axis is set.

Return type:	float

position_rate¶

Return position’s time derivative, i.e. “speed”.

Return type:	float

class Universal(world, body1, body2, anchor, axis1, axis2)[source]¶

Bases: ars.model.robot.joints.Joint

Constructor.

Parameters:	world (physics.base.World) – body1 (physics.base.Body) – body2 (physics.base.Body) – anchor (3-tuple of floats) – joint anchor point axis1 (3-tuple of floats) – first universal axis axis2 (3-tuple of floats) – second universal axis

sensors Module¶

Module of all the classes related to sensors.

There are base classes for sensors whose source is a body, joint or simulation. It also considers those which read information automatically by subscribing to certain signals.

Some abstract classes are:

• BaseSourceSensor
• BaseSignalSensor
• BodySensor
• JointSensor
• SimulationSensor

Some practical sensors are:

• RotaryJointSensor, JointTorque
• Laser
• GPS, Velometer, Accelerometer, Inclinometer
• KineticEnergy, PotentialEnergy, TotalEnergy, SystemTotalEnergy

It also contains the auxiliary classes SensorData and SensorDataQueue.

class Accelerometer(body, time_step)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Calculate and retrieve a body’s linear and angular acceleration.

Warning

The provided time_step is used to calculate the acceleration based on the velocity measured at two instants in time. If subsequent calls to on_change are separated by a simulation time period different to the given time_step, the results will be invalid.

class ActuatedJointSensor(joint)[source]¶

Bases: ars.model.robot.sensors.JointSensor

Sensor whose source of data is an ActuatedJoint joint.

class BaseSignalSensor(sender=_Any, autotime=False)[source]¶

Bases: object

Base class for sensors that handle signals with on_send().

Constructor.

Parameters:	sender – object that will send the signal; if it is any_sender, subscription will be to any object autotime – if True and _get_time() is not overriden, every measurement’s time will set to the computer time in that instant

any_sender = _Any¶

on_send(sender, *args, **kwargs)[source]¶

Handle signal sent/fired by sender through the dispatcher.

Takes care of building a data object, set time to it and save it in the data_queue.

Parameters:	sender – signal sender args – signal arguments kwargs – signal keyword arguments

sender¶

Return the sender of the signal to which the sensor listens.

class BaseSourceSensor(source)[source]¶

Bases: object

Abstract base class for all sensors.

Sensor data is stored in a queue (data_queue), and it is usually retrieved after the simulation ends but can be accessed at any time:

measurement = sensor.data_queue.pull()

Warning

Beware that ars.utils.containers.Queue.pull() returns the first element of the queue and removes it.

get_measurement()[source]¶

Return a measurement of the sensor packed in a data structure.

on_change(time=None)[source]¶

Build a SensorData object and stores it in the data_queue.

Parameters:	time (number or None) – if None, current (computer’s) time is used

source¶

class BodySensor(body)[source]¶

Bases: ars.model.robot.sensors.BaseSourceSensor

Abstract base class for sensors whose source of data is a body.

body¶

class GPS(body)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Retrieve a body’s XYZ position.

class Inclinometer(body)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Retrieve a body’s pitch and roll.

class JointForce(sim_joint, sim)[source]¶

Bases: ars.model.robot.sensors.SingleSignalSensor

Sensor measuring force ‘added’ to a joint.

signal = 'robot joint post add force'¶

class JointPower(sim_joint, sim)[source]¶

Bases: ars.model.robot.sensors.MultipleSignalsSensor

Sensor measuring power applied by a joint (due to force and torque).

signals = ['robot joint post add torque', 'robot joint post add force']¶

class JointSensor(joint)[source]¶

Bases: ars.model.robot.sensors.BaseSourceSensor

Abstract base class for sensors whose source of data is a joint.

joint¶

class JointTorque(sim_joint, sim)[source]¶

Bases: ars.model.robot.sensors.SingleSignalSensor

Sensor measuring torque added to a joint.

signal = 'robot joint post add torque'¶

class KineticEnergy(body)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Retrieve a body’s kinetic energy, both due to translation and rotation.

class Laser(space, max_distance=10.0)[source]¶

Bases: ars.model.robot.sensors.BaseSourceSensor

Laser scanner.

get_ray()[source]¶

on_change(time=1488286409.303754)[source]¶

set_position(pos)[source]¶

Set position of the ray.

Useful mainly when it is not attached to a body.

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

set_rotation(rot)[source]¶

Set rotation of the ray.

Useful mainly when it is not attached to a body.

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

class MultipleSignalsSensor(signals, *args, **kwargs)[source]¶

Bases: ars.model.robot.sensors.BaseSignalSensor

Abstract base class for sensors subscribed to multiple signals.

Constructor.

Parameters:	signals (iterable) – signals to subscribe to

class PotentialEnergy(body, gravity)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Retrieve a body’s potential energy.

Calculated based on the current position (x) and world’s gravitational acceleration (g).

class RotaryJointSensor(joint)[source]¶

Bases: ars.model.robot.sensors.ActuatedJointSensor

Sensor measuring the angle (and its rate) of a rotary joint.

class SensorData(*args, **kwargs)[source]¶

Bases: object

Data structure to pack a sensor measurement’s information.

get_arg(index)[source]¶

get_args()[source]¶

get_kwarg(key)[source]¶

get_kwargs()[source]¶

get_time()[source]¶

set_time(time)[source]¶

class SensorDataQueue[source]¶

Bases: ars.utils.containers.Queue

Queue-like container for sensor measurements.

class SimulationSensor(sim)[source]¶

Bases: ars.model.robot.sensors.BaseSourceSensor

Abstract base class for sensors whose source of data is a simulation.

Constructor.

Parameters:	sim (ars.model.simulator.Simulation) – simulation

sim¶

Return the simulation object.

Returns:	simulation
Return type:	ars.model.simulator.Simulation

class SingleSignalSensor(signal, *args, **kwargs)[source]¶

Bases: ars.model.robot.sensors.BaseSignalSensor

Abstract base class for sensors subscribed to one signal.

Constructor.

Parameters:	signal – signal to subscribe to

class SystemTotalEnergy(sim, disaggregate=False)[source]¶

Bases: ars.model.robot.sensors.SimulationSensor

Retrieve a system’s total potential and kinetic energy.

It considers all bodies in the simulation. The kinetic energy accounts for translation and rotation.

class TotalEnergy(body, gravity, disaggregate=False)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Retrieve a body’s potential and kinetic energy.

The kinetic energy accounts for translation and rotation.

class Velometer(body)[source]¶

Bases: ars.model.robot.sensors.BodySensor

Calculate and retrieve a body’s linear and angular velocity.

signals Module¶

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

simulator Package¶

class SimulatedBody(name, body=None, actor=None, geom=None)[source]¶

Bases: ars.model.simulator.SimulatedPhysicsObject

Class encapsulating the physics, collision and graphical objects representing a body.

All the public attributes of the physics object (_body) are accessible as if they were from this class, by using a trick with __getattr__. This avoids code duplication and frequent changes to the interface.

For example, the call sim_body.get_linear_velocity() works if method sim_body._body.get_linear_velocity exists.

There are some exceptions such as the getters and setters of position and rotation because the base class SimulatedPhysicsObject defines those abstract methods (some other non-abstract methods use them) and requires its subclasses to implement them. Otherwise we get “TypeError: Can’t instantiate abstract class SimulatedBody with abstract methods”.

body¶

get_position()[source]¶

Get the position of the body.

Returns:	position
Return type:	3-sequence of floats

get_rotation()[source]¶

Get the orientation of the body.

Returns:	rotation matrix
Return type:	9-sequence of floats

set_position(pos)[source]¶

Set the orientation of the body.

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

set_rotation(rot)[source]¶

Set the orientation of the body.

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

class SimulatedJoint(name=None, joint=None, actor=None)[source]¶

Bases: ars.model.simulator.SimulatedPhysicsObject

add_torque(torque)[source]¶

get_position()[source]¶

get_rotation()[source]¶

joint¶

set_position(pos)[source]¶

set_rotation(rot)[source]¶

class SimulatedObject(name, actor=None)[source]¶

Bases: object

actor¶

get_name()[source]¶

has_actor()[source]¶

is_updatable()[source]¶

set_name(name)[source]¶

class SimulatedPhysicsObject(name, actor=None)[source]¶

Bases: ars.model.simulator.SimulatedObject

get_pose()[source]¶

Get the pose (3D position and rotation) of the object.

Returns:	pose
Return type:	ars.utils.geometry.Transform

get_position()[source]¶

Get the position of the object.

Returns:	position
Return type:	3-sequence of floats

get_rotation()[source]¶

Get the orientation of the object.

Returns:	rotation matrix
Return type:	9-sequence of floats

offset_by_object(obj)[source]¶

offset_by_position(offset_pos)[source]¶

rotate(axis, angle)[source]¶

Rotate the object by applying a rotation matrix defined by the given axis and angle

set_pose(pose)[source]¶

Set the pose (3D position and rotation) of the object.

Parameters:	pose (ars.utils.geometry.Transform) –

set_position(pos)[source]¶

Set the orientation of the object.

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

set_rotation(rot)[source]¶

Set the orientation of the object.

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

update_actor()[source]¶

If there is no actor, it won’t do anything

class Simulation(FPS, STEPS_PF)[source]¶

Bases: object

actors¶

Return a dict with each object actor indexed by the object name.

add_axes()[source]¶

add_ball_socket_joint(name, obj1, obj2, anchor)[source]¶

Adds a “ball and socket” joint between obj1 and obj2, at the specified anchor. If anchor is None, it will be set equal to the position of obj2.

add_basic_simulation_objects(gravity=(0.0, -9.81, 0.0))[source]¶

Create the basic simulation objects needed for physics and collision such as a contact group (holds temporary contact joints generated during collisions), a simulation ‘world’ (where physics objects are processed) and a collision space (the same thing for geoms and their intersections).

Parameters:	gravity (3 floats tuple.) – Gravity acceleration.

add_box(size, center, mass=None, density=None)[source]¶

add_capsule(length, radius, center, mass=None, density=None)[source]¶

add_cylinder(length, radius, center, mass=None, density=None)[source]¶

add_fixed_joint(obj1, obj2)[source]¶

add_floor(normal=(0, 1, 0), dist=0, box_size=(5, 0.1, 5), box_center=(0, 0, 0), color=(0.2, 0.5, 0.5))[source]¶

Create a plane geom to simulate a floor. It won’t be used explicitly later (space object has a reference to it)

add_joint(sim_joint)[source]¶

add_object(sim_object)[source]¶

Add sim_object to the internal dictionary of simulated objects.

If its name equals an already registered key, it will be modified using its string representation, for example:

>>> add_object(sim_object)
sphere/<ars.model.simulator.SimulatedBody object at 0x3a4bed0>

Parameters:	sim_object (SimulatedObject) – object to add
Returns:	name/key of the object
Return type:	string

add_rotary_joint(name, obj1, obj2, anchor, axis)[source]¶

Adds a rotary joint between obj1 and obj2, at the specified anchor and with the given axis. If anchor is None, it will be set equal to the position of obj2

add_slider_joint(name, obj1, obj2, axis)[source]¶

Add a jo.Slider joint between obj1 and obj2.

The only movement allowed is translation along axis.

Returns:	the name under which the slider was stored, which could be different from the given name

add_sphere(radius, center, mass=None, density=None)[source]¶

add_trimesh_floor(vertices, faces, center=(0, 0, 0), color=(0.2, 0.5, 0.5))[source]¶

add_universal_joint(obj1, obj2, anchor, axis1, axis2)[source]¶

collision_space¶

get_bodies()[source]¶

Return a list with all the bodies included in the simulation.

Returns:	list of SimulatedBody objects

get_joint(name)[source]¶

get_object(name)[source]¶

gravity¶

joints¶

objects¶

on_idle()[source]¶

perform_sim_steps_per_frame()[source]¶

sim_time¶

time_step¶

update_actors()[source]¶

Update pose of each simulated object’s corresponding actor.

signals Module¶

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