Python

Geometry

class Config

Type alias for List[float] as a joint configuration of a robot.

class jacobi.Frame

Bases: pybind11_object

Represents a transformation or pose in 3D Cartesian space.

Encapsulates translation and rotation in a unified manner for 3D poses.

static Identity() → Frame

Get the identity transformation.

Returns:

Frame The identity Frame.

__init__(self: Frame, *, x: float = 0.0, y: float = 0.0, z: float = 0.0, a: float = 0.0, b: float = 0.0, c: float = 0.0, qw: float = 1.0, qx: float = 0.0, qy: float = 0.0, qz: float = 0.0) → None

angular_distance(self: Frame, other: Frame) → float

Calculate the angular distance between two Frames’ orientations.

Parameter other:

The other Frame to compare against.

Returns:

double The angular distance.

static from_euler(x: float, y: float, z: float, a: float, b: float, c: float) → Frame

Create a Frame from Euler angles.

Parameter x:

The x translation.

Parameter y:

The y translation.

Parameter z:

The z translation.

Parameter a:

The rotation angle around the x-axis.

Parameter b:

The rotation angle around the y-axis.

Parameter c:

The rotation angle around the z-axis.

Returns:

Frame The Frame with the specified translation and Euler angles.

static from_matrix(data: Annotated[list[float], FixedSize(16)]) → Frame

Create a Frame from a matrix.

Parameter data:

A 16-element array representing a 4x4 matrix.

Returns:

Frame The Frame constructed from the matrix.

static from_quaternion(x: float, y: float, z: float, qw: float, qx: float, qy: float, qz: float) → Frame

Create a Frame from quaternion values.

Parameter x:

The x component of the quaternion.

Parameter y:

The y component of the quaternion.

Parameter z:

The z component of the quaternion.

Parameter qw:

The scalar component of the quaternion.

Parameter qx:

The x component of the quaternion.

Parameter qy:

The y component of the quaternion.

Parameter qz:

The z component of the quaternion.

Returns:

Frame The Frame with the specified quaternion.

static from_translation(x: float, y: float, z: float) → Frame

Create a Frame from translation values.

Parameter x:

The x translation.

Parameter y:

The y translation.

Parameter z:

The z translation.

Returns:

Frame The Frame with the specified translation.

interpolate(self: Frame, t: float, other: Frame) → Frame

Interpolate between this Frame and another Frame.

Parameter t:

The interpolation parameter (0.0 to 1.0).

Parameter other:

The other Frame to interpolate towards.

Returns:

Frame The interpolated Frame.

inverse(self: Frame) → Frame

translational_distance(self: Frame, other: Frame) → float

Calculate the Euclidean distance between two Frames’ positions.

Parameter other:

The other Frame to compare against.

Returns:

double The Euclidean distance.

property euler

Convert the Frame to Euler angles and translation.

Returns:

std::array<double, 6> The Frame as Euler angles and translation.

property matrix

Convert the Frame to a 4x4 matrix.

Returns:

std::array<double, 16> The Frame as a 4x4 matrix.

class jacobi.Twist

Bases: pybind11_object

Represents a velocity in 3D Cartesian space.

The Twist struct represents a 6-dimensional vector used to describe velocity in 3D Cartesian space. It consists of linear velocities in the x, y, and z directions, and angular velocities around these axes.

__init__(self: Twist, x: float, y: float, z: float, rx: float, ry: float, rz: float) → None

Default constructor.

Element

class jacobi.Element

Bases: pybind11_object

The base element of a scene

The Element struct represents the base element of a scene, such as a robot, camera, or obstacle. It contains a name, pose, and tags that can be used to identify and categorize the element.

__init__(*args, **kwargs)

get_parameter(self: Element, tag: str) → str | None

Reads the value of a tag parameter param=value. Tags are case- insensitive.

Parameter tag:

The tag to read the parameter from.

Returns:

std::optional<std::string> The value of the parameter if it exists, std::nullopt otherwise.

has_tag(self: Element, tag: str) → bool

Checks whether a tag is present on the element. Tags are case- insensitive.

Parameter tag:

The tag to check for.

Returns:

bool True if the tag is present, false otherwise.

property name

The unique name of the element, for display and identification.

property origin

Pose of the element, relative to the parent. Is called “base” for robots in Studio.

property tags

Given tags of the element, might be with a parameter param=value.

Waypoints

class jacobi.Waypoint

Bases: Element

A joint-space waypoint with possible position, velocity, and/or acceleration values.

The Waypoint class represents a point in the joint space of a robot with associated position, velocity, and acceleration values.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.Waypoint, position: list[float]) -> None

Construct a waypoint by position data.

Parameter data:

A list of position values to initialize the waypoint.

2. __init__(self: jacobi.Waypoint, position: list[float], velocity: list[float]) -> None

Construct a waypoint with given position and zero velocity and acceleration.

Parameter position:

The joint position to initialize the waypoint.

3. __init__(self: jacobi.Waypoint, position: list[float], velocity: list[float], acceleration: list[float]) -> None

Construct a waypoint with given position and velocity and zero acceleration.

Parameter position:

The joint position to initialize the waypoint.

Parameter velocity:

The joint velocity to initialize the waypoint.

is_within(self: Waypoint, other: Waypoint) → bool

property acceleration

The joint acceleration at the waypoint.

property position

The joint position at the waypoint.

property velocity

The joint velocity at the waypoint.

class jacobi.CartesianWaypoint

Bases: Element

A Cartesian-space waypoint with possible position, velocity, and/or acceleration values.

The CartesianWaypoint class represents a point in Cartesian space with associated position, velocity, and acceleration frames. It is used to define the robot state in Cartesian space at a specific instance, with optional reference joint positions for inverse kinematics.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.CartesianWaypoint, position: jacobi.Frame, reference_config: Optional[list[float]] = None) -> None

Construct a Cartesian waypoint with given position and zero velocity and acceleration.

Parameter position:

The position frame to initialize the waypoint.

Parameter reference_config:

An optional joint configuration for inverse kinematics.

2. __init__(self: jacobi.CartesianWaypoint, position: jacobi.Frame, velocity: jacobi.Frame, reference_config: Optional[list[float]] = None) -> None

Construct a Cartesian waypoint with given position and velocity and zero acceleration.

Parameter position:

The position frame to initialize the waypoint.

Parameter velocity:

The velocity frame to initialize the waypoint.

Parameter reference_config:

An optional joint configuration for inverse kinematics.

3. __init__(self: jacobi.CartesianWaypoint, position: jacobi.Frame, velocity: jacobi.Frame, acceleration: jacobi.Frame, reference_config: Optional[list[float]] = None) -> None

Construct a Cartesian waypoint with given position, velocity, and acceleration.

Parameter position:

The position frame to initialize the waypoint.

Parameter velocity:

The velocity frame to initialize the waypoint.

Parameter acceleration:

The acceleration frame to initialize the waypoint.

Parameter reference_config:

An optional joint configuration for inverse kinematics.

property acceleration

Frame of the acceleration.

property position

Frame of the position.

property reference_config

An optional joint position that is used as a reference for inverse kinematics.

property velocity

Frame of the velocity.

class jacobi.Region

Bases: Element

A joint-space region with possible position, velocity, and/or acceleration values.

The Region class defines a region in joint space with boundaries on position, velocity, and acceleration. It is used to specify an area within which a the robot end-effector operates. The class provides methods to construct the region with varying levels of detail and to check if a given waypoint falls within the region’s boundaries.

__init__(self: Region, min_position: list[float], max_position: list[float]) → None

is_within(self: Region, other: Waypoint) → bool

Check if a given waypoint is within the region.

Parameter other:

The waypoint to check.

Returns:

true If the waypoint is within the region’s boundaries.

Returns:

false If the waypoint is not within the region’s boundaries.

This method checks if the given waypoint’s position, velocity, and acceleration fall within the respective boundaries defined by the region.

property max_acceleration

Maximum acceleration boundary of the region.

property max_position

Maximum position boundary of the region.

property max_velocity

Maximum velocity boundary of the region.

property min_acceleration

Minimum acceleration boundary of the region.

property min_position

Minimum position boundary of the region.

property min_velocity

Minimum velocity boundary of the region.

class jacobi.CartesianRegionBound

Bases: pybind11_object

The min or max boundary of a Cartesian region.

The CartesianRegionBound struct represents the boundaries of a region in Cartesian space. It defines both positional (x, y, z) and orientational (gamma, alpha) limits. These boundaries are used to constrain the movement or state of an object within a specified region.

__init__(self: CartesianRegionBound, x: float, y: float, z: float, gamma: float = 0.0, alpha: float = 0.0) → None

property alpha

The rotational component around the x-axis (roll).

property gamma

The rotational component around the z-axis (yaw).

property x

The x-coordinate of the boundary.

property y

The y-coordinate of the boundary.

property z

The z-coordinate of the boundary.

class jacobi.CartesianRegion

Bases: Element

A Cartesian-space region with possible minimum and maximum position, velocity, and/or acceleration values.

The CartesianRegion class defines a region in Cartesian space with optional boundaries for position, velocity, and acceleration. It is used to describe constraints on a Cartesian region within which the robot end-effector operates. The region can also have an associated reference configuration.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.CartesianRegion, min_position: jacobi.CartesianRegionBound, max_position: jacobi.CartesianRegionBound, reference_config: Optional[list[float]] = None) -> None

2. __init__(self: jacobi.CartesianRegion, min_position: jacobi.CartesianRegionBound, max_position: jacobi.CartesianRegionBound, min_velocity: jacobi.CartesianRegionBound, max_velocity: jacobi.CartesianRegionBound, reference_config: Optional[list[float]] = None) -> None

3. __init__(self: jacobi.CartesianRegion, min_position: jacobi.CartesianRegionBound, max_position: jacobi.CartesianRegionBound, min_velocity: jacobi.CartesianRegionBound, max_velocity: jacobi.CartesianRegionBound, min_acceleration: jacobi.CartesianRegionBound, max_acceleration: jacobi.CartesianRegionBound, reference_config: Optional[list[float]] = None) -> None

property max_acceleration

Maximum acceleration boundary of the region.

property max_position

Maximum position boundary of the region.

property max_velocity

Maximum velocity boundary of the region.

property min_acceleration

Minimum acceleration boundary of the region.

property min_position

Minimum position boundary of the region.

property min_velocity

Minimum velocity boundary of the region.

property reference_config

Reference configuration for the region, if any.

class MultiRobotPoint

Type alias for Dict[Robot, Config | Waypoint | CartesianWaypoint]. A type for specifying an exact start or goal point per robot.

class Point

Type alias for Config | Waypoint | CartesianWaypoint | MultiRobotPoint | Region | CartesianRegion. All types for specifying motion start or goals, either exact or by region.

class ExactPoint

Type alias for Config | Waypoint | CartesianWaypoint | MultiRobotPoint. All types for specifying exact start or goal points.

Obstacles

class jacobi.Box

Bases: pybind11_object

A box collision object.

The Box struct represents a simple 3D rectangular collision object. It is defined by its dimensions along the x, y, and z axes, which correspond to the width, depth, and height of the box, respectively.

__init__(self: Box, x: float, y: float, z: float) → None

Construct a box of size x, y, z along the respective axes.

Parameter x:

The width of the box along the x-axis.

Parameter y:

The depth of the box along the y-axis.

Parameter z:

The height of the box along the z-axis.

property x

Dimensions of the box [m]

property y

Dimensions of the box [m]

property z

Dimensions of the box [m]

class jacobi.Capsule

Bases: pybind11_object

A capsule collision object.

The Capsule struct represents a simple 3D collision object shaped like a capsule (a cylinder with hemispherical ends). It is defined by its radius and length along the z-axis. Capsules are commonly used in collision detection due to their computational efficiency.

__init__(self: Capsule, radius: float, length: float) → None

Construct a capsule with the given radius and length.

Parameter radius:

The radius of the capsule.

Parameter length:

The length of the capsule along the z-axis.

property length

Length of the capsule along the z-axis [m]

property radius

Radius of the capsule [m]

class jacobi.Convex

Bases: pybind11_object

A convex mesh collision object.

The Convex struct represents a 3D convex mesh, often used for collision detection. It supports loading from files, direct vertex and triangle specification, and provides utility functions like bounding box computation.

__init__(self: Convex, vertices: list[Annotated[list[float], FixedSize(3)]], triangles: list[Annotated[list[int], FixedSize(3)]]) → None

static load_from_file(path: os.PathLike, scale: float | None = None) → list[Convex]

Load convex objects from a file.

Parameter path:

The path to the file (*.obj).

Parameter scale:

Optional scale to apply when loading the object.

Returns:

A vector of Convex objects loaded from the file.

static reference_studio_file(path: os.PathLike, scale: float | None = None) → Convex

Create a reference to a Studio file.

Parameter path:

The path to the Studio file.

Parameter scale:

Optional scale to apply when referencing the file.

Returns:

A Convex object that references the specified Studio file.

property bounding_box_maximum

Get the maximum bounding box corner.

Returns:

A 3D vector representing the maximum corner of the bounding box.

property bounding_box_minimum

Get the minimum bounding box corner.

Returns:

A 3D vector representing the minimum corner of the bounding box.

property file_reference

Optional file reference from which the convex object was loaded.

class jacobi.Cylinder

Bases: pybind11_object

A cylinder collision object.

The Cylinder struct represents a 3D cylindrical collision object. It is defined by its radius and length along the z-axis.

__init__(self: Cylinder, radius: float, length: float) → None

Construct a cylinder with the given radius and length.

Parameter radius:

The radius of the cylinder.

Parameter length:

The length of the cylinder along the z-axis.

property length

Length of the cylinder along the z-axis [m].

property radius

Radius of the cylinder [m].

class jacobi.Sphere

Bases: pybind11_object

A sphere collision object.

The Sphere struct represents a 3D spherical collision object, defined by its radius, which determines its size in all directions.

__init__(self: Sphere, radius: float) → None

Construct a sphere with the given radius.

Parameter radius:

The radius of the sphere.

Initializes the sphere with the specified radius.

property radius

Radius of the sphere [m]

class jacobi.Obstacle

Bases: Element

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.Obstacle, collision: jacobi.Box, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

2. __init__(self: jacobi.Obstacle, collision: jacobi.Capsule, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

3. __init__(self: jacobi.Obstacle, collision: jacobi.Convex, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

4. __init__(self: jacobi.Obstacle, collision: list[jacobi.Convex], origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

5. __init__(self: jacobi.Obstacle, collision: jacobi.Cylinder, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

6. __init__(self: jacobi.Obstacle, collision: jacobi.DepthMap, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

7. __init__(self: jacobi.Obstacle, collision: jacobi.Sphere, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

8. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.Box, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

9. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.Capsule, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

10. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.Convex, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

11. __init__(self: jacobi.Obstacle, name: str, collision: list[jacobi.Convex], origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

12. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.Cylinder, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

13. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.DepthMap, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

14. __init__(self: jacobi.Obstacle, name: str, collision: jacobi.Sphere, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

with_origin(self: Obstacle, origin: Frame) → Obstacle

property collision

The object for collision checking (and/or visualization).

This variant holds the geometric representation of the obstacle. It can be any of the supported shapes, including Box, Capsule, Convex, ConvexVector, Cylinder, DepthMap, or Sphere.

property color

The hex-string representation of the obstacle’s color, without the leading #.

This string defines the color of the obstacle for visualization purposes, formatted as a hex code (e.g., “FF5733” for orange).

property for_collision

Whether this obstacle is used for collision checking.

If true, the obstacle will be considered in collision detection calculations. By default, this is set to true.

property for_visual

Whether this obstacle is used for visualization.

If true, the obstacle will be rendered in the environment’s visualization in Studio. By default, this is set to true.

property safety_margin

An additional obstacle-specific safety margin for collision checking (on top of the environment’s global safety margin).

This margin adds an extra buffer around the obstacle during collision detection. It is specific to this obstacle and is added on top of any global safety margins.

class Matrix

Type alias for List[List[float]].

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

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

2. add_obstacle(self: jacobi.Environment, object: jacobi.Box, origin: jacobi.Frame = Frame(), name: 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.

3. add_obstacle(self: jacobi.Environment, object: jacobi.Capsule, origin: jacobi.Frame = Frame(), name: 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.

4. add_obstacle(self: jacobi.Environment, object: jacobi.Convex, origin: jacobi.Frame = Frame(), name: 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.

5. add_obstacle(self: jacobi.Environment, object: list[jacobi.Convex], origin: jacobi.Frame = Frame(), name: 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.

6. add_obstacle(self: jacobi.Environment, object: jacobi.Cylinder, origin: jacobi.Frame = Frame(), name: 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.

7. add_obstacle(self: jacobi.Environment, object: jacobi.DepthMap, origin: jacobi.Frame = Frame(), name: 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.

8. add_obstacle(self: jacobi.Environment, object: jacobi.Sphere, origin: jacobi.Frame = Frame(), name: 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.

9. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Box, origin: jacobi.Frame = Frame(), name: 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.

10. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Capsule, origin: jacobi.Frame = Frame(), name: 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.

11. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Convex, origin: jacobi.Frame = Frame(), name: 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.

12. add_obstacle(self: jacobi.Environment, name: str, object: list[jacobi.Convex], origin: jacobi.Frame = Frame(), name: 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.

13. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Cylinder, origin: jacobi.Frame = Frame(), name: 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.

14. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.DepthMap, origin: jacobi.Frame = Frame(), name: 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.

15. add_obstacle(self: jacobi.Environment, name: str, object: jacobi.Sphere, origin: jacobi.Frame = Frame(), name: 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.

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 = '') → jacobi.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.

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

property safety_margin

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

Returns:

The global safety margin for collision checking [m].

Robots

class jacobi.Robot

Bases: pybind11_object

__init__(*args, **kwargs)

static from_model(model: str) → Robot

set_speed(self: Robot, speed: float) → None

property model

The model name of the robot

property name

The name (id) of the robot arm

class jacobi.RobotArm

Bases: Robot

__init__(*args, **kwargs)

calculate_tcp(self: RobotArm, joint_position: list[float]) → Frame

Calculates the forward_kinematics and returns the frame of the robot’s TCP.

Parameter joint_position:

The joint position of the robot.

Returns:

The frame of the robot’s TCP.

calculate_tcp_speed(self: RobotArm, joint_position: list[float], joint_velocity: list[float]) → float

Calculates the forward_kinematics and returns the norm of the Cartesian velocity of the robot’s TCP.

Parameter joint_position:

The joint position of the robot.

Parameter joint_velocity:

The joint velocity of the robot.

Returns:

The Cartesian speed of the TCP.

inverse_kinematics(*args, **kwargs)

Overloaded function.

1. inverse_kinematics(self: jacobi.RobotArm, waypoint: jacobi.CartesianWaypoint) -> Optional[list[float]]

Computes the inverse kinematics for a Cartesian waypoint.

Parameter waypoint:

The Cartesian waypoint to compute the inverse kinematics for.

Returns:

An optional Config object representing the joint positions of the robot.

2. inverse_kinematics(self: jacobi.RobotArm, tcp: jacobi.Frame, reference_config: Optional[list[float]] = None) -> Optional[list[float]]

Computes the inverse kinematics for a Cartesian position and a reference configuration.

Finds a joint position so that the robot’s TCP is at the given frame, which is defined in the world coordinate system. In general, the solution will try to stay close to the reference_config parameter. We use a numerical optimization for robots with more than 6 degrees of freedom. Then, the reference configuration is used as a starting point for the optimization. This method does not take the environment’s collision model into account.

Parameter tcp:

The Cartesian position to compute the inverse kinematics for.

Parameter reference_config:

The reference configuration to use for the inverse kinematics.

Returns:

An optional Config object representing the joint positions of the robot.

set_speed(self: RobotArm, speed: float) → None

Sets the velocity, acceleration, and jerk limits to a factor [0, 1] of their respective default (maximum) values.

Parameter speed:

A double representing the speed to be set for the robot.

property default_position

The default robot position - used for initializing the current robot position.

property degrees_of_freedom

The degrees of freedom (or number of axis) of the robot.

property end_effector_obstacle

internal An (optional) obstacle attached to the robot’s flange.

property flange_to_tcp

internal The transformation from the robot’s flange to the robot’s TCP, e.g., for using inverse kinematics or an item obstacle.

property item_obstacle

internal An (optional) obstacle attached to the robot’s TCP.

property link_obstacles

The obstacles for each robot link.

property max_acceleration

Maximum absolute acceleration for each joint. [rad/s^2]

property max_jerk

Maximum absolute jerk for each joint. [rad/s^3]

property max_position

Maximum position for each joint. [rad]

property max_velocity

Maximum absolute velocity for each joint. [rad/s]

property min_position

Minimum position for each joint. [rad]

property tcp

Retrieves the frame of the robot’s TCP.

Returns:

A Frame representing the frame of the robot’s TCP.

property tcp_acceleration

Retrieves the Cartesian acceleration of the robot’s TCP.

Returns:

A Twist representing the Cartesian acceleration of the robot’s TCP.

property tcp_position

Retrieves the frame of the robot’s TCP.

Returns:

A Frame representing the frame of the robot’s TCP.

property tcp_velocity

Retrieves the Cartesian velocity of the robot’s TCP.

Returns:

A Twist representing the Cartesian velocity of the robot’s TCP.

class jacobi.robots.DualArm

Bases: Robot

__init__(self: DualArm, left: RobotArm, right: RobotArm) → None

property left

The left arm of the robot

property right

The right arm of the robot

class jacobi.robots.ABBIRB1200590

Bases: RobotArm

__init__(self: ABBIRB1200590) → None

class jacobi.robots.ABBIRB1300714

Bases: RobotArm

__init__(self: ABBIRB1300714) → None

class jacobi.robots.ABBIRB1600612

Bases: RobotArm

__init__(self: ABBIRB1600612) → None

class jacobi.robots.ABBIRB460060205

Bases: RobotArm

__init__(self: ABBIRB460060205) → None

class jacobi.robots.ABBIRB6700150320

Bases: RobotArm

__init__(self: ABBIRB6700150320) → None

class jacobi.robots.ABBYuMiIRB14000

Bases: DualArm

__init__(self: ABBYuMiIRB14000) → None

class jacobi.robots.FanucLR10iA10

Bases: RobotArm

__init__(self: FanucLR10iA10) → None

class jacobi.robots.FanucLRMate200iD7L

Bases: RobotArm

__init__(self: FanucLRMate200iD7L) → None

class jacobi.robots.FanucM20iB25

Bases: RobotArm

__init__(self: FanucM20iB25) → None

class jacobi.robots.FanucM710iC45M

Bases: RobotArm

__init__(self: FanucM710iC45M) → None

class jacobi.robots.FrankaPanda

Bases: RobotArm

__init__(self: FrankaPanda) → None

class jacobi.robots.KinovaGen37DoF

Bases: RobotArm

__init__(self: KinovaGen37DoF) → None

class jacobi.robots.KukaIiwa7

Bases: RobotArm

__init__(self: KukaIiwa7) → None

class jacobi.robots.MecademicMeca500

Bases: RobotArm

__init__(self: MecademicMeca500) → None

class jacobi.robots.UfactoryXArm7

Bases: RobotArm

__init__(self: UfactoryXArm7) → None

class jacobi.robots.UniversalUR5e

Bases: RobotArm

__init__(self: UniversalUR5e) → None

class jacobi.robots.UniversalUR10

Bases: RobotArm

__init__(self: UniversalUR10) → None

class jacobi.robots.UniversalUR10e

Bases: RobotArm

__init__(self: UniversalUR10e) → None

class jacobi.robots.UniversalUR20

Bases: RobotArm

__init__(self: UniversalUR20) → None

class jacobi.robots.YaskawaGP12

Bases: RobotArm

__init__(self: YaskawaGP12) → None

class jacobi.robots.YaskawaGP50

Bases: RobotArm

__init__(self: YaskawaGP50) → None

class jacobi.robots.YaskawaHC10

Bases: RobotArm

__init__(self: YaskawaHC10) → None

class jacobi.robots.YaskawaHC20

Bases: RobotArm

__init__(self: YaskawaHC20) → None

Warning

Custom robots are in a beta preview with rudimentary support right now. If possible, use robots from our supported robot library, as they will be significantly faster to compute and easier to use.

class jacobi.robots.CustomRobot

Bases: RobotArm

A custom robot arm that can be loaded from a URDF file.

The CustomRobot class extends the RobotArm class and provides the functionality to load a robot’s configuration from a URDF (Unified Robot Description Format) file. It also includes methods for handling inverse kinematics and filtering relevant configurations.

class JointType

Bases: pybind11_object

Members:

Revolute

Continuous

Prismatic

Fixed

__init__(self: JointType, value: int) → None

property name

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.robots.CustomRobot, degrees_of_freedom: int) -> None

2. __init__(self: jacobi.robots.CustomRobot, degrees_of_freedom: int, number_joints: int) -> None

static load_from_urdf_file(file: os.PathLike, base_link: str = 'base_link', end_link: str = 'flange') → CustomRobot

Load the robot from a URDF file

Loads a custom robot from a *.urdf file, and sets the robot arm to the kinematic chain between the given base_link and the end_link.

Parameter file:

The path to the URDF file.

Parameter base_link:

The name of the base link in the URDF.

Parameter end_link:

The name of the end link in the URDF.

Returns:

A shared pointer to the loaded robot.

property child

Possible child robot.

property config_joint_names

Names of the joints corresponding to a specific joint configuration.

Motions

class jacobi.LinearSection

Bases: pybind11_object

Represents a linear Cartesian section for either the approach to the goal or the retraction from the start.

class Approximation

Bases: pybind11_object

Whether to approximate the Cartesian linear motion in joint space for singularity-free calculation.

Members:

Always :

Never :

__init__(self: Approximation, value: int) → None

property name

__init__(self: jacobi.LinearSection, offset: jacobi.Frame, speed: float = 1.0, approximation: jacobi.LinearSection.Approximation = <Approximation.Never: 0>, smooth_transition: bool = True) → None

property offset

Relative linear cartesian offset from the reference pose.

property smooth_transition

Whether to use a smooth transition between this and the next or previous section. If false, the robot will come to a complete stop at the transition point.

property speed

Speed of the sub-motion, relative to the overall motion’s speed.

class jacobi.Motion

Bases: pybind11_object

Represents a request for a collision-free point-to-point motion.

The Motion class provides an interface for general point-to-point motion planning with arbitrary waypoints, linear approach and retraction, and task constraints. It includes parameters for the motion name, robot, start and goal points, and additional settings for motion planning, such as collision checking and soft failure handling.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.Motion, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion]) -> None

Construct a Motion with a given start and goal point.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

2. __init__(self: jacobi.Motion, robot: jacobi.Robot, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion]) -> None

Construct a Motion with a name, start and goal point.

Parameter name:

The unique name of the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

3. __init__(self: jacobi.Motion, name: str, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion]) -> None

Construct a Motion with a name, start and goal point.

Parameter name:

The unique name of the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

4. __init__(self: jacobi.Motion, name: str, robot: jacobi.Robot, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion]) -> None

Construct a Motion with a name, robot, start and goal point.

Parameter name:

The unique name of the motion.

Parameter robot:

The robot for the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

property cartesian_tcp_speed_cutoff

Optional Cartesian TCP speed (translation-only) cutoff. This is a post-processing step.

property goal

Goal point of the motion

property ignore_collisions

Whether to ignore collisions

property initial_waypoints

Optional initial waypoints to start the optimization with (don’t use with intermediate waypoints).

property linear_approach

Optional relative linear cartesian motion for approaching the goal pose.

property linear_retraction

Optional relative linear cartesian motion for retracting from the start pose.

property name

The unique name of the motion.

property orientation_loss_weight

Weight of the loss minimizing the maximizing deviation of the end- effector orientation to the target value.

property orientation_target

Target vector pointing in the direction of the end-effector (TCP) orientation in the global coordinate system.

property path_length_loss_weight

Weight of the loss minimizing the path length of the trajectory.

property robot

The robot for the motion (e.g. defines the kinematics and the joint limits).

property soft_collision_goal

Enables soft collision checking at the goal of the motion. Then, the item obstacle of the robot is allowed to be in collision at the goal point, but minimizes the time in collision and allows going into collision only once.

property soft_collision_start

Enables soft collision checking at the start of the motion. Then, the item obstacle of the robot is allowed to be in collision at the start point. The trajectory will move the item out of collision, and won’t allow a collision thereafter.

property start

Start point of the motion

property waypoints

Intermediate waypoints that the motion passes through exactly. The list of waypoints is limited to less than four, otherwise please take a look at LowLevelMotion.

class jacobi.LinearMotion

Bases: pybind11_object

Represents a request for a linear Cartesian-space motion.

The LinearMotion struct represents a request for a linear motion in Cartesian space. It consists of a start and goal point, as well as a robot to perform the motion. It provides an interface for planning singularity-free linear motion in Cartesian space between any two waypoints.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.LinearMotion, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]) -> None

Construct a linear motion with a given start, and goal.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

2. __init__(self: jacobi.LinearMotion, robot: jacobi.Robot, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]) -> None

Construct a linear motion with a given robot, start, and goal.

Parameter robot:

The robot for the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

3. __init__(self: jacobi.LinearMotion, name: str, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]) -> None

Construct a linear motion with a given name, start, and goal.

Parameter name:

The unique name of the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

4. __init__(self: jacobi.LinearMotion, name: str, robot: jacobi.Robot, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]) -> None

Construct a linear motion with a given name, robot, start, and goal.

Parameter name:

The unique name of the motion.

Parameter robot:

The robot for the motion.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

property goal

Goal point of the motion.

property ignore_collisions

Whether to ignore collisions

property name

The unique name of the motion.

property robot

The robot for the motion (e.g. defines the kinematics and the joint limits).

property start

Start point of the motion

class jacobi.LowLevelMotion

Bases: pybind11_object

Represents a request for a low-level motion.

The LinearMotion class provides an interface for very efficient planning of motion between joint-space waypoints. While low level motions are not checked for collisions, they are much faster to compute and allow for more flexible constraints such as a minimum duration parameter. This motion type is suitable for visual servoing task or other real-time control.

class ControlInterface

Bases: pybind11_object

The control interface for the motion, specifying either position or velocity control.

Members:

Position

Velocity

__init__(self: ControlInterface, value: int) → None

property name

class DurationDiscretization

Bases: pybind11_object

Members:

Continuous

Discrete

__init__(self: DurationDiscretization, value: int) → None

property name

class Synchronization

Bases: pybind11_object

The synchronization strategy for the motion, specifying either phase, time, time if necessary, or no synchronization.

Members:

Phase : Phase synchronize the DoFs when possible, else fallback to “Time”

strategy (Default)

Time : Always synchronize the DoFs to reach the target at the same time

TimeIfNecessary : Synchronize only when necessary (e.g. for non-zero target velocity or

acceleration)

None : Calculate every DoF independently

__init__(self: Synchronization, value: int) → None

property name

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.LowLevelMotion, robot: jacobi.Robot) -> None

Construct a low-level motion with a given robot.

Parameter robot:

The robot for the motion.

2. __init__(self: jacobi.LowLevelMotion, name: str) -> None

Construct a low-level motion with a given name.

Parameter name:

The unique name of the motion.

3. __init__(self: jacobi.LowLevelMotion, name: str, robot: jacobi.Robot) -> None

Construct a low-level motion with a given name, robot, start, and goal.

Parameter name:

The unique name of the motion.

Parameter robot:

The robot for the motion.

4. __init__(self: jacobi.LowLevelMotion) -> None

Default constructor.

property control_interface

The control interface for the motion.

property duration_discretization

The duration discretization strategy for the motion.

property goal

Goal waypoint of the motion.

property intermediate_positions

List of intermediate positions.

For a small number of waypoints (less than 16), the trajectory goes exactly through the intermediate waypoints. For a larger number of waypoints, first a filtering algorithm is used to keep the resulting trajectory close to the original waypoints.

property minimum_duration

A minimum duration of the motion.

property name

The unique name of the motion.

property robot

The robot for the motion (e.g. defines the kinematics and the joint limits).

property start

Start waypoint of the motion.

property synchronization

The synchronization strategy for the motion.

class jacobi.LinearPath

Bases: PathType

A path type for linear motion between two waypoints.

The LinearPath class implements the PathType interface to represent a linear path from a start pose to a goal pose. It calculates waypoints along a straight line between the two poses and supports serialization and deserialization to/from JSON.

__init__(self: LinearPath, start: Frame, goal: Frame) → None

Construct a LinearPath with a given start and goal pose.

Parameter start:

The starting pose of the linear path.

Parameter goal:

The ending pose of the linear path.

calculate_path(self: LinearPath, velocity: float, delta_time: float) → list[Frame]

Calculate the path waypoints for the linear motion.

Parameter velocity:

The velocity used for path calculation.

Parameter delta_time:

The time step used for path calculation.

Returns:

The calculated path waypoints as a sequence of Frames.

property goal

The goal pose of the linear path.

property start

The start pose of the linear path.

class jacobi.CircularPath

Bases: PathType

A circular path type with a specified start pose, circle center, normal, and rotation angle, optionally maintaining tool-to-surface orientation.

The CircularPath class implements the PathType interface to represent a circular path with a given start pose, circle center, normal to the plane of the circle, and rotation angle. This path type optionally supports maintaining tool-to-surface orientation throughout the path.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.CircularPath, start: jacobi.Frame, theta: float, center: list[float], normal: list[float], keep_tool_to_surface_orientation: bool = False) -> None

2. __init__(self: jacobi.CircularPath, start: jacobi.Frame, goal: jacobi.Frame, center: list[float], keep_tool_to_surface_orientation: bool = False) -> None

calculate_path(self: CircularPath, velocity: float, delta_time: float) → list[Frame]

Calculate the path waypoints for the circular motion.

Parameter velocity:

The velocity used for path calculation.

Parameter delta_time:

The time step used for path calculation.

Returns:

The calculated path waypoints as a sequence of Frames.

property center

The center of the circle.

property keep_tool_to_surface_orientation

Whether to maintain the tool-to-surface orientation.

property normal

The normal of the plane in which to create a circular path.

property start

The start pose of the circular path.

property theta

The rotation angle of the circular path [rad].

class jacobi.BlendedPath

Bases: PathType

A path type for linear motion between waypoints with a circular blend to ensure motion continuity, optionally maintaining tool-to-surface orientation.

The BlendedPath class implements the PathType interface to represent a path that smoothly transitions between Cartesian waypoints with circular blends. This ensures continuity of motion. This path type optionally supports maintaining tool-to-surface orientation throughout the path.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.BlendedPath, waypoints: list[jacobi.Frame], blend_radius: float, keep_tool_to_surface_orientation: bool = False) -> None

2. __init__(self: jacobi.BlendedPath, waypoints: list[jacobi.Frame], keep_tool_to_surface_orientation: bool = False) -> None

calculate_path(self: BlendedPath, velocity: float, delta_time: float) → list[Frame]

Calculate the path waypoints with piecewise linear motion and circular blends.

Parameter velocity:

The velocity used for path calculation.

Parameter delta_time:

The time step used for path calculation.

Returns:

The calculated path waypoints as a sequence of Frames.

property blend_radius

The blend radius for the circular blend.

property keep_tool_to_surface_orientation

Whether to maintain the tool-to-surface orientation.

property waypoints

The path Cartesian waypoints.

class jacobi.ArbitraryPath

Bases: PathType

A wrapper for a path with arbitrary user-provided waypoints.

The ArbitraryPath class implements the PathType interface and serves as a wrapper for a path defined by user-provided Cartesian waypoints. This class allows users to specify their own sequence of waypoints directly, without additional path calculations.

__init__(self: ArbitraryPath, path: list[Frame]) → None

Construct an ArbitraryPath with given waypoints.

Parameter path:

The Cartesian waypoints defining the path.

calculate_path(self: ArbitraryPath, velocity: float, delta_time: float) → list[Frame]

Return the user-provided waypoints as the calculated path.

Parameter velocity:

The velocity used for path calculation (not utilized in this case).

Parameter delta_time:

The time step used for path calculation (not utilized in this case).

Returns:

The waypoints provided by the user as the path.

property path

The path Cartesian waypoints.

class jacobi.PathFollowingMotion

Bases: pybind11_object

Represents a request for a Cartesian-space motion to be followed by the end-effector.

The PathFollowingMotion class provides an interface for Cartesian- space paths to be accurately followed by the robot end-effector with a constant velocity. There are four different path types that are supported: linear, circular, blended and arbitrary. The path-following motion is suitable for use cases such as welding, painting, dispensing and deburring, where constant end-effector velocity is required for successful task execution. It includes parameters for the motion name, robot, path type, velocity, and additional settings for motion planning, such as collision checking and soft failure handling.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.PathFollowingMotion) -> None

2. __init__(self: jacobi.PathFollowingMotion, path_type: jacobi.PathType, velocity: float = 50.0) -> None

3. __init__(self: jacobi.PathFollowingMotion, name: str, path_type: jacobi.PathType, velocity: float = 50.0) -> None

4. __init__(self: jacobi.PathFollowingMotion, robot: jacobi.Robot, path_type: jacobi.PathType, velocity: float = 50.0) -> None

5. __init__(self: jacobi.PathFollowingMotion, name: str, robot: jacobi.Robot, path_type: jacobi.PathType, velocity: float = 50.0) -> None

calculate_path(self: PathFollowingMotion, delta_time: float) → list[Frame]

Calculate the path waypoints based on the current feasible velocity and delta time.

Parameter delta_time:

The time step used for path calculation.

Returns:

The calculated path waypoints as a sequence of Frames.

robot_arm(self: PathFollowingMotion) → RobotArm

property check_collision

If true, the planner will check for collisions during the motion.

property feasible_velocity

The feasible velocity of the end-effector achieved after planning [m/s] (only used if soft_failure is true).

property name

The unique name of the motion.

property path_type

The Cartesian path to follow.

property reference_config

Optional reference configuration for the start state of the motion.

property robot

The robot for the motion (e.g. defines the kinematics and the joint limits).

property soft_failure

If true, the planner will adjust path velocity until a solution until velocity limits are satisfied.

property velocity

The desired velocity of the end-effector [m/s].

Motion Planning

class jacobi.Trajectory

Bases: pybind11_object

A robot’s trajectory as a list of positions, velocities and accelerations at specific times.

The Trajectory class represents a sequence of kinematic states of a robot over a specified duration. It maintains lists of positions, velocities, and accelerations at particular time stamps.

__init__(self: Trajectory, degrees_of_freedom: int) → None

Create an empty trajectory with the given degrees of freedom

Parameter dofs:

The degrees of freedom of the joint space.

append(self: Trajectory, other: Trajectory) → None

Append another trajectory to the current one.

Parameter other:

The trajectory to append.

as_table(self: Trajectory) → str

To pretty print the trajectory as a table of positions

at_time(self: Trajectory, time: float) → tuple

back(self: Trajectory) → jacobi.State

Access the last state at t=duration of the trajectory

Returns:

The last state at t=duration of the trajectory.

filter_path(self: Trajectory, max_distance: list[float]) → list[list[float]]

Filter a path of sparse waypoints from the trajectory

The path has a maximum distance per degree of freedom between the linear interpolation of the sparse waypoints and the original trajectory.

Parameter max_distance:

The maximum allowable distance between joint positions.

Returns:

std::vector<Config> A list of sparse waypoints filtered from the trajectory.

static from_json(json: str) → Trajectory

Loads a trajectory from a json string.

static from_json_file(file: os.PathLike) → Trajectory

Loads a trajectory from a *.json file.

Parameter file:

The path to the *.json file.

Returns:

Trajectory The loaded trajectory.

front(self: Trajectory) → jacobi.State

Access the first state at t=0 of the trajectory

Returns:

The first state at t=0 of the trajectory.

get_step_closest_to(self: Trajectory, position: list[float]) → int

Get step at which the trajectory is closest (in terms of the L2 norm in joint space) to the reference position

Returns:

size_t The step index of the closest position.

reverse(self: Trajectory) → Trajectory

Reverse the trajectory’s start and goal

Returns:

Trajectory A new trajectory with the start and end points reversed.

slice(self: Trajectory, start: int, steps: int) → Trajectory

Slice a trajectory starting from step start for a length of steps.

Parameter start:

The starting index of the slice.

Parameter steps:

The number of steps to include in the slice.

Returns:

Trajectory A new trajectory containing the specified slice of the original.

to_json(self: Trajectory) → str

Serializes a trajectory to a json string.

to_json_file(self: Trajectory, file: os.PathLike) → None

Saves a trajectory to a *.json file.

Parameter file:

The path to the *.json file.

update_first_position(self: Trajectory, joint_position: list[float]) → None

Update the first position of the trajectory

Parameter joint_position:

The new position to set at the start of the trajectory.

property accelerations

The joint accelerations along the trajectory.

property duration

The total duration in [s]

property id

Field for identifying trajectories (for the user)

property max_acceleration

Get the maximum acceleration along the trajectory for each degree of freedom individually

Returns:

Config The maximum acceleration value for each degree of freedom across the trajectory.

property max_position

Get the maximum position along the trajectory for each degree of freedom individually

Returns:

Config The maximum position value for each degree of freedom across the trajectory.

property max_velocity

Get the maximum velocity along the trajectory for each degree of freedom individually

Returns:

Config The maximum velocity value for each degree of freedom across the trajectory.

property min_acceleration

Get the minimum acceleration along the trajectory for each degree of freedom individually

Returns:

Config The minimum acceleration value for each degree of freedom across the trajectory.

property min_position

Get the minimum position along the trajectory for each degree of freedom individually

Returns:

Config The minimum position value for each degree of freedom across the trajectory.

property min_velocity

Get the minimum velocity along the trajectory for each degree of freedom individually

Returns:

Config The minimum velocity value for each degree of freedom across the trajectory.

property motion

Name of the motion this trajectory was planned for

property positions

The joint positions along the trajectory.

property times

The exact time stamps for the position, velocity, and acceleration values. The times will usually be sampled at the delta_time distance of the Planner class, but might deviate at the final step.

property velocities

The joint velocities along the trajectory.

class jacobi.Planner

Bases: pybind11_object

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.Planner, environment: jacobi.Environment, delta_time: float) -> None

Create a planner with an environment and a specific delta time parameter.

Parameter environment:

The environment to plan the robot motions in.

Parameter delta_time:

The time step for sampling the trajectories in [s].

2. __init__(self: jacobi.Planner, robot: jacobi.Robot, delta_time: float) -> None

Create a planner with the robot inside an empty environment and a specific delta time parameter.

Parameter robot:

The robot to plan the motions for.

Parameter delta_time:

The time step for sampling the trajectories in [s].

3. __init__(self: jacobi.Planner, environment: jacobi.Environment) -> None

Create a planner with an environment.

Parameter environment:

The environment to plan the robot motions in.

4. __init__(self: jacobi.Planner, robot: jacobi.Robot) -> None

Create a planner with the robot inside an empty environment.

Parameter robot:

The robot to plan the motions for.

add_motion(self: Planner, motion: Motion | LinearMotion | LowLevelMotion | PathFollowingMotion) → None

Add (or update when name already exists) a motion to the planner

Parameter motion:

The motion to add, can be of any type.

get_motion(self: Planner, name: str) → Motion | LinearMotion | LowLevelMotion | PathFollowingMotion

Get a motion by its name

Parameter name:

The name of the motion to retrieve.

Returns:

The AnyMotion object associated with the given name.

static load_from_json_file(file: os.PathLike, base_path: os.PathLike) → Planner

static load_from_project_file(file: os.PathLike) → Planner

Loads a planner from a project file.

Parameter file:

The path to the project file.

Returns:

A shared pointer to the loaded Planner object.

static load_from_studio(name: str) → Planner

Loads a planner from a Studio project. Make sure to have the access token set as an environment variable.

Parameter name:

The name of the Studio project.

Returns:

A shared pointer to the loaded Planner object.

load_motion_plan(self: Planner, file: os.PathLike) → None

Load a *.jacobi-plan motion plan for accelerating the planning calculation.

Parameter file:

The path to the *.jacobi-plan file to load.

plan(*args, **kwargs)

Overloaded function.

1. plan(self: jacobi.Planner, start: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion], goal: Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint, jacobi.Region, jacobi.CartesianRegion]) -> Optional[jacobi.Trajectory]

Plans a time-optimized, collision-free, and jerk-limited motion from start to goal.

Parameter start:

The start point of the motion.

Parameter goal:

The goal point of the motion.

Returns:

The computed trajectory or std::nullopt if the planning failed.

2. plan(self: jacobi.Planner, name: str, start: Optional[Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]] = None, goal: Optional[Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]] = None) -> Optional[jacobi.Trajectory]

Plans a time-optimized, collision-free, and jerk-limited motion given the motion name. In case the motion was specified by a start or goal region, the respective exact start or goal positions needs to be passed.

Parameter name:

The name of the motion to plan.

Parameter start:

The exact start position of the motion.

Parameter goal:

The exact goal position of the motion.

Returns:

The computed trajectory or std::nullopt if the planning failed.

3. plan(self: jacobi.Planner, motion: jacobi.Motion, start: Optional[Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]] = None, goal: Optional[Union[list[float], jacobi.Waypoint, jacobi.CartesianWaypoint, jacobi.MultiRobotPoint]] = None) -> Optional[jacobi.Trajectory]

Plans a collision-free point-to-point motion.

Parameter motion:

The motion to plan.

Parameter start:

The exact start position of the motion.

Parameter goal:

The exact goal position of the motion.

Returns:

The computed trajectory or std::nullopt if the planning failed.

4. plan(self: jacobi.Planner, motion: jacobi.LinearMotion) -> Optional[jacobi.Trajectory]

Plans a linear motion.

Parameter motion:

The linear motion to plan.

Returns:

The computed trajectory or std::nullopt if the planning failed.

5. plan(self: jacobi.Planner, motion: jacobi.LowLevelMotion) -> Optional[jacobi.Trajectory]

Plans a low-level motion.

Parameter motion:

The low-level motion to plan.

Returns:

The computed trajectory or std::nullopt if the planning failed.

6. plan(self: jacobi.Planner, motion: jacobi.PathFollowingMotion) -> Optional[jacobi.Trajectory]

Plans a path-following motion.

Parameter motion:

The path-following motion to plan.

Returns:

The computed trajectory or std::nullopt if the planning failed.

7. plan(self: jacobi.Planner, motions: list[Union[jacobi.Motion, jacobi.LinearMotion, jacobi.LowLevelMotion, jacobi.PathFollowingMotion]]) -> Optional[list[jacobi.Trajectory]]

Plans a feasible sequence of motions.

Parameter motions:

The sequence of motions to plan.

Returns:

The computed sequence of trajectories or std::nullopt if the planning failed.

set_seed(self: Planner, seed: int | None) → None

Set the seed of the planner’s random number generator

Parameter seed:

The seed to set. If no seed is provided, the generator will be seeded with a random value.

transfer_trajectory(self: Planner, trajectory: Trajectory, robot_from: RobotArm, robot_to: RobotArm, offset: Frame = Frame()) → Trajectory | None

Transfers a trajectory from one robot to another.

Calculate a trajectory for another robot that follows the TCP of the original robot given the trajectory. This method does not check for constraints of the new robot.

Parameter trajectory:

The trajectory to follow.

Parameter robot_from:

The original robot to transfer from.

Parameter robot_to:

The new robot to transfer to.

Parameter offset:

Optional offset between the from and to robot’s TCP.

Returns:

The transferred trajectory or std::nullopt if the planning failed.

property delta_time

The time step for sampling the trajectories in [s]. Usually, this should correspond to the control rate of the robot.

property environment

The current environment to plan robot motions in

property initial_perturbation_scale

Initial perturbation for the trajectory optimization

property last_calculation_duration

The calculation duration of the last full trajectory computation

property last_calculation_result

Result of the last trajectory computation

property max_break_steps

Max number of steps without improvement before early stopping

property max_calculation_duration

The maximum compute budget (that won’t be exceeded)

property max_optimization_steps

Maximum number of optimization steps

property meaningful_loss_improvement

A meaningful relative improvement to avoid stopping

property min_calculation_duration

The minimum compute budget (that the planner can use regardless)

property perturbation_change_steps

Steps without improvement after which the perturbation scale is adapted

property perturbation_scale_change

Change of the perturbation if no improvement could be found recently

property pre_eps_collision

Resolution of the collision checking in the pre-planning stage [rad]

property pre_eps_steering

Steering epsilon in the pre-planning stage [rad]

property pre_max_steps

Maximum number of steps in the pre-planning stage before a solution is not found

property pre_optimization_steps

Number of samples for optimization after finding a solution in the pre-plannning stage

Studio Live

class jacobi.Studio

Bases: pybind11_object

Helper class to connect and visualize trajectories and events in Jacobi Studio.

The Studio class provides functionality to connect to Jacobi Studio via a WebSocket, and to visualize trajectories and events. It manages the connection, handles incoming and outgoing messages, and allows the user to create and execute actions within Jacobi Studio.

class Action

Bases: pybind11_object

An action that can be performed in Jacobi Studio.

The Action class represents an action in Jacobi Studio, such as setting a robot’s joint position, adding an obstacle, or manipulating the environment. An action can contain multiple commands, allowing for complex interactions in Studio.

__init__(*args, **kwargs)

class Events

Bases: pybind11_object

A container that maps a specific timing to one or multiple actions. The static methods of this class do not change the visualization in Jacobi Studio immediately, but only return an action that can be executed later (e.g. alongside a trajectory).

The Events struct allows for scheduling actions in Jacobi Studio at specific times. Static methods are provided to create various actions, which can be executed later.

__init__(self: Events) → None

A container that maps a specific timing to one or multiple actions. The static methods of this class do not change the visualization in Jacobi Studio immediately, but only return an action that can be executed later (e.g. alongside a trajectory).

The Events struct allows for scheduling actions in Jacobi Studio at specific times. Static methods are provided to create various actions, which can be executed later.

static add_camera(camera: jacobi.Camera) → Action

Returns an action that adds a camera.

Parameter camera:

The camera to be added.

Returns:

The action to add the camera.

static add_obstacle(obstacle: Obstacle) → Action

Returns an action that adds the given obstacle to the environment.

Parameter obstacle:

The obstacle to be added.

Returns:

The action to add the obstacle.

static add_robot(robot: Robot) → Action

Returns an action that adds the given robot to the environment.

Parameter robot:

The robot to be added.

Returns:

The action to add the robot.

static add_robot_path(points: list[list[float]], robot: Robot = None, name: str = '', color: str = '', stroke: float = -1.0, arrow_size: float = 1.0) → Action

Returns an action that adds a visualization of a path for the given robot.

Parameter points:

The points defining the path.

Parameter robot:

Optional robot associated with the path.

Parameter name:

Optional name for the path.

Parameter color:

Optional color for the path visualization.

Parameter stroke:

Optional stroke width for the path visualization.

Parameter arrow_size:

Optional size of arrow for end of path

Returns:

The action to add the robot path visualization.

static add_waypoint(point: list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion) → Action

Returns an action that adds the given Cartesian waypoint to the environment.

Parameter point:

The Cartesian waypoint to be added.

Returns:

The action to add the Cartesian waypoint.

static remove_camera(camera: jacobi.Camera) → Action

Returns an action that removes a camera.

Parameter camera:

The camera to be removed.

Returns:

The action to remove the camera.

static remove_obstacle(obstacle: Obstacle) → Action

Returns an action that removes the given obstacle (by name) from the environment.

Parameter obstacle:

The obstacle to be removed.

Returns:

The action to remove the obstacle.

static remove_robot_path(robot: Robot, name: str) → Action

Returns an action that removes a visualization of a named path for the given robot.

Parameter robot:

The robot associated with the path.

Parameter name:

The name of the path to be removed.

Returns:

The action to remove the robot path visualization.

static set_camera_depth_map(depths: list[list[float]], x: float, y: float, camera: jacobi.Camera = None) → Action

Returns an action that sets the depth map visualization of a camera.

Parameter depths:

The depth map data.

Parameter x:

The x-coordinate for the depth map.

Parameter y:

The y-coordinate for the depth map.

Parameter camera:

Optional camera associated with the depth map.

Returns:

The action to set the camera depth map.

static set_camera_image_encoded(image: str, camera: jacobi.Camera) → Action

Returns an action that sets an image for a camera encoded as a string.

Parameter image:

The encoded image to be set.

Parameter camera:

Optional camera associated with the image.

Returns:

The action to set the camera image.

static set_io_signal(name: str, value: int | float, robot: Robot = None) → Action

Returns an action that sets an I/O signal of the given robot, or the last active robot instead.

Parameter name:

The name of the I/O signal.

Parameter value:

The value to be set for the I/O signal.

Parameter robot:

Optional robot associated with the I/O signal.

Returns:

The action to set the I/O signal.

static set_item(obstacle: Obstacle | None, robot: Robot = None) → Action

Returns an action that sets the item obstacle of the given robot, or the last active robot instead.

Parameter obstacle:

Optional obstacle to be set.

Parameter robot:

Optional robot associated with the obstacle.

Returns:

The action to set the item obstacle.

static set_joint_position(joint_position: list[float], robot: Robot = None) → Action

Returns an action that sets the joint position of the given robot, or the last active robot instead.

Parameter joint_position:

The desired joint position.

Parameter robot:

Optional robot to set the joint position for.

Returns:

The action to set the joint position.

static set_material(material: str, robot: Robot = None) → Action

Returns an action that sets the material of the given robot, or the last active robot instead.

Parameter material:

The material to be set.

Parameter robot:

Optional robot associated with the material.

Returns:

The action to set the material.

static update_camera(camera: jacobi.Camera) → Action

Returns an action that updates a camera with the same name.

Parameter camera:

The camera to be updated.

Returns:

The action to update the camera.

static update_obstacle(obstacle: Obstacle) → Action

Returns an action that updates the obstacle with the same name.

Parameter obstacle:

The obstacle to be updated.

Returns:

The action to update the obstacle.

__init__(self: Studio, auto_connect: bool = True, timeout: float = 3.0) → None

Interface Jacobi Studio via code. Connects to Jacobi Studio automatically - please make sure to enable the Studio Live feature in the Jacobi Studio settings.

Parameter auto_connect:

Whether to connect to Studio Live automatically.

Parameter timeout:

The timeout for connecting to Studio Live.

add_camera(self: Studio, camera: jacobi.Camera) → bool

Adds a camera in Jacobi Studio.

Parameter camera:

The camera to be added.

add_obstacle(self: Studio, obstacle: Obstacle) → bool

Adds the given obstacle to the environment.

Parameter obstacle:

The obstacle to be added.

add_robot(self: Studio, robot: Robot) → bool

Adds the given robot to the environment.

Parameter robot:

The robot to be added.

add_robot_path(self: Studio, points: list[list[float]], robot: Robot = None, name: str = '', color: str = '', stroke: float = -1.0, arrow_size: float = 1.0) → bool

Adds a visualization of a path for the given robot.

Parameter points:

The points defining the path.

Parameter robot:

Optional robot associated with the path.

Parameter name:

Optional name for the path.

Parameter color:

Optional color for the path visualization.

Parameter stroke:

Optional stroke width for the path visualization.

Parameter arrow_size:

Optional size of arrow for end of path

add_waypoint(self: Studio, point: list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion) → bool

Adds the given Cartesian waypoint to the environment.

Parameter point:

The Cartesian waypoint to be added.

get_camera_image_encoded(self: Studio, stream: jacobi.CameraStream, camera: jacobi.Camera) → str

Get an image from a camera encoded as a string.

Parameter stream:

The type of camera stream to get.

Parameter camera:

Optional camera to get the image from.

Returns:

The encoded image from the camera.

get_joint_position(self: Studio, robot: Robot = None) → list[float]

Get the joint position of a robot.

Parameter robot:

Optional robot to get the joint position for.

Returns:

The joint position of the robot.

reconnect(self: Studio, timeout: float = 3.0) → bool

Reconnect to Studio Live

Parameter timeout:

The timeout for reconnecting to Studio Live.

Returns:

Whether the reconnection was successful.

remove_camera(self: Studio, camera: jacobi.Camera) → bool

Removes a camera in Jacobi Studio.

Parameter camera:

The camera to be removed.

remove_obstacle(self: Studio, obstacle: Obstacle) → bool

Removes the given obstacle (by name) from the environment.

Parameter obstacle:

The obstacle to be removed.

remove_robot_path(self: Studio, robot: Robot, name: str) → bool

Removes a named visualization of a path for the given robot.

Parameter robot:

The robot associated with the path.

Parameter name:

The name of the path to be removed.

reset(self: Studio) → bool

Resets the environment to the state before a trajectory or events were run. In particular, it removes all obstacles there were added dynamically.

run_action(self: Studio, action: Action) → bool

Run the given action in Jacobi Studio.

Parameter action:

The action to be run.

Returns:

Was the action successfully sent to Studio?

run_events(self: Studio, events: Events) → bool

Run the events at the specified timings in Jacobi Studio.

Parameter events:

The events to be run at the specified timings.

run_trajectories(self: Studio, trajectories: list[tuple[Trajectory, Robot]], events: Events = Studio.Events(), loop_forever: bool = False) → bool

run_trajectory(self: Studio, trajectory: Trajectory, events: Events = Studio.Events(), loop_forever: bool = False, robot: Robot = None) → bool

Runs a trajectory for the given robot (or the last active robot) in Jacobi Studio, alongside the events at the specified timings. Optionally, the visualization can be looped.

Parameter trajectory:

The trajectory to be run.

Parameter events:

The events to be run at the specified timings.

Parameter loop_forever:

Whether to loop the visualization forever.

Parameter robot:

Optional robot to run the trajectory for.

set_camera_depth_map(self: Studio, depths: list[list[float]], x: float, y: float, camera: jacobi.Camera = None) → bool

Sets the depth map visualization of a camera.

Parameter depths:

The depth map data.

Parameter x:

The x-coordinate for the depth map.

Parameter y:

The y-coordinate for the depth map.

Parameter camera:

Optional camera associated with the depth map.

set_camera_image_encoded(self: Studio, image: str, camera: jacobi.Camera) → bool

Sets an image for a camera encoded as a string.

Parameter image:

The encoded image to be set.

Parameter camera:

Optional camera associated with the image.

set_camera_point_cloud(self: Studio, points: list[float], camera: jacobi.Camera = None) → bool

Sets the point cloud visualization of a camera.

Parameter points:

The point cloud data.

Parameter camera:

Optional camera associated with the point cloud.

set_io_signal(self: Studio, name: str, value: int | float, robot: Robot = None) → bool

Sets an I/O signal of the given robot, or the last active robot instead.

Parameter name:

The name of the I/O signal.

Parameter value:

The value to be set for the I/O signal.

Parameter robot:

Optional robot associated with the I/O signal.

set_item(self: Studio, obstacle: Obstacle | None, robot: Robot = None) → bool

Sets the item obstacle of the given robot, or the last active robot instead.

Parameter obstacle:

Optional obstacle to be set.

Parameter robot:

Optional robot associated with the obstacle.

set_joint_position(self: Studio, joint_position: list[float], robot: Robot = None) → bool

Sets the joint position of the given robot, or the last active robot instead.

Parameter joint_position:

The desired joint position.

Parameter robot:

Optional robot to set the joint position for.

set_material(self: Studio, material: str, robot: Robot = None) → bool

Sets the material of the given robot, or the last active robot instead.

Parameter material:

The material to be set.

Parameter robot:

Optional robot associated with the material.

update_camera(self: Studio, camera: jacobi.Camera) → bool

Updates the camera with the same name in Jacobi Studio.

Parameter camera:

The camera to be updated.

update_obstacle(self: Studio, obstacle: Obstacle) → bool

Updates the obstacle with the same name.

Parameter obstacle:

The obstacle to be updated.

property is_connected

Whether the library is connected to Studio Live

Returns:

Whether the library is connected to Studio Live.

property port

Port of the websocket connection

property speedup

A factor to speed up or slow down running trajectories or events.

class jacobi.Studio.Action

Bases: pybind11_object

An action that can be performed in Jacobi Studio.

The Action class represents an action in Jacobi Studio, such as setting a robot’s joint position, adding an obstacle, or manipulating the environment. An action can contain multiple commands, allowing for complex interactions in Studio.

__init__(*args, **kwargs)

class jacobi.Studio.Events

Bases: pybind11_object

A container that maps a specific timing to one or multiple actions. The static methods of this class do not change the visualization in Jacobi Studio immediately, but only return an action that can be executed later (e.g. alongside a trajectory).

The Events struct allows for scheduling actions in Jacobi Studio at specific times. Static methods are provided to create various actions, which can be executed later.

__init__(self: Events) → None

A container that maps a specific timing to one or multiple actions. The static methods of this class do not change the visualization in Jacobi Studio immediately, but only return an action that can be executed later (e.g. alongside a trajectory).

The Events struct allows for scheduling actions in Jacobi Studio at specific times. Static methods are provided to create various actions, which can be executed later.

static add_camera(camera: jacobi.Camera) → Action

Returns an action that adds a camera.

Parameter camera:

The camera to be added.

Returns:

The action to add the camera.

static add_obstacle(obstacle: Obstacle) → Action

Returns an action that adds the given obstacle to the environment.

Parameter obstacle:

The obstacle to be added.

Returns:

The action to add the obstacle.

static add_robot(robot: Robot) → Action

Returns an action that adds the given robot to the environment.

Parameter robot:

The robot to be added.

Returns:

The action to add the robot.

static add_robot_path(points: list[list[float]], robot: Robot = None, name: str = '', color: str = '', stroke: float = -1.0, arrow_size: float = 1.0) → Action

Returns an action that adds a visualization of a path for the given robot.

Parameter points:

The points defining the path.

Parameter robot:

Optional robot associated with the path.

Parameter name:

Optional name for the path.

Parameter color:

Optional color for the path visualization.

Parameter stroke:

Optional stroke width for the path visualization.

Parameter arrow_size:

Optional size of arrow for end of path

Returns:

The action to add the robot path visualization.

static add_waypoint(point: list[float] | Waypoint | CartesianWaypoint | jacobi.MultiRobotPoint | Region | CartesianRegion) → Action

Returns an action that adds the given Cartesian waypoint to the environment.

Parameter point:

The Cartesian waypoint to be added.

Returns:

The action to add the Cartesian waypoint.

static remove_camera(camera: jacobi.Camera) → Action

Returns an action that removes a camera.

Parameter camera:

The camera to be removed.

Returns:

The action to remove the camera.

static remove_obstacle(obstacle: Obstacle) → Action

Returns an action that removes the given obstacle (by name) from the environment.

Parameter obstacle:

The obstacle to be removed.

Returns:

The action to remove the obstacle.

static remove_robot_path(robot: Robot, name: str) → Action

Returns an action that removes a visualization of a named path for the given robot.

Parameter robot:

The robot associated with the path.

Parameter name:

The name of the path to be removed.

Returns:

The action to remove the robot path visualization.

static set_camera_depth_map(depths: list[list[float]], x: float, y: float, camera: jacobi.Camera = None) → Action

Returns an action that sets the depth map visualization of a camera.

Parameter depths:

The depth map data.

Parameter x:

The x-coordinate for the depth map.

Parameter y:

The y-coordinate for the depth map.

Parameter camera:

Optional camera associated with the depth map.

Returns:

The action to set the camera depth map.

static set_camera_image_encoded(image: str, camera: jacobi.Camera) → Action

Returns an action that sets an image for a camera encoded as a string.

Parameter image:

The encoded image to be set.

Parameter camera:

Optional camera associated with the image.

Returns:

The action to set the camera image.

static set_io_signal(name: str, value: int | float, robot: Robot = None) → Action

Returns an action that sets an I/O signal of the given robot, or the last active robot instead.

Parameter name:

The name of the I/O signal.

Parameter value:

The value to be set for the I/O signal.

Parameter robot:

Optional robot associated with the I/O signal.

Returns:

The action to set the I/O signal.

static set_item(obstacle: Obstacle | None, robot: Robot = None) → Action

Returns an action that sets the item obstacle of the given robot, or the last active robot instead.

Parameter obstacle:

Optional obstacle to be set.

Parameter robot:

Optional robot associated with the obstacle.

Returns:

The action to set the item obstacle.

static set_joint_position(joint_position: list[float], robot: Robot = None) → Action

Returns an action that sets the joint position of the given robot, or the last active robot instead.

Parameter joint_position:

The desired joint position.

Parameter robot:

Optional robot to set the joint position for.

Returns:

The action to set the joint position.

static set_material(material: str, robot: Robot = None) → Action

Returns an action that sets the material of the given robot, or the last active robot instead.

Parameter material:

The material to be set.

Parameter robot:

Optional robot associated with the material.

Returns:

The action to set the material.

static update_camera(camera: jacobi.Camera) → Action

Returns an action that updates a camera with the same name.

Parameter camera:

The camera to be updated.

Returns:

The action to update the camera.

static update_obstacle(obstacle: Obstacle) → Action

Returns an action that updates the obstacle with the same name.

Parameter obstacle:

The obstacle to be updated.

Returns:

The action to update the obstacle.