Environment

class jacobi.Environment

Bases: pybind11_object

The environment a robot (or multiple robots) lives in

The Environment class manages static obstacles, collision checking, waypoints, cameras, and robots within a defined environment. The class provides methods to add, remove, and manage obstacles and waypoints, as well as to retrieve information about these elements. It also includes functionality for collision checking and updating the state of obstacles and robots.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: jacobi.Environment, robot: jacobi.Robot, safety_margin: float = 0.0) -> None

Create an environment with a controllable robot

Parameter robot:

The robot to add to the environment.

Parameter safety_margin:

The global safety margin for collision checking [m].

  1. __init__(self: jacobi.Environment, robots: set[jacobi.Robot], safety_margin: float = 0.0) -> None

Create an environment with multiple robots

Parameter robots:

The robots to add to the environment.

Parameter safety_margin:

The global safety margin for collision checking [m].

add_obstacle(*args, **kwargs)

Overloaded function.

  1. add_obstacle(self: jacobi.Environment, obstacle: jacobi.Obstacle) -> jacobi.Obstacle

Add an obstacle to the environment (and returns the pointer to it)

Parameter obstacle:

The obstacle to add to the environment.

Returns:

The original shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.Box, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a box-shaped obstacle to the environment

Parameter object:

The box-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.Capsule, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a capsule-shaped obstacle to the environment

Parameter object:

The capsule-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.Convex, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a convex-shaped obstacle to the environment

Parameter object:

The convex-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: list[jacobi.Convex], origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a vector of convex-shaped obstacles to the environment

Parameter object:

The vector of convex-shaped obstacles to add.

Parameter origin:

The initial pose of the obstacles in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacles in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacles (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.Cylinder, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a cylinder-shaped obstacle to the environment

Parameter object:

The cylinder-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.DepthMap, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a depth map-shaped obstacle to the environment

Parameter object:

The depth map-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.MeshFile, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a file obstacle to the environment

Parameter object:

The file obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.PointCloud, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a point cloud obstacle to the environment

Parameter object:

The point cloud obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, object: jacobi.Sphere, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a sphere-shaped obstacle to the environment

Parameter object:

The sphere-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Box, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add an obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The obstacle to add (of a specific type, e.g., Box, Capsule, etc.).

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Capsule, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Overload for adding an obstacle with a name and various shapes

Parameter name:

The name to assign to the obstacle.

Parameter object:

The obstacle to add (of a specific type, e.g., Capsule, Convex, etc.).

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Convex, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a convex-shaped obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The convex-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: list[jacobi.Convex], origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a vector of convex-shaped obstacles with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The vector of convex-shaped obstacles to add.

Parameter origin:

The initial pose of the obstacles in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacles in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacles (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Cylinder, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a cylinder-shaped obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The cylinder-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.DepthMap, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a depth map-shaped obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The depth map-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.MeshFile, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a file obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The file obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.PointCloud, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a point cloud obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The point cloud obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

  1. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Sphere, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> jacobi.Obstacle

Add a sphere-shaped obstacle with a name to the environment

Parameter name:

The name to assign to the obstacle.

Parameter object:

The sphere-shaped obstacle to add.

Parameter origin:

The initial pose of the obstacle in the environment (default is Frame::Identity()).

Parameter color:

The color of the obstacle in hexadecimal format (default is “000000”).

Parameter safety_margin:

The safety margin around the obstacle (default is 0.0).

Returns:

A shared pointer to the added obstacle.

static carve_point_cloud(point_cloud: Obstacle, obstacle: Obstacle) → None

Carves (subtracts) an obstacle from a point cloud.

This function removes all points from the point cloud that are in collision with the obstacle. The point cloud is modified in place. The function does not update the collision model and update_point_cloud() may be called afterwards.

Parameter point_cloud:

The point cloud to carve the obstacle from.

Parameter obstacle:

The obstacle to carve from the point cloud.

check_collision(*args, **kwargs)

Overloaded function.

  1. check_collision(self: jacobi.Environment, robot: jacobi.Robot, joint_position: list[float]) -> bool

  2. check_collision(self: jacobi.Environment, joint_position: list[float]) -> bool

  3. check_collision(self: jacobi.Environment, robot: jacobi.Robot, waypoint: jacobi.CartesianWaypoint) -> bool

  4. check_collision(self: jacobi.Environment, robot: jacobi.Robot, tcp: jacobi.Frame, reference_config: Optional[list[float]] = None) -> bool

  5. check_collision(self: jacobi.Environment, tcp: jacobi.Frame, reference_config: Optional[list[float]] = None) -> bool

  6. check_collision(self: jacobi.Environment, waypoint: jacobi.CartesianWaypoint) -> bool

get_camera(self: Environment, name: str = '') → Camera

Get a camera from the environment

Parameter name:

Optional parameter to specify the name of the camera. If not provided, an empty string defaults to retrieving a camera without a specific name.

Returns:

A shared pointer to the camera associated with the given name, or a default camera if the name is empty.

get_collision_free_joint_position_nearby(self: Environment, joint_position: list[float], robot: Robot = None) → list[float] | None
get_obstacle(self: Environment, name: str) → Obstacle

Get the obstacle with the given name from the environment. Throws an error if no obstacle with the name exists.

Parameter name:

The name of the obstacle to retrieve.

Returns:

A shared pointer to the obstacle associated with the given name.

get_obstacles(self: Environment) → list[Obstacle]

Get all obstacles within the environment

This function retrieves a list of all obstacles present in the environment.

Returns:

A vector of shared pointers to the obstacles within the environment.

get_obstacles_by_tag(self: Environment, tag: str) → list[Obstacle]

Get all obstacles within the environment that carry the given tag.

Parameter tag:

The tag associated with the obstacles to retrieve.

Returns:

A vector of shared pointers to the obstacles that have the specified tag.

get_robot(self: Environment, name: str = '') → Robot

Get the robot with the given name from the environment.

In case there is only a single robot in the environment, the default empty name argument will return this robot. Otherwise throws an error if no robot with the name exists.

Parameter name:

The name of the robot to retrieve.

Returns:

The shared pointer to a robot object associated with the given name.

get_robots(self: Environment) → list[Robot]

Get all robots within the environment

Returns:

A vector of shared pointers to the robots within the environment.

get_waypoint(self: Environment, name: str) → list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion

Get the waypoint with the given name from the environment. Throws an error if no waypoint with the name exists.

Parameter name:

The name of the waypoint to retrieve.

Returns:

The waypoint associated with the given name.

get_waypoint_by_tag(self: Environment, tag: str) → list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion | None

Get a waypoint within the environment given a tag. If multiple waypoints have the same tag, the first one to be found is returned.

Parameter tag:

The tag associated with the waypoint to retrieve.

Returns:

An optional containing the waypoint associated with the given tag, or std::nullopt if no waypoint with the tag is found.

get_waypoints(self: Environment) → list[list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion]

Get all waypoints within the environment

This function retrieves a list of all waypoints present in the environment.

Returns:

A vector of waypoints within the environment.

get_waypoints_by_tag(self: Environment, tag: str) → list[list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion]

Get all waypoints within the environment given a tag.

Parameter tag:

The tag associated with the waypoints to retrieve.

Returns:

A vector of waypoints that have the specified tag.

remove_obstacle(*args, **kwargs)

Overloaded function.

  1. remove_obstacle(self: jacobi.Environment, obstacle: jacobi.Obstacle) -> None

Removes the given obstacles from the environment and from all collision checking.

Parameter obstacle:

The obstacle to remove from the environment.

  1. remove_obstacle(self: jacobi.Environment, name: str) -> None

Removes all obstacles with the given name from the environment and from all collision checking.

Parameter name:

The name of the obstacle to remove from the environment.

update_depth_map(self: Environment, obstacle: Obstacle) → None

Updates the depths matrix of a given depth map obstacle for the internal collision checking.

Parameter obstacle:

The obstacle to update the depths map for.

update_fixed_obstacles(self: Environment) → None

Updates all fixed obstacles for the internal collision checking. This should be called after changing e.g. the position or size of an obstacle.

update_joint_position(self: Environment, robot: Robot, joint_position: list[float]) → None

Updates the joint position of the given robot for the internal collision checking.

Parameter robot:

The robot to update the joint position for.

Parameter joint_position:

The new joint position to set for the robot.

update_point_cloud(self: Environment, obstacle: Obstacle) → None

Updates the point cloud of a given point cloud obstacle for the internal collision checking.

Parameter obstacle:

The point cloud to update the points for.

update_robot(self: Environment, robot: Robot = None) → None

Updates the given robot (or the default one if none was given) for the internal collision checking.

Parameter robot:

The robot to update the collision model for.

property safety_margin

Environment’s global safety margin for collision checking [m]

Returns:

The global safety margin for collision checking [m].