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.

__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].

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Check if a joint position is in collision

Parameter robot:: The robot to check the joint position for.
Parameter joint_position:: The joint position to check for collision.
Returns:: True if the joint position is in collision, false otherwise.

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

Check if a joint position is in collision

Parameter joint_position:: The joint position to check for collision.
Returns:: True if the joint position is in collision, false otherwise.

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

Check if there exists a collision-free inverse kinematics for the Cartesian position

Parameter robot:: The robot to check the Cartesian position for.
Parameter waypoint:: The Cartesian position to check for collision.
Returns:: True if there exists a collision-free inverse kinematics for the Cartesian position, false otherwise.

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

Check if there exists a collision-free inverse kinematics for the given robot and end-effector pose

Parameter robot:: The robot to check for collision-free inverse kinematics.
Parameter tcp:: The end-effector pose (transformation) to check for collision.
Parameter reference_config:: Optional reference configuration for inverse kinematics of the end-effector pose.
Returns:: True if there exists a collision-free inverse kinematics for the given end-effector pose, false otherwise.

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

Check if there exists a collision-free inverse kinematics for the Cartesian position

Parameter waypoint:: The Cartesian position to check for collision.
Returns:: True if there exists a collision-free inverse kinematics for the Cartesian position, false otherwise.

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

Check if there exists a collision-free inverse kinematics for the given end-effector pose

Parameter tcp:: The end-effector pose to check for collision.
Parameter reference_config:: Optional reference configuration for inverse kinematics of the end-effector pose.
Returns:: True if there exists a collision-free inverse kinematics for the given end-effector pose, false otherwise.

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¶

Calculate a collision free joint position close to the reference position.

Parameter joint_position:: The reference joint position to find a collision free joint position close to.
Parameter robot:: The robot to find a collision free joint position for.
Returns:: An optional containing the collision free joint position close to the reference position, or std::nullopt if no such joint position exists.

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

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.

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