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]

Deprecated since version 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.

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

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

Bases: pybind11_object

A depth map collision object.

The DepthMap struct represents a 3D collision object based on a depth map, which is essentially a grid of depth values.

__init__(self: DepthMap, depths: list[list[float]], x: float, y: float) → None

Construct a depth map with the given data.

Parameter depths:

The matrix of depth values.

Parameter x:

The size of the depth map along the x-axis.

Parameter y:

The size of the depth map along the y-axis.

property depths

Matrix containing the depth values at evenly spaced grid points.

property max_depth

Maximum depth to check for collisions [m].

This value sets the maximum depth that will be considered during collision checking. Any depth greater than this value will be ignored. The default value is 100 meters.

property x

Size along the x-axis [m].

property y

Size along the y-axis [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.MeshFile

Bases: pybind11_object

A collision object loaded from a file.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: jacobi.MeshFile, path: os.PathLike, scale: Optional[float] = None) -> None

Load a file obstacle.

Parameter path:

The path to the collision file (*.obj).

Parameter scale:

Optional scale to apply when loading the object.

2. __init__(self: jacobi.MeshFile, visual_path: os.PathLike, collision_path: os.PathLike, scale: Optional[float] = None) -> None

Load a file obstacle.

Parameter visual_path:

The path to the visual file.

Parameter collision_path:

The path to the collision file (*.obj).

Parameter scale:

Optional scale to apply when loading the object.

property collision_reference

The reference to the collision file

property inside_project

Indicates if the file is part of a Jacobi Studio project. Then, the file content is not uploaded when referencing the file in Studio live.

property original_reference

The reference to the original file

property visual_reference

The reference to a visual file

class jacobi.PointCloud

Bases: pybind11_object

__init__(self: PointCloud, points: list[Annotated[list[float], FixedSize(3)]], resolution: float = 0.01) → None

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.MeshFile, origin: jacobi.Frame = Frame(), color: str = ‘000000’, safety_margin: float = 0.0) -> None

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

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

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

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

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

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

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

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

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

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

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

with_name(self: Obstacle, name: str) → Obstacle

Clone the current obstacle and update some parameters.

Creates a copy of the current obstacle and updates its name. This function is useful for creating modified versions of an obstacle without altering the original object.

Parameter name:

The new name for the cloned obstacle.

Returns:

Obstacle A new Obstacle instance with the updated origin.

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

Clone the current obstacle and set the new origin.

Creates a copy of the current obstacle and updates its origin to the provided frame. This function is useful for creating modified versions of an obstacle without altering the original object.

Parameter origin:

The new pose (origin) for the cloned obstacle.

Returns:

Obstacle A new Obstacle instance with the updated origin.

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