Python API Reference

You can call help to get the definitions directly from your currently installed Zivid Motion release:

>>> import zividmotion
>>> help(zividmotion.Planner)

Or if you want to look up the entire API at once:

>>> from zividmotion import zividmotion
>>> help(zividmotion)

Units of Measurement

All units in the Zivid Motion API are SI units, meaning meters for length and position and radians for angles.

Top-level Classes

class zividmotion.zividmotion.Application

Manager class for Zivid Motion.

The Application class manages resources used by the Zivid Motion. It is required to have one instance of this class alive while using Zivid Motion. Using any part of Zivid Motion without a live Application is undefined behavior.

It is not possible to have more than one Application instance at a time. Creating a second Application instance before the first Application instance has been destroyed will trigger an exception.

__enter__(self: zividmotion.zividmotion.Application) → zividmotion.zividmotion.Application

Enter the runtime context related to this object

__exit__(self: zividmotion.zividmotion.Application, arg0: type | None, arg1: object | None, arg2: object | None) → None

Exit the runtime context related to this object

create_planner(self: zividmotion.zividmotion.Application, planner_settings: Zivid::Motion::PlannerSettings) → Zivid::Motion::Planner

Initializes a Planner instance from planner settings.

Args:

planner_settings (PlannerSettings): Planner settings

Returns:

Planner

release(self: zividmotion.zividmotion.Application) → None

Releases the resources used by the application.

After calling this method, the Application instance should not be used anymore. If you want to use Zivid Motion again, please instantiate a new Application object.

Returns:

None

to_string(self: zividmotion.zividmotion.Application) → str

class zividmotion.zividmotion.Planner

clear_carried_object(self: zividmotion.zividmotion.Planner) → None

Clears the carried object from the robot’s collision model.

Returns:

None

clear_obstacles(self: zividmotion.zividmotion.Planner) → None

Clears all registered obstacles from the planner’s collision model.

Returns:

None

clear_replaceable_tool(self: zividmotion.zividmotion.Planner) → None

Clears the replaceable tool from the robot’s collision model.

Returns:

None

clip_point_cloud_with_box(self: zividmotion.zividmotion.Planner, box: Zivid::Motion::BottomCenteredTransformedBox) → None

Updates the environment point cloud by removing all points inside the specified box. This is useful when picking up objects from the scene in e.g. de-palletizing applications, where the object being picked up should no longer be considered part of the environment.

Args:

box (BottomCenteredTransformedBox): The box volume where points should be removed. The transform is defined relative to the cell base frame.

Returns:

None

clip_point_cloud_with_mesh(self: zividmotion.zividmotion.Planner, transform: zividmotion.zividmotion.Pose, mesh: zividmotion.zividmotion.Mesh) → None

Updates the environment point cloud by removing all points inside the specified mesh. This is useful when picking up objects from the scene in e.g. de-palletizing applications, where the object being picked up should no longer be considered part of the environment.

Args:

transform (Pose): The transformation from the cell base frame to the mesh.

mesh (Mesh): The mesh to clip with. Note: The mesh must be closed. Using a mesh that is not closed is currently undefined behavior.

Returns:

None

compute_inverse_kinematics(self: zividmotion.zividmotion.Planner, poses: list[zividmotion.zividmotion.Pose], reference_configuration: zividmotion.zividmotion.Configuration) → zividmotion.zividmotion.Goals

Computes the robot’s joint configurations corresponding to the given TCP poses

This method performs inverse kinematics to find joint configurations. There are possibly multiple joint configurations that correspond to the same TCP pose, denoted by different robot postures. The reference configuration is used to select which posture the solution should be computed for.

Args:

poses (list[Pose]): The poses for which the corresponding configurations will be computed

reference_configuration (Configuration): A reference configuration used to preserve the robot’s posture

Returns:

Goals: An object containing one IK result per input pose. The result is the configuration that represents the desired pose with the same posture as the reference configuration, or None if no such solution is found.

export_api_log(self: zividmotion.zividmotion.Planner, output_directory: os.PathLike | None = None) → os.PathLike

Exports and saves the API log to file.

Args:

output_directory (Optional[os.PathLike]): If specified, overrides the default output directory specified in RuntimeConfiguration.yaml.

Returns:

os.PathLike: The path to the stored API log file.

get_tcp(self: zividmotion.zividmotion.Planner) → zividmotion.zividmotion.Tcp

Returns the current Tool Center Point of the robot.

Returns:

Tcp: The current TCP.

path(self: zividmotion.zividmotion.Planner, initial_state: zividmotion.zividmotion.InitialState, request: Zivid::Motion::PathRequest) → zividmotion.zividmotion.PathResult

Calculates a path to one of multiple goal configurations from the initial state

Args:

initial_state (InitialState): The initial state for the path

request (PathRequest): Request for the path call

Returns:

PathResult

replay_api_log(self: zividmotion.zividmotion.Planner, path: os.PathLike) → None

Replays a previously exported API log file.

Restores the environment state (obstacles, TCP, carried object, replaceable tool, attachments) from the log, then replays all recorded API calls.

Args:

path (os.PathLike): The path to the API log file to replay.

Returns:

None

set_attachments(self: zividmotion.zividmotion.Planner, attachments: list[str]) → None

Sets the active attachments connected to the last link of the robot in the robot’s collision model. Multiple attachments can be added. Only attachments defined in the configuration file can be added.

Args:

attachments (list[str]): Specifies the name of the attachments to be set. Only attachments defined in the configuration file can be set. If an empty list is provided, all attachments are removed.

Returns:

None

set_carried_object(self: zividmotion.zividmotion.Planner, carried_object: zividmotion.zividmotion.Mesh) → None

Updates the robot’s collision model with the carried object it’s now holding. The carried object geometry is defined in the robot TCP frame.

Args:

carried_object (Mesh): The mesh of the carried object to be set.

Returns:

None

set_obstacles(self: zividmotion.zividmotion.Planner, obstacles: list[zividmotion.zividmotion.Obstacle]) → None

Register objects in the environment for collision avoidance.

Obstacles are unique by name, if you set a new obstacle with the same name as an existing obstacle, the existing one will be replaced. When possible, it is preferred to set all obstacles at once with a single call, rather than iterative calls to this method which will be slower.

For colored obstacles, the alpha value is ignored. Note that adding color also has some overhead and is therefore not recommended in performance-critical code.

Args:

obstacles (list[Obstacle]): Obstacles

Returns:

None

set_replaceable_tool(self: zividmotion.zividmotion.Planner, replaceable_tool: zividmotion.zividmotion.Mesh, compliant_section: zividmotion.zividmotion.Mesh | None = None) → None

Updates the robot’s collision model with the current configuration of a modifiable or exchangeable end-effector tool. The replaceable tool geometry is defined in the robot flange frame.

Args:

replaceable_tool (Mesh): The mesh of the rigid section of the replaceable tool to be set.

compliant_section (Optional[Mesh]): Optional mesh representing the compliant geometry of the tool element during Touch motions. This could represent the deformable part of a suction tool. Environment contact will be allowed for the specified geometry during Touch motions, while it will be considered rigid all other times.

Returns:

None

set_tcp(self: zividmotion.zividmotion.Planner, tcp: zividmotion.zividmotion.Tcp) → None

Updates the current Tool Center Point of the robot. The new TCP frame is used for path planning to goal poses, and it is the reference frame for setting carried objects.

Args:

tcp (Tcp): The TCP to be set.

Returns:

None

to_string(self: zividmotion.zividmotion.Planner) → str

class zividmotion.zividmotion.Visualizer

Visualizer for viewing a robot cell.

The Visualizer opens a window that displays a robot cell. The window remains open until the user closes it or the Visualizer is destroyed. The destructor will immediately close the window if it is still open.

static view_cell(application: zividmotion.zividmotion.Application, cell_name: str) → zividmotion.zividmotion.Visualizer

Opens a visualization window for the given cell.

Use this overload to visualize a cell before planning. To visualize a cell while planning, use Visualizer.view_planner() instead.

Args:

application (Application): The Zivid Motion Application instance

cell_name (str): The name of the cell to visualize

Returns:

Visualizer: A Visualizer instance that manages the visualization window

static view_planner(planner: zividmotion.zividmotion.Planner) → zividmotion.zividmotion.Visualizer

Opens a visualization window for a running Planner.

Use this overload to visualize a planner during path planning. To visualize a cell before generation, use Visualizer.view_cell() instead. The planner must remain alive for the lifetime of the Visualizer.

Args:

planner (Planner): The Planner instance to visualize

Returns:

Visualizer: A Visualizer instance that manages the visualization window

wait(self: zividmotion.zividmotion.Visualizer) → None

Blocks until the user closes the visualization window.

If the window has already been closed, this method returns immediately.

Returns:

None

Helper Classes and Structs

class zividmotion.zividmotion.InitialState

Represents the context required for path planning. It is used as an argument to the Planner.path() method.

The InitialState class encapsulates the start configuration or the result of a path planning operation. It is used to provide the necessary context for planning paths to goal configurations.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: zividmotion.zividmotion.InitialState, start_configuration: zividmotion.zividmotion.Configuration) -> None

   Initializes the InitialState from a start Configuration.

   This should only be utilized when a previous path result is not available. For consecutive motions, it is recommended to use the PathResult constructor.

   Args:

   start_configuration (Configuration): The robot’s start configuration for the path planning

   Returns:

   None

2. __init__(self: zividmotion.zividmotion.InitialState, previous_result: zividmotion.zividmotion.PathResult) -> None

   Initializes the InitialState from a PathResult.

   This overload is intended for consecutive robot motions. It requires that the provided PathResult has status Success.

   Args:

   previous_result (PathResult): A previous successful PathResult

   Returns:

   None

static from_touch(start_configuration: zividmotion.zividmotion.Configuration) → zividmotion.zividmotion.InitialState

Initializes the InitialState from a start Configuration in touch. In contrast to the regular constructor, this function is used when the robot is in a touch state. This should only be utilized when a previous path result is not available. For consecutive motions, it is recommended to use the PathResult constructor.

Args:

start_configuration (Configuration): The robot’s start configuration for the path planning in touch

Returns:

InitialState

to_string(self: zividmotion.zividmotion.InitialState) → str

class zividmotion.zividmotion.PathRequest

Request to pass to a path call.

__init__(self: zividmotion.zividmotion.PathRequest, goals: zividmotion.zividmotion.Goals, type: zividmotion.zividmotion.PathRequest.Type = <Type.free: 0>, goal_prioritization_method: zividmotion.zividmotion.PathRequest.GoalPrioritizationMethod = <GoalPrioritizationMethod.shortestPath: 1>, retract_direction: Optional[zividmotion.zividmotion.Vector3f] = None, description: Optional[str] = None, max_carried_object_compression_distance: Optional[float] = None) → None

Initializes a PathRequest instance.

Args:

goals (Goals): The goals to plan to. The path will be planned according to the selected goal prioritization method.

type (Type): The motion type. Defaults to Type.free.

goal_prioritization_method (GoalPrioritizationMethod): Decides which goal is used when multiple reachable goals are provided to the path call. Defaults to GoalPrioritizationMethod.shortestPath.

retract_direction (Vector3f, optional): Optional retract direction when retracting from a Touch configuration. When retracting from Touch, this field can be used to specify the desired retraction direction when clearing the surrounding objects. If not provided, the retract direction will be calculated based on the parameters specified in RegionOfInterest. The direction should be given in the cell base frame.

description (str, optional): Description can be used to easily distinguish between path calls in the visualizer.

max_carried_object_compression_distance (float, optional): Optional parameter for specifying the maximum compression distance, beyond initial contact, for the carried object along the Touch approach.

Returns:

None

property description

Description can be used to easily distinguish between path calls in the visualizer.

Returns:

Optional[str]

property goal_prioritization_method

Decides which goal is used when multiple reachable goals are provided to the path call.

Returns:

GoalPrioritizationMethod

property goals

The goals to plan to.

The path will be planned according to the selected goal prioritization method.

Returns:

Goals

property max_carried_object_compression_distance

Optional parameter for specifying the maximum compression distance, beyond initial contact, for the carried object along the Touch approach.

Returns:

Optional[float]

property retract_direction

Optional retract direction when retracting from a Touch configuration.

When retracting from Touch, this field can be used to specify the desired retraction direction when clearing the surrounding objects. If not provided, the retract direction will be calculated based on the parameters specified in RegionOfInterest. The direction should be given in the cell base frame.

Returns:

Optional[Vector3f]

to_string(self: zividmotion.zividmotion.PathRequest) → str

property type

Decides the motion type.

Returns:

Type

class PathRequest.Type

free

For moving in free space.

touch

For interacting with the environment, like gripping or placing an object. A touch call will include a linear motion at the end of the trajectory to approach the object safely. If the InitialState for the path call is constructed from a touch result, then the next trajectory will also start with a linear retraction.

class PathRequest.GoalPrioritizationMethod

listOrder

Among the reachable goals, the one that appears first in the list of goals is selected.

shortestPath

Among the reachable goals, the one that gives the shortest trajectory is selected.

class zividmotion.zividmotion.BlendRadius

The blend radius for a waypoint guaranteed to give a collision-free blending motion.

See Blending parameters for how to interpret these values for a particular robot type.

__init__(self: zividmotion.zividmotion.BlendRadius, entry: float = 0.0, exit: float = 0.0) → None

property entry

The distance from the waypoint to the point along the trajectory from the previous waypoint to the current one where safe blending can start.

Returns:

float

property exit

The distance from the waypoint to the point along the trajectory from the current waypoint to the next one where safe blending must end.

Returns:

float

to_string(self: zividmotion.zividmotion.BlendRadius) → str

class zividmotion.zividmotion.Waypoint

A waypoint in joint space, describing where and how the robot should move as part of a path.

property blend_radius

The blend radius for this waypoint guaranteed to give a collision-free blending motion.

See Blending parameters for how to interpret these values for a particular robot type.

Do not use a smaller non-zero blend radius than what is reported. Either use the value(s) provided or zero. Smaller non-zero values are not guaranteed to give collision-free blending motions in all scenarios.

Note that the blend radius will never be more than half the distance between consecutive waypoints.

Returns:

BlendRadius

property configuration

The joint configuration of the waypoint.

Returns:

Configuration

property movement

Describes with what movement type the robot should move to this waypoint.

Note that this can affect how the blend_radius should be interpreted for both this and the previous waypoint in the path.

Returns:

Movement

to_string(self: zividmotion.zividmotion.Waypoint) → str

class Waypoint.Movement

joint

The robot moves linearly in joint space (often called move_j).

linear

The robot moves linearly in cartesian space (often called move_l).

class zividmotion.zividmotion.Path

An ordered sequence of waypoints describing how the robot should move.

Returned from PathResult.path. Supports len(), indexing and iteration over the contained Waypoints.

to_string(self: zividmotion.zividmotion.Path) → str

class zividmotion.zividmotion.PathResult

PathResult is the result of calculating a path to a set of potential goals. It’s the return value from Planner.path().

__bool__(self: zividmotion.zividmotion.PathResult) → bool

Returns true if there is no planning error, false otherwise.

Makes it convenient to do if path_result: ...

Returns:

bool: A boolean indicating successful status.

property error

The PathResult will have an error set if the planner did not find a collision-free path to any of the goals.

Returns:

Optional[Error]: The error of the path result, if any.

property final_configuration

Returns the final configuration of the robot in the computed path.

This is the same as the selected goal and performs the same operation as calling .path[-1].configuration. This throws if the path planning failed.

Returns:

Configuration: The final configuration of the path.

property path

Returns the computed path, as a list of waypoints.

The path does not include the start configuration provided to the Planner.path() call. The final waypoint in the path is the joint configuration of the selected goal, i.e.:

path_result.final_configuration == goals[path_result.selected_goal_idx].configuration.

If there is a planning error, the list is empty.

Returns:

Path: A list of waypoints.

property selected_goal_idx

If there is a planning error, this is None. Otherwise, this is the index to the selected goal in the goals vector.

Returns:

Optional[int]: The selected goal’s index in the list of goals, if any.

property tcp

The TCP when the PathResult was computed.

Returns:

Tcp

to_string(self: zividmotion.zividmotion.PathResult) → str

class PathResult.Error

blockedStart

The start configuration is blocked.

blockedEnd

All the valid goal configurations are blocked.

blockedPath

The start configuration and at least one goal configuration are not blocked, but the planner failed to connect them with a collision-free path.

kinematicViolation

All the goal configurations are outside the robot’s joint limits.

class zividmotion.zividmotion.Obstacle

Represents an obstacle in the robot environment, to be used with the set_obstacles() method. The obstacle coordinates must be expressed in the base frame of the planner.

static from_colored_point_cloud(name: str, points: zividmotion.zividmotion.Obstacle.PointCloud, colors: zividmotion.zividmotion.Obstacle.Colors) → zividmotion.zividmotion.Obstacle

Initializes a colored Obstacle instance from a point cloud.

The number of points and colors must be the same. Note that adding color has some overhead and is therefore not recommended in performance-critical code.

Args:

name (str): Name

points (Obstacle.PointCloud): The obstacle points.

colors (Obstacle.Colors): The per-point colors.

Returns:

Obstacle

static from_mesh(name: str, mesh: zividmotion.zividmotion.Mesh) → zividmotion.zividmotion.Obstacle

Initializes an Obstacle instance from a Mesh.

Args:

name (str): Name

mesh (Mesh): The mesh defining the obstacle surface.

Returns:

Obstacle

static from_point_cloud(name: str, points: zividmotion.zividmotion.Obstacle.PointCloud) → zividmotion.zividmotion.Obstacle

Initializes an Obstacle instance from a point cloud.

Args:

name (str): Name

points (Obstacle.PointCloud): The obstacle points.

Returns:

Obstacle

to_string(self: zividmotion.zividmotion.Obstacle) → str

class zividmotion.zividmotion.Obstacle.PointCloud

A point cloud as a sequence of Vector3f.

Construct from a numpy (N, 3) float32 array (one copy, recommended for large clouds, for example copy_data(“xyz”) from a Zivid frame) or any iterable of Vector3f.

__init__(self: zividmotion.zividmotion.Obstacle.PointCloud, data: object) → None

Constructs a point cloud.

Args:

data (numpy.ndarray[numpy.float32[N, 3]]): The points as a numpy array, or any iterable of Vector3f.

Returns:

None

class zividmotion.zividmotion.Obstacle.Colors

A sequence of ColorRGBA.

Construct from a numpy (N, 4) uint8 array (one copy, recommended for large clouds, for example copy_data(“rgba”) from a Zivid frame) or any iterable of ColorRGBA.

__init__(self: zividmotion.zividmotion.Obstacle.Colors, data: object) → None

Constructs the per-point colors.

Args:

data (numpy.ndarray[numpy.uint8[N, 4]]): The colors as a numpy array, or any iterable of ColorRGBA.

Returns:

None

class zividmotion.zividmotion.Mesh

A triangle mesh.

bottom_center_transform(self: zividmotion.zividmotion.Mesh) → zividmotion.zividmotion.Mesh

Transforms this mesh such that its bottom center is at the origin. This method can be used in conjunction with e.g. Planner.set_replaceable_tool where the attachment point for the mesh is usually at the bottom. This method creates a copy of the mesh and leaves the original unchanged.

Returns:

Mesh: A copy of this mesh which is transformed such that its bottom center is at the origin.

bottom_center_transform_in_place(self: zividmotion.zividmotion.Mesh) → zividmotion.zividmotion.Mesh

Transforms this mesh such that its bottom center is at the origin. This method can be used in conjunction with e.g. Planner.set_replaceable_tool where the attachment point for the mesh is usually at the bottom. This method modifies the mesh in-place and does not create a new Mesh instance.

Returns:

Mesh: This mesh which is now transformed such that its bottom center is at the origin.

static create_box(extents: zividmotion.zividmotion.Vector3f) → zividmotion.zividmotion.Mesh

Creates a box-shaped mesh with the given extents. The created mesh is centered on the origin.

Args:

extents (Vector3f): The dimensions of the box.

Returns:

Mesh: A box-shaped mesh.

static create_cylinder(radius: float, height: float, resolution: int = 64) → zividmotion.zividmotion.Mesh

Creates a cylinder-shaped mesh. The created mesh is centered on the origin. The side of the cylinder is constructed from rectangular segments that approximate the circular surface at the provided angular resolution. I.e., the side of the cylinder is made up of ‘resolution’ rectangular segments, each covering an angle of (360 / resolution) degrees.

Args:

radius (float): The radius of the cylinder.

height (float): The height of the cylinder.

resolution (int): The number of rectangular segments approximating the side of the cylinder. (Default: 64)

Returns:

Mesh: A cylinder-shaped mesh.

static create_sphere(radius: float, resolution: int = 64) → zividmotion.zividmotion.Mesh

Creates a sphere-shaped mesh. The created mesh is centered on the origin. The surface of the sphere is constructed from square segments that approximate the circular surface at the provided angular resolution.

Args:

radius (float): The radius of the sphere.

resolution (int): The number of square segments along each axis used to cover 180 degrees along the sphere, from pole to pole. (Default: 64)

Returns:

Mesh: A sphere-shaped mesh.

static from_triangles(triangles: zividmotion.zividmotion.Triangles) → zividmotion.zividmotion.Mesh

Creates a Mesh from a list of triangles.

Args:

triangles (Triangles): The triangles to construct the mesh out of.

Returns:

Mesh: A mesh consisting of the given triangles.

set_color(self: zividmotion.zividmotion.Mesh, color: zividmotion.zividmotion.ColorRGBA) → zividmotion.zividmotion.Mesh

Sets a uniform color on all vertices of the mesh, replacing any existing color. This method modifies the mesh in-place and does not create a new Mesh instance.

Args:

color (ColorRGBA): The color to apply to the mesh. The alpha component is ignored.

Returns:

Mesh: This mesh which now has the given uniform color.

to_triangles(self: zividmotion.zividmotion.Mesh) → zividmotion.zividmotion.Triangles

Converts the mesh to a list of triangles. This method is effectively the inverse of Mesh.from_triangles.

Returns:

Triangles: A list of triangles representing the contents of the mesh.

transform(self: zividmotion.zividmotion.Mesh, transform: zividmotion.zividmotion.Pose) → zividmotion.zividmotion.Mesh

Applies the given transform to the vertices of this mesh. This method creates a copy of the mesh and leaves the original unchanged.

Args:

transform (Pose): The transform to apply to the mesh vertices.

Returns:

Mesh: A copy of this mesh which is transformed by the given pose.

transform_in_place(self: zividmotion.zividmotion.Mesh, transform: zividmotion.zividmotion.Pose) → zividmotion.zividmotion.Mesh

Applies the given transform to the vertices of this mesh. This method modifies the mesh in-place and does not create a new Mesh instance.

Args:

transform (Pose): The transform to apply to the mesh vertices.

Returns:

Mesh: This mesh which is now transformed by the given pose.

triangle_count(self: zividmotion.zividmotion.Mesh) → int

Returns the number of triangles in the mesh.

Returns:

int: The number of triangles.

class zividmotion.zividmotion.Tcp

Represents a tool center point (TCP) of the robot. It contains the transform and tool direction.

__init__(self: zividmotion.zividmotion.Tcp, transform: zividmotion.zividmotion.Pose, tool_direction: zividmotion.zividmotion.Vector3f) → None

Initializes a TCP instance from a transform and tool direction.

Args:

transform (Pose): Transform

tool_direction (Vector3f): Tool direction

Returns:

None

to_string(self: zividmotion.zividmotion.Tcp) → str

property tool_direction

The tool direction of the TCP, expressed in the new TCP frame.

This is used for interaction planning in Touch operations.

Returns:

Vector3f

property transform

The transform of the TCP, relative to the robot flange frame.

Returns:

Pose

class zividmotion.zividmotion.Goals

A collection of path-planning goals.

static from_configurations(joint_configurations: list[zividmotion.zividmotion.Configuration]) → zividmotion.zividmotion.Goals

Initializes a Goals instance directly from a list of configurations.

Args:

joint_configurations (list[Configuration]): The joint configurations

Returns:

Goals

property joint_configurations

List of optional joint configurations.

These are optionals to preserve the mapping to the input poses when calling Planner::compute_inverse_kinematics().

Returns:

list[Optional[Configuration]]

none_valid(self: zividmotion.zividmotion.Goals) → bool

A utility method to check if all the configurations are None or not.

Returns:

bool

to_string(self: zividmotion.zividmotion.Goals) → str

class zividmotion.zividmotion.Pose

Describes a rigid transform (rotation+translation), such as a robot pose.

The translation part of the transform is expressed in meters.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: zividmotion.zividmotion.Pose) -> None

   Default-constructs a Pose with an identity transform.

   Returns:

   None

2. __init__(self: zividmotion.zividmotion.Pose, matrix: numpy.ndarray[numpy.float32[4, 4]]) -> None

   Constructs a Pose from a 4x4 NumPy array.

   Args:

   matrix (numpy.ndarray[numpy.float32[4, 4]]): The 4x4 homogeneous transformation matrix.

   Returns:

   None

3. __init__(self: zividmotion.zividmotion.Pose, matrix: zividmotion.zividmotion.Matrix4x4) -> None

   Constructs a Pose from a 4x4 transformation matrix.

   Args:

   matrix (Matrix4x4): The 4x4 homogeneous transformation matrix.

   Returns:

   None

to_matrix(self: zividmotion.zividmotion.Pose) → zividmotion.zividmotion.Matrix4x4

Converts the pose to a 4x4 transformation matrix.

Returns:

Matrix4x4

to_string(self: zividmotion.zividmotion.Pose) → str

class zividmotion.zividmotion.Matrix4x4

Matrix of size 4x4 containing 32-bit floats.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: zividmotion.zividmotion.Matrix4x4) -> None

   Default-constructs a zero-initialized 4x4 matrix.

   Returns:

   None

2. __init__(self: zividmotion.zividmotion.Matrix4x4, other: zividmotion.zividmotion.Matrix4x4) -> None

   Copy-constructs a Matrix4x4.

   Returns:

   None

3. __init__(self: zividmotion.zividmotion.Matrix4x4, data: Annotated[list[float], FixedSize(16)]) -> None

   Constructs a Matrix4x4 from a flat sequence of 16 elements in row major order.

   Args:

   data: A 1D list or numpy.ndarray of 16 floats.

   Returns:

   None

4. __init__(self: zividmotion.zividmotion.Matrix4x4, data: Annotated[list[Annotated[list[float], FixedSize(4)]], FixedSize(4)]) -> None

   Constructs a Matrix4x4 from a 4x4 sequence in row major order.

   Args:

   data: A 2D 4x4 list or numpy.ndarray of floats.

   Returns:

   None

static identity() → zividmotion.zividmotion.Matrix4x4

Returns the identity matrix.

Returns:

Matrix4x4

inverse(self: zividmotion.zividmotion.Matrix4x4) → zividmotion.zividmotion.Matrix4x4

Returns the inverse of this matrix.

Returns:

Matrix4x4

to_string(self: zividmotion.zividmotion.Matrix4x4) → str

class zividmotion.zividmotion.Profile

testing

production

class zividmotion.zividmotion.PlannerSettings

Settings to instantiate the Planner.

__init__(self: zividmotion.zividmotion.PlannerSettings, cell_name: str, profile: zividmotion.zividmotion.Profile) → None

Initializes a PlannerSettings instance.

Args:

cell_name (str): The identifier for the planner configuration data path

profile (Profile): Used to specify a testing or production profile for a robot cell

Returns:

None

to_string(self: zividmotion.zividmotion.PlannerSettings) → str

class zividmotion.zividmotion.BottomCenteredTransformedBox

Represents a box whose transform points to the box’s bottom center.

__init__(self: zividmotion.zividmotion.BottomCenteredTransformedBox, transform: zividmotion.zividmotion.Pose, box_dimensions: zividmotion.zividmotion.Vector3f) → None

Initializes a BottomCenteredTransformedBox instance from a transform and box dimensions.

Args:

transform (Pose): The transformation from the context-dependent reference frame to the box bottom center.

box_dimensions (Vector3f): The dimensions of the box.

Returns:

None

property dimensions

The dimensions of the box.

Returns:

Vector3f

to_string(self: zividmotion.zividmotion.BottomCenteredTransformedBox) → str

property transform

The transformation from the context-dependent reference frame to the box bottom center.

Returns:

Pose

class zividmotion.zividmotion.ColorRGBA

Color with red, green, blue and alpha channels, each in the range 0-255.

A sequence of these makes up an Obstacle.Colors. For large clouds, construct that directly from a numpy (N, 4) uint8 array rather than building one ColorRGBA per point; the numpy path copies in a single pass and is much faster.

__init__(self: zividmotion.zividmotion.ColorRGBA, r: int = 0, g: int = 0, b: int = 0, a: int = 0) → None

property a

The alpha channel.

Returns:

int

property b

The blue channel.

Returns:

int

property g

The green channel.

Returns:

int

property r

The red channel.

Returns:

int

to_string(self: zividmotion.zividmotion.ColorRGBA) → str

class zividmotion.zividmotion.Vector3f

Vector of three coordinates as float, expressed in meters.

A sequence of these makes up an Obstacle.PointCloud. For large clouds, construct that directly from a numpy (N, 3) float32 array rather than building one Vector3f per point; the numpy path copies in a single pass and is much faster.

__init__(self: zividmotion.zividmotion.Vector3f, x: float = 0.0, y: float = 0.0, z: float = 0.0) → None

to_string(self: zividmotion.zividmotion.Vector3f) → str

property x

The x coordinate.

Returns:

float

property y

The y coordinate.

Returns:

float

property z

The z coordinate.

Returns:

float

class zividmotion.zividmotion.Configuration

Joint angles of the robot, expressed in radians.

Constructible from any list, tuple or numpy array of floats. Supports len(), indexing, iteration and the numpy buffer protocol (np.array(configuration)).

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: zividmotion.zividmotion.Configuration) -> None

2. __init__(self: zividmotion.zividmotion.Configuration, values: list[float]) -> None

to_string(self: zividmotion.zividmotion.Configuration) → str

class zividmotion.zividmotion.Triangle

A triangle defined by three Vector3f corners.

Constructed from its three corners a, b and c, which are also accessible as attributes.

A sequence of these makes up a Triangles mesh. For large meshes, construct that directly from a numpy (N, 3, 3) float32 array rather than building one Triangle per face; the numpy path copies in a single pass and is much faster.

__init__(self: zividmotion.zividmotion.Triangle, a: zividmotion.zividmotion.Vector3f = {x: 0, y: 0, z: 0}, b: zividmotion.zividmotion.Vector3f = {x: 0, y: 0, z: 0}, c: zividmotion.zividmotion.Vector3f = {x: 0, y: 0, z: 0}) → None

property a

The first corner.

Returns:

Vector3f

property b

The second corner.

Returns:

Vector3f

property c

The third corner.

Returns:

Vector3f

to_string(self: zividmotion.zividmotion.Triangle) → str

Typedefs

class zividmotion.zividmotion.Triangles

A mesh as a sequence of Triangle.

Construct from a numpy (N, 3, 3) float32 array of triangle corners (one copy, recommended for large meshes) or any iterable of Triangle.

__init__(self: zividmotion.zividmotion.Triangles, data: object) → None

Constructs a mesh.

Args:

data (numpy.ndarray[numpy.float32[N, 3, 3]]): The triangle corners as a numpy array, or any iterable of Triangle.

Returns:

None

zividmotion.zividmotion.ProgressCallback

A progress callback function type: Callable[[float, str], None].

The first argument is the progress completion percentage (0 - 100%), and the second is a textual description of the progress stage.

Free Functions

zividmotion.zividmotion.generate(application: zividmotion.zividmotion.Application, planner_settings: Zivid::Motion::PlannerSettings, progress_callback: Callable[[float, str], None] = None) → None

Generate cell data

Args:

application (Application): Motion application

planner_settings (PlannerSettings): Settings for generation

progress_callback (Callable[[float, str], None] or None): An optional progress callback function

Returns:

None

zividmotion.zividmotion.package_cell(application: zividmotion.zividmotion.Application, cell_name: str, output_path: os.PathLike, include_generated_data: list[zividmotion.zividmotion.Profile]) → None

Packages a cell into a zip archive.

This function collects all files required to run the motion planner with the specified cell name and packages them into a zip file at the given output path.

Throws if the specified cell does not exist, if the output file already exists, or if the parent folder of the output path does not exist.

Args:

application (Application): Motion application

cell_name (str): The name of the cell to package.

output_path (os.PathLike): The destination path for the generated zip archive, including the filename with “.zip” extension.

include_generated_data (list[Profile]): What generated data to include.

Returns:

None

zividmotion.zividmotion.package_api_log(application: zividmotion.zividmotion.Application, api_log_path: os.PathLike) → os.PathLike

Packages the data related to an API log into a zip archive.

This function collects the files required to replay a motion session with a specified API log, and packages them into a zip file with the same name as the API log, but with the -resources.zip suffix instead of the .json extension. The API log itself is not packaged.

Args:

application (Application): Motion application

api_log_path (os.PathLike): The path to the API log

Returns:

os.PathLike: The path to the created zip archive.

zividmotion.zividmotion.install_package(application: zividmotion.zividmotion.Application, package_path: os.PathLike) → None

Installs a packaged cell to be used by the motion planner.

This function extracts the contents of a packaged cell (zip archive) and installs them into the appropriate directory so they can be used by the motion planner.

Args:

application (Application): Motion application

package_path (os.PathLike): The path to the cell package (zip archive) to install.

Returns:

None

Experimental

zividmotion.zividmotion.experimental.merge(meshes: list[zividmotion.zividmotion.Mesh]) → zividmotion.zividmotion.Mesh

Merges several meshes into a single mesh. This function creates a new Mesh instance and leaves the input meshes unchanged.

This is an experimental feature. It may be changed or removed without notice in a future release.

Args:

meshes (list[Mesh]): A list of meshes to merge.

Returns:

Mesh: The merged Mesh instance.

zividmotion.zividmotion.experimental.check_mesh_collisions(planner: zividmotion.zividmotion.Planner, configurations: list[zividmotion.zividmotion.Configuration], num_ignored_links_from_tip: int) → list[bool]

Checks if the robot is in collision with any environment meshes for the given joint configurations.

This is an experimental feature. It may be changed or removed without notice in a future release.

Also checks for self-collision. Any environment point clouds are ignored.

Use num_ignored_links_from_tip to disregard links of the robot from collision checking, counting from the tip of your robot model. Use the value zero to include the whole robot model. Note that if you have a tool modeled as part of the last link, then setting this to 1 ignores the tool as well. Any carried objects or replaceable tools are also ignored when num_ignored_links_from_tip > 0.

Also note that including multiple configurations in the same call is faster than iterative calls to this function.

Args:

planner (Planner): The planner holding the robot model and environment

configurations (list[Configuration]): Configurations

num_ignored_links_from_tip (int): Number of ignored links from tip

Returns:

list[bool]: One bool per input configuration. True if the configuration is in collision, False otherwise.