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 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: Application) Application
Enter the runtime context related to this object
- __exit__(self: Application, arg0: type | None, arg1: object | None, arg2: object | None) None
Exit the runtime context related to this object
- create_planner(self: Application, planner_settings: PlannerSettings) Planner
Initializes a Planner instance from planner settings.
- Parameters:
planner_settings (PlannerSettings) – Planner settings
- Return type:
- release(self: 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.
- Return type:
- to_string(self: Application) str
- class Planner
- clear_carried_object(self: Planner) None
Clears the carried object from the robot’s collision model.
- Return type:
- clear_obstacles(self: Planner) None
Clears all registered obstacles from the planner’s collision model.
- Return type:
- clear_replaceable_tool(self: Planner) None
Clears the replaceable tool from the robot’s collision model.
- Return type:
- clip_point_cloud_with_box(self: Planner, box: 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.
- Parameters:
box (BottomCenteredTransformedBox) – The box volume where points should be removed. The transform is defined relative to the cell base frame.
- Return type:
- clip_point_cloud_with_mesh(self: Planner, transform: Pose, mesh: 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.
- compute_inverse_kinematics(self: Planner, poses: list[Pose], reference_configuration: Configuration) 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.
- Parameters:
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:
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
Noneif no such solution is found.- Return type:
- export_api_log(self: Planner, output_directory: PathLike | None = None) PathLike
Exports and saves the API log to file.
- get_tcp(self: Planner) Tcp
Returns the current Tool Center Point of the robot.
- Returns:
The current TCP.
- Return type:
- path(self: Planner, initial_state: InitialState, request: PathRequest) PathResult
Calculates a path to one of multiple goal configurations from the initial state
- Parameters:
initial_state (InitialState) – The initial state for the path
request (PathRequest) – Request for the path call
- Return type:
- replay_api_log(self: Planner, path: 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.
- set_attachments(self: 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.
- set_carried_object(self: Planner, carried_object: 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.
- set_obstacles(self: Planner, obstacles: list[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.
- set_replaceable_tool(self: Planner, replaceable_tool: Mesh, compliant_section: 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.
- Parameters:
replaceable_tool (Mesh) – The mesh of the rigid section of the replaceable tool to be set.
compliant_section (Mesh | None) – 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.
- Return type:
- class 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: Application, cell_name: str) 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.
- Parameters:
application (Application) – The Zivid Motion Application instance
cell_name (str) – The name of the cell to visualize
- Returns:
A Visualizer instance that manages the visualization window
- Return type:
- static view_planner(planner: Planner) 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.
- Parameters:
- Returns:
A Visualizer instance that manages the visualization window
- Return type:
- wait(self: Visualizer) None
Blocks until the user closes the visualization window.
If the window has already been closed, this method returns immediately.
- Return type:
Helper Classes and Structs
- class 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__(self: InitialState, start_configuration: 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.
- Parameters:
start_configuration (Configuration) – The robot’s start configuration for the path planning
- Return type:
- __init__(self: InitialState, previous_result: 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.
- Parameters:
previous_result (PathResult) – A previous successful PathResult
- Return type:
- static from_touch(start_configuration: Configuration) 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.
- Parameters:
start_configuration (Configuration) – The robot’s start configuration for the path planning in touch
- Return type:
- to_string(self: InitialState) str
- class PathRequest
Request to pass to a path call.
- __init__(self: PathRequest, goals: Goals, type: Type = Type.free, goal_prioritization_method: GoalPrioritizationMethod = GoalPrioritizationMethod.shortestPath, retract_direction: Vector3f | None = None, description: str | None = None, max_carried_object_compression_distance: float | None = None) None
Initializes a PathRequest instance.
- Parameters:
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 | None) – 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 | None) – Description can be used to easily distinguish between path calls in the visualizer.
max_carried_object_compression_distance (float | None) – Optional parameter for specifying the maximum compression distance, beyond initial contact, for the carried object along the Touch approach.
- Return type:
- property description
Description can be used to easily distinguish between path calls in the visualizer.
- property goal_prioritization_method
Decides which goal is used when multiple reachable goals are provided to the path call.
- Return type:
- property goals
The goals to plan to.
The path will be planned according to the selected goal prioritization method.
- Return type:
- 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.
- 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.
- to_string(self: PathRequest) str
- 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 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: 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.
- Return type:
- 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.
- Return type:
- to_string(self: BlendRadius) str
- class 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.
- Return type:
- property configuration
The joint configuration of the waypoint.
- Return type:
- 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.
- Return type:
- 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 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.
- class 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: PathResult) bool
Returns true if there is no planning error, false otherwise.
Makes it convenient to do
if path_result: ...- Returns:
A boolean indicating successful status.
- Return type:
- property error
The PathResult will have an error set if the planner did not find a collision-free path to any of the goals.
- 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:
The final configuration of the path.
- Return type:
- 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:
A list of waypoints.
- Return type:
- 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.
- property tcp
The TCP when the PathResult was computed.
- Return type:
- to_string(self: 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 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: PointCloud, colors: Colors) 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.
- Parameters:
name (str) – Name
points (PointCloud) – The obstacle points.
colors (Colors) – The per-point colors.
- Return type:
- static from_point_cloud(name: str, points: PointCloud) Obstacle
Initializes an Obstacle instance from a point cloud.
- Parameters:
name (str) – Name
points (PointCloud) – The obstacle points.
- Return type:
- class 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.
- class 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.
- class Mesh
A triangle mesh.
- bottom_center_transform(self: Mesh) 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:
A copy of this mesh which is transformed such that its bottom center is at the origin.
- Return type:
- bottom_center_transform_in_place(self: Mesh) 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:
This mesh which is now transformed such that its bottom center is at the origin.
- Return type:
- static create_box(extents: Vector3f) Mesh
Creates a box-shaped mesh with the given extents. The created mesh is centered on the origin.
- static create_cylinder(radius: float, height: float, resolution: int = 64) 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.
- static create_sphere(radius: float, resolution: int = 64) 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.
- set_color(self: Mesh, color: ColorRGBA) 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.
- to_triangles(self: Mesh) Triangles
Converts the mesh to a list of triangles. This method is effectively the inverse of Mesh.from_triangles.
- Returns:
A list of triangles representing the contents of the mesh.
- Return type:
- transform(self: Mesh, transform: Pose) Mesh
Applies the given transform to the vertices of this mesh. This method creates a copy of the mesh and leaves the original unchanged.
- class Tcp
Represents a tool center point (TCP) of the robot. It contains the transform and tool direction.
- __init__(self: Tcp, transform: Pose, tool_direction: Vector3f) None
Initializes a TCP instance from a transform and tool direction.
- property tool_direction
The tool direction of the TCP, expressed in the new TCP frame.
This is used for interaction planning in Touch operations.
- Return type:
- class Goals
A collection of path-planning goals.
- static from_configurations(joint_configurations: list[Configuration]) Goals
Initializes a Goals instance directly from a list of configurations.
- Parameters:
joint_configurations (list[Configuration]) – The joint configurations
- Return type:
- 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().- Return type:
- class Pose
Describes a rigid transform (rotation+translation), such as a robot pose.
The translation part of the transform is expressed in meters.
- __init__(self: Pose, matrix: ndarray[numpy.float32[4, 4]]) None
Constructs a Pose from a 4x4 NumPy array.
- class Matrix4x4
Matrix of size 4x4 containing 32-bit floats.
- __init__(self: Matrix4x4, data: Annotated[list[float], FixedSize(16)]) None
Constructs a Matrix4x4 from a flat sequence of 16 elements in row major order.
- Parameters:
data – A 1D list or numpy.ndarray of 16 floats.
- Return type:
- class PlannerSettings
Settings to instantiate the Planner.
- __init__(self: PlannerSettings, cell_name: str, profile: Profile) None
Initializes a PlannerSettings instance.
- to_string(self: PlannerSettings) str
- class BottomCenteredTransformedBox
Represents a box whose transform points to the box’s bottom center.
- __init__(self: BottomCenteredTransformedBox, transform: Pose, box_dimensions: Vector3f) None
Initializes a BottomCenteredTransformedBox instance from a transform and box dimensions.
- to_string(self: BottomCenteredTransformedBox) str
- class 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.
- class 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.
- class 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__(self: Configuration) None
- __init__(self: Configuration, values: list[float]) None
- to_string(self: Configuration) str
- class 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.
Typedefs
- class 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.
- 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
- generate(application: Application, planner_settings: PlannerSettings, progress_callback: Callable[[float, str], None] = None) None
Generate cell data
- Parameters:
application (Application) – Motion application
planner_settings (PlannerSettings) – Settings for generation
progress_callback (Callable[[float, str], None] or None) – An optional progress callback function
- Return type:
- package_cell(application: Application, cell_name: str, output_path: PathLike, include_generated_data: list[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.
- Parameters:
application (Application) – Motion application
cell_name (str) – The name of the cell to package.
output_path (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.
- Return type:
- package_api_log(application: Application, api_log_path: PathLike) 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.zipsuffix instead of the.jsonextension. The API log itself is not packaged.- Parameters:
application (Application) – Motion application
api_log_path (PathLike) – The path to the API log
- Returns:
The path to the created zip archive.
- Return type:
- install_package(application: Application, package_path: 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.
- Parameters:
application (Application) – Motion application
package_path (PathLike) – The path to the cell package (zip archive) to install.
- Return type:
Experimental
- merge(meshes: list[Mesh]) 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.
- check_mesh_collisions(planner: Planner, configurations: list[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.
- Parameters:
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:
One bool per input configuration. True if the configuration is in collision, False otherwise.
- Return type: