The Environment is responsible for setting up and checking collisions with external obstacles.

Setting up the Environment#

To define an environment, we can pass the robot that we want to use for planning, as well as an optional safety margin that will be applied to all collision checks.

environment = Environment(robot, safety_margin=0.01)  # [m]


Jacobi currently supports Box, Capsule, Convex, Cylinder, and Sphere objects. These primitive objects can be defined by

box = Box(x=0.1, y=0.1, z=0.1)  # [m]
capsule = Capsule(radius=0.1, length=0.2)  # [m]
convex = Convex.load_from_file(project_path / 'table.obj')
cylinder = Cylinder(radius=0.1, length=0.2)  # [m]
sphere = Sphere(radius=0.1)  # [m]

For the geometric primitives, the origin is at the geometric center of the object. The length of the capsule and the cylinder is defined along z-axis.

For the Convex object type, a mesh can be loaded from a .obj or .stl file. We then check if the object is convex, and calculate the convex hull if that is not the case. We will add further utility methods, in particular for convex decomposition, to the Jacobi motion library very soon.


Obstacles combine an object together with an exact pose. We can either add an obstacle to an environment by

environment.add_obstacle(box, Frame(z=0.2))  # [m]

or by constructing an Obstacle explicitly

obstacle = Obstacle(box, Frame(z=0.2))  # [m]

The latter is in particular useful for defining obstacles for the robot’s end effector or item obstacle.