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
- create_planner(
- self: Application,
- planner_settings: PlannerSettings,
Initializes a Planner instance from planner settings.
Raises an exception if the cell does not exist, or if its planning data for the selected profile is missing or was generated from a different version of the cell's configuration. Run generate() to create or update the data.
- パラメータ:
planner_settings (PlannerSettings) -- Planner settings
- 戻り値の型:
- 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.
- 戻り値の型:
- to_string(self: Application) str
- class Planner
Plans collision-free robot paths in a cell.
Create a Planner with Application.create_planner().
- clear_carried_object(self: Planner) None
Clears the carried object from the robot's collision model.
- 戻り値の型:
- clear_obstacles(self: Planner) None
Clears all registered obstacles from the planner's collision model.
- 戻り値の型:
- clear_replaceable_tool(self: Planner) None
Clears the replaceable tool from the robot's collision model.
- 戻り値の型:
- clip_point_cloud_with_box(
- self: Planner,
- box: BottomCenteredTransformedBox,
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.
- パラメータ:
box (BottomCenteredTransformedBox) -- The box volume where points should be removed. The transform is defined relative to the cell base frame.
- 戻り値の型:
- 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: PoseGoals,
- reference_configuration: Configuration,
Computes the robot's joint configurations corresponding to the given pose goals
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.
- パラメータ:
poses (PoseGoals) -- The poses for which the corresponding configurations will be computed
reference_configuration (Configuration) -- A reference configuration used to preserve the robot’s posture
- 戻り値:
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.- 戻り値の型:
- get_tcp(self: Planner) Tcp
Returns the current Tool Center Point of the robot.
- 戻り値:
The current TCP.
- 戻り値の型:
- path(
- self: Planner,
- initial_state: InitialState,
- request: PathRequest,
Calculates a path to one of multiple goal configurations from the initial state
If the planner does not find a path, PathResult.error is set, and PathResult.diagnostics explains why when the request asks for it. Raises an exception on invalid input, for example a request description that is set but empty.
- パラメータ:
initial_state (InitialState) -- The initial state for the path
request (PathRequest) -- Request for the path call
- 戻り値:
The path to the selected goal, or the error that prevented planning one
- 戻り値の型:
- 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.
Raises an exception if the list is empty, if an obstacle has an empty name, if a point cloud obstacle has no points, or if a colored point cloud obstacle has a different number of points and colors.
- set_replaceable_tool(self: Planner, replaceable_tool: ReplaceableTool) 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.
- パラメータ:
replaceable_tool (ReplaceableTool) -- The replaceable tool parameters.
- 戻り値の型:
- 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.
Only one Visualizer can exist at a time. Opening a new one while another exists raises an exception.
- set_robot_configuration(
- self: Visualizer,
- configuration: Configuration,
Sets the robot configuration displayed by the Visualizer.
This only changes what the Visualizer displays. It does not affect the state of the Planner or any path planning.
- パラメータ:
configuration (Configuration) -- The robot configuration to display
- 戻り値:
None
- static view_cell(application: Application, cell_name: str) Visualizer
Opens a visualization window for the given cell.
Use this function to visualize a cell before planning. To visualize a cell while planning, use Visualizer.view_planner() instead.
- パラメータ:
application (Application) -- The Zivid Motion Application instance
cell_name (str) -- The name of the cell to visualize
- 戻り値:
A Visualizer instance that manages the visualization window
- 戻り値の型:
- static view_planner(planner: Planner) Visualizer
Opens a visualization window for a running Planner.
Use this function 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.
- パラメータ:
- 戻り値:
A Visualizer instance that manages the visualization window
- 戻り値の型:
- wait(self: Visualizer) None
Blocks until the user closes the visualization window.
If the window has already been closed, this method returns immediately.
- 戻り値の型:
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.
- パラメータ:
start_configuration (Configuration) -- The robot's start configuration for the path planning
- 戻り値の型:
- __init__(self: InitialState, previous_result: PathResult) None
Initializes the InitialState from a PathResult.
This overload is intended for consecutive robot motions. Raises an exception if the provided PathResult has an error set.
- パラメータ:
previous_result (PathResult) -- A previous successful PathResult
- 戻り値の型:
- 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.
- パラメータ:
start_configuration (Configuration) -- The robot's start configuration for the path planning in touch
- 戻り値の型:
- to_string(self: InitialState) str
- class PathRequest
Request to pass to a path call.
- __init__(
- self: PathRequest,
- goals: ConfigurationGoals,
- 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,
- diagnose_failures: bool = False,
Initializes a PathRequest instance.
- パラメータ:
goals (ConfigurationGoals) -- 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 Runtime/RegionsOfInterest entry for the region of interest in the user configuration. 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. In meters. If not provided, no compression is allowed.
diagnose_failures (bool) -- Ask the path call to explain a failure. Defaults to False.
- 戻り値の型:
- property description
Description can be used to easily distinguish between path calls in the visualizer.
- property diagnose_failures
Ask the path call to explain a failure.
When set, a path call that fails to find a path returns the collisions and joint limit violations found for the start configuration and every goal configuration in PathResult.diagnostics. A successful path call never returns diagnostics. Finding the explanation takes additional time, so leave this off unless the explanation is used.
- 戻り値の型:
- property goal_prioritization_method
Decides which goal is used when multiple reachable goals are provided to the path call.
- 戻り値の型:
- property goals
The goals to plan to.
The path will be planned according to the selected goal prioritization method.
- 戻り値の型:
- 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.
In meters. If not provided, no compression is allowed.
- 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 Runtime/RegionsOfInterest entry for the region of interest in the user configuration. 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.
The unit can depend on the robot brand. For most off-the-shelf robots, the entry and exit are always equal and expressed in meters.
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.
- 戻り値の型:
- 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.
- 戻り値の型:
- 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.
- 戻り値の型:
- property configuration
The joint configuration of the waypoint.
- 戻り値の型:
- 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.
- 戻り値の型:
- 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: ...- 戻り値:
A boolean indicating successful status.
- 戻り値の型:
- property diagnostics
The collisions and joint limit violations that explain why the path call failed.
This holds a value only when the path request had diagnose_failures set and the path call failed. A successful path call never carries diagnostics. The findings and what they mean are documented on the types in the diagnostics submodule.
- 戻り値の型:
- 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.- 戻り値:
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.
- 戻り値:
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.
- property tcp
The TCP when the PathResult was computed.
If there is a planning error, this value is not meaningful. Use Planner.get_tcp() to get the current TCP.
- 戻り値の型:
- 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 Planner.set_obstacles(). The obstacle coordinates must be expressed in the base frame of the planner.
- static from_colored_point_cloud(
- name: str,
- points: PointCloud,
- colors: Colors,
Initializes a colored Obstacle instance from a point cloud.
The number of points and colors must be the same. Planner.set_obstacles() raises an exception if they differ. Note that adding color has some overhead and is therefore not recommended in performance-critical code.
- パラメータ:
name (str) -- Name
points (PointCloud) -- The obstacle points.
colors (Colors) -- The per-point colors.
- 戻り値の型:
- static from_point_cloud(name: str, points: PointCloud) Obstacle
Initializes an Obstacle instance from a point cloud.
- パラメータ:
name (str) -- Name
points (PointCloud) -- The obstacle points.
- 戻り値の型:
- 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.
- 戻り値:
A copy of this mesh which is transformed such that its bottom center is at the origin.
- 戻り値の型:
- static create_box(extents: Vector3f) Mesh
Creates a box-shaped mesh with the given extents. The created mesh is centered on the origin, with its edges along the x, y and z axes.
Raises an exception if any extent is not positive.
- static create_cylinder(radius: float, height: float, resolution: int = 64) Mesh
Creates a cylinder-shaped mesh. The created mesh is centered on the origin, with its axis along z. 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.
Raises an exception if the radius or height is not positive, or if the resolution is less than 4.
- 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.
Raises an exception if the radius is not positive, or if the resolution is less than 4.
- static from_triangles(triangles: Triangles) Mesh
Creates a Mesh from a list of triangles.
Raises an exception if there are no triangles, or if the triangles form invalid geometry, such as a degenerate (zero-area) triangle.
- to_triangles(self: Mesh) Triangles
Converts the mesh to a list of triangles. This method is effectively the inverse of Mesh.from_triangles.
- 戻り値:
A list of triangles representing the contents of the mesh.
- 戻り値の型:
- 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.
- triangle_count(self: Mesh) int
Returns the number of triangles in the mesh.
- 戻り値:
The number of triangles.
- 戻り値の型:
- class ToolGeometry
Geometry for a tool element, defined in the robot flange frame
- __init__(
- self: ToolGeometry,
- rigid_section: Mesh,
- compliant_section: Mesh | None = None,
Initializes a ToolGeometry instance.
- パラメータ:
rigid_section (Mesh) -- The rigid section of the tool geometry.
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.
- 戻り値の型:
- property compliant_section
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.
- class ReplaceableTool
"Replaceable tool defined in the robot flange frame.
- __init__(
- self: ReplaceableTool,
- name: str,
- geometry: ToolGeometry,
Constructs a replaceable tool with the given name and geometry.
- パラメータ:
name (str) -- The name of the replaceable tool.
geometry (ToolGeometry) -- The geometry of the replaceable tool.
- 戻り値:
None
- to_string(self: ReplaceableTool) str
- 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.
- 戻り値の型:
- class ConfigurationGoal
A path-planning goal, consisting of a joint configuration.
- __init__(
- self: ConfigurationGoal,
- configuration: Configuration,
Initializes a ConfigurationGoal instance.
- パラメータ:
configuration (Configuration) -- The configuration to attempt to plan to
- 戻り値の型:
- property configuration
The configuration to attempt to plan to
- 戻り値の型:
- to_string(self: ConfigurationGoal) str
- class ConfigurationGoals
A collection of path-planning goals.
- __init__(
- self: ConfigurationGoals,
- joint_configurations: list[Configuration],
Initializes a ConfigurationGoals instance directly from a list of configurations.
- パラメータ:
joint_configurations (list[Configuration]) -- The joint configurations
- 戻り値の型:
- __init__(
- self: ConfigurationGoals,
- goals: list[ConfigurationGoal],
Initializes a ConfigurationGoals instance from a list of goals.
- パラメータ:
goals (list[ConfigurationGoal]) -- The goals
- 戻り値の型:
- goals(self: ConfigurationGoals) list[ConfigurationGoal | None]
List of optional goals.
These are optionals to preserve the mapping to the input poses when calling
Planner::compute_inverse_kinematics().- 戻り値の型:
- none_valid(self: ConfigurationGoals) bool
A utility method to check if all the configurations are
Noneor not.- 戻り値の型:
- to_string(self: ConfigurationGoals) str
- class PoseGoal
A goal given as a TCP pose.
- class PoseGoals
A collection of pose goals.
- __init__(self: PoseGoals, poses: list[Pose]) None
Initializes a PoseGoals instance directly from a list of poses.
- 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.
Raises an exception if the matrix is not a rigid transform, i.e. a rotation plus a translation.
- __init__(self: Pose, matrix: Matrix4x4) None
Constructs a Pose from a 4x4 transformation matrix.
Raises an exception if the matrix is not a rigid transform, i.e. a rotation plus a translation.
- compose(self: Pose, other: Pose) Pose
Composes this pose with another pose.
The result applies the other pose first, then this pose.
- 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.
- パラメータ:
data -- A 1D list or numpy.ndarray of 16 floats.
- 戻り値の型:
- class Profile
- testing
Planning data for development and testing, typically configured to be coarser and quick to generate.
- production
Planning data for deployment, typically configured to be finer and slower to generate.
- class PlannerSettings
Settings to instantiate the Planner.
- __init__(
- self: PlannerSettings,
- cell_name: str,
- profile: Profile,
Initializes a PlannerSettings instance.
- property cell_name
The name of the cell, which is the name of its folder in the Motion cell data directory.
- property profile
The profile of the cell's planning data to use.
- 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,
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.
Diagnostics
- class diagnostics.PathDiagnostics
The collisions and joint limit violations found for a failed path call. The start configuration and every goal configuration are checked, regardless of which error the path call reported. A blockedPath failure concerns the space between configurations, so it typically yields no findings.
- property goals
The diagnostics for each requested goal, index-aligned with the request, including goals path() did not plan to. A goal that had no configuration to check, because no inverse kinematics solution was found for its pose, is None.
- property start
The diagnostics for the start configuration.
- to_string(self: PathDiagnostics) str
- class diagnostics.ConfigurationDiagnostics
The collisions and joint limit violations found for a single configuration.
- property joint_limit_violations
All joint limit violations found for the configuration.
- property obstacle_collisions
All collisions between the robot and an obstacle found for the configuration. Empty for a configuration outside its joint limits, which is never collision-checked.
- property self_collision
The self-collision found for the configuration, or None if the robot did not collide with itself.
- class diagnostics.ObstacleCollision
Describes a single collision between the robot and an obstacle.
- property obstacle_name
The name of the obstacle.
- property obstacle_type
The kind of object the robot collided with.
- property robot_parts
The colliding robot parts. Each part is a Link, an Attachment, a CarriedObject or a ReplaceableTool. Empty when the overlap cannot be attributed to a specific part.
- class diagnostics.SelfCollision
Describes the robot colliding with itself.
- property robot_parts
The robot parts that touch each other. Each part is a Link, an Attachment, a CarriedObject or a ReplaceableTool.
- class diagnostics.JointLimitViolation
Describes a single joint that is outside its limits.
The values are in the same unit as Configuration.
- property joint_name
The name of the violating joint.
- property joint_value
The requested joint value.
- property lower_limit
The lower joint limit.
- property upper_limit
The upper joint limit.
- class diagnostics.Link
A robot link.
- property name
The name of the link in the robot model. Frames fixed to that link belong to the same part.
- property number
The number of the link, counted from 1 at the robot base. Link 1 is the link moved by the first joint of the configuration.
- class diagnostics.Attachment
An attachment mounted on the last link.
- property index
The index of the attachment, in the order the attachments were configured.
- class diagnostics.CarriedObject
The carried object held at the TCP.
- class diagnostics.ReplaceableTool
The replaceable tool, reported as one part.
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,
Generate the planning data for a cell and profile.
A Planner needs this data. Generate again after changing the cell's configuration files: creating a Planner from data generated for an earlier version of the configuration raises an exception.
Raises an exception if the cell does not exist.
- パラメータ:
application (Application) -- Motion application
planner_settings (PlannerSettings) -- Settings for generation
progress_callback (Callable[[float, str], None] or None) -- An optional progress callback function. It is called periodically during each stage with the progress of the current stage in percent (0 - 100) and a description of the stage.
- 戻り値の型:
- package_cell(
- application: Application,
- cell_name: str,
- output_path: PathLike,
- include_generated_data: list[Profile],
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 or its dependencies cannot be loaded, if the requested generated data is out of sync with the cell configuration, if the output file already exists, or if the parent folder of the output path does not exist.
- パラメータ:
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.
- 戻り値の型:
- package_api_log(application: Application, api_log_path: PathLike) PathLike
Packages an API log and the data required to replay it into a zip archive.
This function collects the API log and the files required to replay it, and packages them into a zip file next to the API log, with the same name but the
.zipextension instead of.json. This archive is all Zivid needs to reproduce the logged session.- パラメータ:
application (Application) -- Motion application
api_log_path (PathLike) -- The path to the API log
- 戻り値:
The path to the created zip archive.
- 戻り値の型:
- 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.
- パラメータ:
application (Application) -- Motion application
package_path (PathLike) -- The path to the cell package (zip archive) to install.
- 戻り値の型:
Experimental
- load_mesh(filename: str) Mesh
Loads a mesh from a file on disk.
This is an experimental feature. It may be changed or removed without notice in a future release.
- 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,
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.
- パラメータ:
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
- 戻り値:
One bool per input configuration. True if the configuration is in collision, False otherwise.
- 戻り値の型: