C++ API Reference

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

Applicationclass

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.

Public Functions

PlannercreatePlanner(PlannerSettingsplannerSettings )const

Initializes a Planner instance from planner settings.

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

パラメータ:

plannerSettings -- Planner settings

stdstringtoString()const::

Get string representation of the Application.

Plannerclass

Plans collision-free robot paths in a cell.

Create a Planner with Application::createPlanner().

Public Functions

ConfigurationGoalscomputeInverseKinematics( PoseGoals&const poses, Configuration&const referenceConfiguration)

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 -- The poses for which the corresponding configurations will be computed

• referenceConfiguration -- 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 std::nullopt if no such solution is found.

PathResultpath( InitialState&const initialState, PathRequest&const request)

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. Throws on invalid input, for example a request description that is set but empty.

パラメータ:

• initialState -- The initial state for the path

• request -- Request for the path call

戻り値:

The path to the selected goal, or the error that prevented planning one

setObstacles( stdvectorObstacle obstaclesconst::<>&)void

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.

Throws if the vector 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.

パラメータ:

obstacles -- Obstacles

clearObstacles()void

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

setCarriedObject( Mesh&const carriedObject)void

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.

パラメータ:

carriedObject -- The mesh of the carried object to be set

clearCarriedObject()void

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

setReplaceableTool( ReplaceableTool&const replaceableTool)void

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.

パラメータ:

replaceableTool -- The replaceable tool parameters

clearReplaceableTool()void

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

setAttachments( stdvectorstdstring attachmentsconst::<::>&)void

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.

パラメータ:

attachments -- Specifies the name of the attachments to be set. Only attachments defined in the configuration file can be set. If an empty vector is provided, all attachments are removed.

setTcp( Tcp&const tcp)void

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.

パラメータ:

tcp -- The TCP to be set

TcpgetTcp()const

Returns the current Tool Center Point of the robot.

戻り値:

The current TCP

clipPointCloudWithBox( BottomCenteredTransformedBox&const box)void

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 -- The box volume where points should be removed. The transform is relative to the cell base frame.

clipPointCloudWithMesh( Pose&const transform, Mesh&const mesh)void

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.

パラメータ:

• transform -- The transformation from the cell base frame to the mesh.

• mesh -- The mesh to clip with. Note: The mesh must be closed. Using a mesh that is not closed is currently undefined behavior.

stdfilesystempathexportApiLog( stdoptionalstdfilesystempath outputDirectory=stdnulloptconst::<::::>& ::)::::

Exports and saves the API log to file.

パラメータ:

outputDirectory -- If specified, overrides the default output directory specified in RuntimeConfiguration.yaml.

戻り値:

The path to the stored API log file.

replayApiLog( stdfilesystempath&const:::: path)void

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.

パラメータ:

path -- The path to the API log file to replay.

stdstringtoString()const::

Get string-representation of Planner

Visualizerclass

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 throws an exception.

Public Functions

setRobotConfiguration( Configuration&const configuration)void

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 -- The robot configuration to display

wait()void

Blocks until the user closes the visualization window.

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

Public Static Functions

VisualizerviewPlanner(Planner& planner)static

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::viewCell() instead. The planner must remain alive for the lifetime of the Visualizer.

パラメータ:

planner -- The Planner instance to visualize

戻り値:

A Visualizer instance that manages the visualization window

VisualizerviewCell( Application&const application, stdstring&const:: cellName)static

Opens a visualization window for the given cell.

Use this function to visualize a cell before generation. To visualize a cell while planning, use Visualizer::viewPlanner() instead.

パラメータ:

• application -- The Zivid Motion Application instance

• cellName -- The name of the cell to visualize

戻り値:

A Visualizer instance that manages the visualization window

Helper Classes and Structs

InitialStateclass

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.

Public Functions

InitialState( Configuration&const startConfiguration)

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.

パラメータ:

startConfiguration -- The robot's start configuration for the path planning

InitialState( PathResult&const previousResult)

Initializes the InitialState from a PathResult.

This overload is intended for consecutive robot motions. Throws if the provided PathResult has an error set.

パラメータ:

previousResult -- A previous successful PathResult

stdstringtoString()const::

Get string representation of the InitialState.

Public Static Functions

InitialStateFromTouch( Configuration&const startConfiguration)static

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.

パラメータ:

startConfiguration -- The robot's start configuration for the path planning in touch

PathRequeststruct

Request to pass to a path call.

Public Types

Typeenumclass

Used to specify the motion type.

Values:

freeenumerator

For moving in free space.

touchenumerator

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.

GoalPrioritizationMethodenumclass

Used to specify the goal prioritization method.

Values:

listOrderenumerator

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

shortestPathenumerator

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

Public Functions

stdstringtoString()const::

Get string representation of the PathRequest.

Public Members

ConfigurationGoalsgoals

The goals to plan to.

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

Typetype=Typefree ::

Decides the motion type.

GoalPrioritizationMethodgoalPrioritizationMethod=GoalPrioritizationMethodshortestPath ::

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

stdoptionalVector3f retractDirection={::<> }

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.

stdoptionalstdstring description={::<::> }

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

stdoptionalfloat maxCarriedObjectCompressionDistance={::<> }

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.

diagnoseFailures={}bool false

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.

BlendRadiusstruct

Represents a blend radius for a given waypoint.

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.

Public Functions

stdstringtoString()const::

Get string representation of the BlendRadius.

Public Members

entryfloat

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

exitfloat

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

Waypointstruct

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

Public Types

Movementenumclass

Enum describing different ways the robot can move between waypoints.

Values:

jointenumerator

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

linearenumerator

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

Public Functions

stdstringtoString()const::

Get string representation of the Waypoint.

Public Members

Configurationconfiguration

The joint configuration of the waypoint.

Movementmovement

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

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

BlendRadiusblendRadius

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

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.

Pathclass

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

Public Types

value_type=Waypointusing

The type of the elements stored in the path.

const_iterator=stdvectorWaypoint::const_iteratorusing ::<>

Iterator type for immutable access to the waypoints.

Public Functions

const_iteratorbegin()const

Iterator to the beginning of the waypoints.

const_iteratorend()const

Iterator to the end of the waypoints.

const_iteratorcbegin()const

Iterator to the beginning of the waypoints.

const_iteratorcend()const

Iterator to the end of the waypoints.

stdsize_tsize()const::

The number of waypoints in the path.

empty()constbool

Check whether the path contains no waypoints.

Waypoint&[]operator(stdsize_tindex:: )constconst

Access the waypoint at the given index.

Waypoint&front()constconst

Access the first waypoint in the path.

Waypoint&back()constconst

Access the last waypoint in the path.

stdstringtoString()const::

Get string representation of the Path.

PathResultclass

PathResult is the result of calculating a path to a set of potential goals.

It's the return value from Planner.path().

Public Types

Errorenumclass

Enum describing why the planner did not find a path to any goal.

Values:

blockedStartenumerator

The start configuration is blocked.

blockedEndenumerator

All the valid goal configurations are blocked.

blockedPathenumerator

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

kinematicViolationenumerator

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

Public Functions

Pathpath()const

Returns the computed path, as a list of waypoints.

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

pathResult.finalConfiguration() == goals[pathResult.selectedGoalIdx].configuration.

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

戻り値:

A list of waypoints

ConfigurationfinalConfiguration()const

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().back().configuration. This throws if the path planning failed.

戻り値:

The final configuration of the path

operatorbool()constexplicit

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

Makes it convenient to do if(pathResult) { ... }

stdstringtoString()const::

Get string representation of the PathResult.

Public Members

stdoptionalError error::<>

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

stdoptionaluint32_t selectedGoalIdx::<>

If there is a planning error, this is std::nullopt.

Otherwise, this is the index to the selected goal in the goals vector.

Tcptcp

The TCP when the PathResult was computed.

If there is a planning error, this value is not meaningful. Use Planner::getTcp() to get the current TCP.

stdoptionalDiagnosticsPathDiagnostics diagnostics::<::>

The collisions and joint limit violations that explain why the path call failed.

This holds a value only when the path request had diagnoseFailures 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 Zivid::Motion::Diagnostics.

Obstacleclass

Represents an obstacle in the robot environment, to be used with Planner::setObstacles().

The obstacle coordinates must be expressed in the cell base frame.

Public Types

PointCloud=stdvectorVector3fusing ::<>

A vector of points representing a point cloud.

Colors=stdvectorColorRGBAusing ::<>

A vector of colors.

Public Functions

stdstringtoString()const::

Get string representation of the Obstacle.

Public Static Functions

ObstaclefromMesh(stdstringname:: , Mesh&const mesh)static

Initializes an Obstacle instance from a Mesh.

ObstaclefromPointCloud(stdstringname:: , PointCloudpointCloud )static

Initializes an Obstacle instance from a point cloud.

ObstaclefromColoredPointCloud(stdstringname:: , PointCloudpointCloud , Colorscolors )static

Initializes a colored Obstacle instance from a point cloud.

The number of points and colors must be the same. Planner::setObstacles() throws if they differ. Note that adding color has some overhead and is therefore not recommended in performance-critical code.

Meshclass

A triangle mesh.

Public Functions

TrianglestoTriangles()const

Converts the mesh to a vector of triangles.

This method is effectively the inverse of Mesh::fromTriangles.

戻り値:

A vector of triangles representing the contents of the mesh.

stdsize_ttriangleCount()const::

Returns the number of triangles in the mesh.

戻り値:

The number of triangles.

Meshtransform( Pose&const pose)const

Applies the given transform to the vertices of this mesh.

This method creates a copy of the mesh and leaves the original unchanged.

パラメータ:

pose -- The transform to apply to the mesh vertices.

戻り値:

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

MeshbottomCenterTransform()const

Transforms this mesh such that its bottom center is at the origin.

This method can be used in conjunction with e.g. Planner::setReplaceableTool 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.

MeshwithColor( ColorRGBA&const color)const

Sets a uniform color on all vertices of the mesh, replacing any existing color.

This method creates a copy of the mesh and leaves the original unchanged.

パラメータ:

color -- The color to apply to the mesh. The alpha component is ignored.

戻り値:

A copy of this mesh which now has the given uniform color.

Public Static Functions

MeshfromTriangles( Triangles&const triangles)static

Creates a Mesh from a vector of triangles.

Throws if there are no triangles, or if the triangles form invalid geometry, such as a degenerate (zero-area) triangle.

パラメータ:

triangles -- The triangles to construct the mesh out of.

戻り値:

A mesh consisting of the given triangles.

MeshcreateBox( Vector3f&const extents)static

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.

Throws if any extent is not positive.

パラメータ:

extents -- The dimensions of the box along x, y and z, in meters.

戻り値:

A box-shaped mesh.

MeshcreateCylinder( floatradius, floatheight, unsignedresolution=64)static

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.

Throws if the radius or height is not positive, or if the resolution is less than 4.

パラメータ:

• radius -- The radius of the cylinder, in meters.

• height -- The full height of the cylinder along z, in meters.

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

戻り値:

A cylinder-shaped mesh.

MeshcreateSphere( floatradius, unsignedresolution=64)static

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.

Throws if the radius is not positive, or if the resolution is less than 4.

パラメータ:

• radius -- The radius of the sphere, in meters.

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

戻り値:

A sphere-shaped mesh.

ToolGeometrystruct

Geometry for a tool element, defined in the robot flange frame.

Public Members

MeshrigidSection

The mesh of the rigid section of the tool

stdoptionalMesh compliantSection=stdnullopt::<> ::

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.

ReplaceableToolclass

Replaceable tool defined in the robot flange frame.

Public Functions

ReplaceableTool(stdstringname:: , ToolGeometrygeometry )

Constructs a replaceable tool with the given name and geometry.

パラメータ:

• name -- The name of the replaceable tool.

• geometry -- The geometry of the replaceable tool.

stdstringtoString()const::

Get string representation of the ReplaceableTool.

Tcpstruct

Represents a tool center point (TCP) of the robot.

It contains the transform and tool direction.

Public Functions

stdstringtoString()const::

Get string representation of the Tcp.

Public Members

Posetransform

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

Vector3ftoolDirection

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

This is used for interaction planning in Touch operations.

ConfigurationGoalstruct

A path-planning goal, consisting of a joint configuration.

Public Functions

stdstringtoString()const::

Get string representation of the Goal.

Public Members

Configurationconfiguration

The configuration to attempt to plan to

ConfigurationGoalsclass

A collection of path-planning goals.

Public Functions

ConfigurationGoals( stdvectorConfiguration jointConfigurationsconst::<>&)

Initializes a ConfigurationGoals instance directly from a vector of configurations.

パラメータ:

jointConfigurations -- The joint configurations

ConfigurationGoals( stdvectorConfigurationGoal goalsconst::<>&)

Initializes a ConfigurationGoals instance from a vector of goals.

パラメータ:

goals -- The goals

stdvectorstdoptionalConfigurationGoal>&goals()constconst::<::<>

Returns the stored goals

戻り値:

Optional goals, to preserve the mapping to the input poses when calling Planner::computeInverseKinematics().

noneValid()constbool

A utility method to check if all the joint configurations are std::nullopt or not.

stdstringtoString()const::

Get a string representation of the object.

PoseGoalstruct

A goal given as a TCP pose.

Public Functions

stdstringtoString()const::

Get a string representation of the object.

Public Members

Posepose

The pose to compute a joint configuration for.

PoseGoalsclass

A collection of pose goals.

Public Functions

PoseGoals( stdvectorPose posesconst::<>&)

Initializes a PoseGoals instance directly from a vector of poses.

パラメータ:

poses -- The poses

PoseGoals( stdvectorPoseGoal goalsconst::<>&)

Initializes a PoseGoals instance from a vector of goals.

パラメータ:

goals -- The goals

stdvectorPoseGoal goals()constconst::<>&

Returns the stored goals

stdstringtoString()const::

Get a string representation of the object.

Poseclass

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

The translation part of the transform is expressed in meters.

Public Functions

Pose()

Default-constructs a Pose with an identity transform.

Pose( Matrix4x4&const transform)

Pose constructor taking a 4x4 transform.

Throws if the matrix is not a rigid transform, i.e. a rotation plus a translation.

パラメータ:

transform -- Provides orientation (rotation) and location (translation) for the pose.

Posecompose( Pose&const other)const

Composes this pose with another pose.

パラメータ:

other -- The transform applied first.

戻り値:

The pose that applies other followed by this pose.

Matrix4x4toMatrix()const

Converts the pose to a 4x4 matrix.

戻り値:

4 by 4 matrix.

stdstringtoString()const::

Get string representation of the Pose.

戻り値:

Pose as string.

Public Static Functions

PosefromXyzRpy( Vector3f&const translation, floatroll, floatpitch, floatyaw)static

Constructs a Pose from a translation and roll, pitch and yaw angles.

The rotation is composed as R = Rz(yaw) * Ry(pitch) * Rx(roll).

パラメータ:

• translation -- Translation part of the transform, in meters.

• roll -- Rotation about the X axis, in radians.

• pitch -- Rotation about the Y axis, in radians.

• yaw -- Rotation about the Z axis, in radians.

戻り値:

Pose with the given translation and orientation.

Matrix4x4class

A fixed size 4x4 matrix of floats in row major order.

Public Types

ValueType=floatusing

The type stored in the matrix.

Iterator=stdarrayfloat >iteratorusing ::<,16::

Iterator type for mutable access, iterating over elements in row major order.

ConstIterator=stdarrayfloat >const_iteratorusing ::<,16::

Iterator type for immutable access, iterating over elements in row major order.

Public Functions

Matrix4x4()=default

Default-constructs a zero-initialized matrix.

Matrix4x4( stdarrayfloat rows*cols dataconst::<, >&)explicit

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

Matrix4x4(stdinitializer_listfloat ::<>values)explicit

Constructs a Matrix4x4 from a flat initializer list of elements in row major order.

Throws if the list does not have 16 elements.

Matrix4x4(stdinitializer_liststdinitializer_listfloat>values::<::<> )explicit

Constructs a Matrix4x4 from a nested initializer list.

Each inner list is a row.

Throws if there are not 4 rows of 4 elements.

Iteratorbegin()

Iterator to the beginning of the matrix.

Iteratorend()

Iterator to the end of the matrix.

ConstIteratorbegin()const

Iterator to the beginning of the matrix.

ConstIteratorend()const

Iterator to the end of the matrix.

ConstIteratorcbegin()const

Iterator to the beginning of the matrix.

ConstIteratorcend()const

Iterator to the end of the matrix.

at(stdsize_trow:: , stdsize_tcol:: )float&

Access specified element with bounds checking.

Throws if the row or column is out of range.

at(stdsize_trow:: , stdsize_tcol:: )constconstfloat&

Access specified element with bounds checking.

Throws if the row or column is out of range.

operator()(stdsize_trow:: , stdsize_tcol:: )float&

Access specified element without bounds checking.

operator()(stdsize_trow:: , stdsize_tcol:: )constconstfloat&

Access specified element without bounds checking.

data()float*

Pointer to the underlying row major data.

data()constconstfloat*

Pointer to the underlying row major data.

Matrix4x4inverse()const

Get the inverse of this matrix.

stdstringtoString()const::

Get string representation of the Matrix4x4.

Public Static Functions

Matrix4x4identity()static

Get the identity matrix.

Public Static Attributes

stdsize_trows={}staticconstexpr:: 4

The number of rows in the matrix.

stdsize_tcols={}staticconstexpr:: 4

The number of columns in the matrix.

Profileenumclass

Selects which of a cell's two sets of planning data to generate and plan with.

Each profile has its own generation settings in the cell configuration and its own generated data, so both can be generated for the same cell.

Values:

testingenumerator

Planning data for development and testing, typically configured to be coarser and quick to generate.

productionenumerator

Planning data for deployment, typically configured to be finer and slower to generate.

PlannerSettingsstruct

Settings to instantiate the Planner.

Public Functions

PlannerSettings(stdstringcellName_:: , Profileprofile_ )

Initializes the settings for a cell and profile.

パラメータ:

• cellName_ -- The name of the cell

• profile_ -- The profile to plan with

stdstringtoString()const::

Get string representation of the PlannerSettings.

Public Members

stdstringcellName::

The name of the cell, which is the name of its folder in the Motion cell data directory.

Profileprofile

The profile of the cell's planning data to use.

BottomCenteredTransformedBoxstruct

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

Public Functions

stdstringtoString()const::

Get string representation of the BottomCenteredTransformedBox.

Public Members

Posetransform

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

Vector3fdimensions

The dimensions of the box.

ColorRGBAstruct

Color with red, green, blue and alpha channels.

Public Functions

stdstringtoString()const::

Get string representation of the ColorRGBA.

Public Members

runsignedchar

The red channel.

gunsignedchar

The green channel.

bunsignedchar

The blue channel.

aunsignedchar

The alpha channel.

Vector3fstruct

Vector of three coordinates as float, expressed in meters.

Public Functions

stdstringtoString()const::

Get string representation of the Vector3f.

Public Members

xfloat

The x coordinate.

yfloat

The y coordinate.

zfloat

The z coordinate.

Configurationclass

Joint angles of the robot, expressed in radians.

Public Types

value_type=floatusing

The type stored in the configuration.

const_iterator=Storageconst_iteratorusing ::

Iterator type for immutable access to the joint angles.

Public Functions

Configuration()=default

Default-constructs an empty configuration.

Configuration(stdinitializer_listfloat ::<>values)explicit

Constructs a Configuration from a list of joint angles.

< Iteratortemplatetypename>
Configuration( IteratorbeginItconst , IteratorendItconst )inline

Constructs a Configuration from the joint angles in the range [beginIt, endIt).

const_iteratorbegin()const

Iterator to the beginning of the joint angles.

const_iteratorend()const

Iterator to the end of the joint angles.

const_iteratorcbegin()const

Iterator to the beginning of the joint angles.

const_iteratorcend()const

Iterator to the end of the joint angles.

stdsize_tsize()const::

The number of joint angles.

operator[](stdsize_tindex:: )constconstfloat&

Access the specified joint angle.

data()constconstfloat*

Pointer to the underlying joint angle data.

==operator( Configuration&const other)constbool

Check if two configurations have equal joint angles.

stdstringtoString()const::

Get string representation of the Configuration.

Trianglestruct

A triangle defined by three Vector3f corners.

Public Functions

stdstringtoString()const::

Get string representation of the Triangle.

Public Members

Vector3fa

The first corner.

Vector3fb

The second corner.

Vector3fc

The third corner.

Diagnostics

PathDiagnosticsstruct

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.

Public Functions

stdstringtoString()const::

Get string representation of the PathDiagnostics.

Public Members

ConfigurationDiagnosticsstart

The diagnostics for the start configuration.

stdvectorstdoptionalConfigurationDiagnostics>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, holds no value.

ConfigurationDiagnosticsstruct

The collisions and joint limit violations found for a single configuration.

Public Members

stdvectorObstacleCollision obstacleCollisions::<>

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.

stdoptionalSelfCollision selfCollision::<>

The self-collision found for the configuration, if the robot collided with itself.

stdvectorJointLimitViolation jointLimitViolations::<>

All joint limit violations found for the configuration.

ObstacleCollisionstruct

Describes a single collision between the robot and an obstacle.

Public Members

stdvectorRobotPart robotParts::<>

The colliding robot parts, such as links, a carried object, replaceable tool or attachment.

Empty when the overlap cannot be attributed to a specific part.

ObstacleTypeobstacleType={ }

The kind of object the robot collided with.

stdstringobstacleName::

The name of the obstacle.

ObstacleTypeenumclass

The kind of object the robot collided with.

Values:

cellMeshenumerator

A static mesh belonging to the cell.

userMeshenumerator

A user-provided mesh obstacle.

userPointCloudenumerator

A user-provided point cloud obstacle.

SelfCollisionstruct

Describes the robot colliding with itself.

Public Members

stdvectorRobotPart robotParts::<>

The robot parts that touch each other, such as links, a carried object, replaceable tool or attachment.

JointLimitViolationstruct

Describes a single joint that is outside its limits.

The values are in the same unit as Configuration.

Public Members

stdstringjointName::

The name of the violating joint.

jointValue={float }

The requested joint value.

lowerLimit={float }

The lower joint limit.

upperLimit={float }

The upper joint limit.

Linkstruct

A robot link.

Public Members

uint32_tnumber={ }

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.

stdstringname::

The name of the link in the robot model.

Frames fixed to that link belong to the same part.

Attachmentstruct

An attachment mounted on the last link.

Public Members

uint32_tindex={ }

The index of the attachment, in the order the attachments were configured.

CarriedObjectstruct

The carried object held at the TCP.

ReplaceableToolstruct

The replaceable tool, reported as one part.

RobotPart=stdvariantLink Attachment CarriedObject ReplaceableToolusing ::<,,,>

A single robot part involved in a collision.

stdstringtoString( RobotPart&const robotPart)::

Get string representation of a robot part, such as "link_3" or "carried object".

Typedefs

Triangles=stdvectorTriangleusing ::<>

Vector of triangles, for example a triangle mesh.

ProgressCallback=stdfunctionvoiddouble stdstring)using ::<(,const::&>

A progress callback function type.

generate() calls it periodically during each stage. The percentage is the progress of the current stage.

Param progressPercentage:

The progress completion percentage (0 - 100%).

Param updateStageDescription:

A textual description of the progress stage.

Free Functions

generate( Application&const application, PlannerSettings&const plannerSettings, ProgressCallback& }const progressCallback={)void

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

Throws if the cell does not exist.

パラメータ:

• application -- Motion application

• plannerSettings -- Settings for generation

• progressCallback -- An optional progress callback function

packageCell( Application&const application, stdstring&const:: cellName, stdfilesystempath&const:::: outputPath, stdvectorProfile includeGeneratedDataconst::<>&)void

Packages a cell into a zip archive.

This function collects all files required to run the motion planner with the specified cell 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 output file already exists, or if the parent folder of the output path does not exist.

パラメータ:

• application -- Motion application

• cellName -- The name of the cell to package.

• outputPath -- The destination path for the generated zip archive, including the filename with ".zip" extension.

• includeGeneratedData -- What generated data to include.

stdfilesystempathpackageApiLog( Application&const application, stdfilesystempath&const:::: apiLogPath)::::

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 .zip extension instead of .json. This archive is all Zivid needs to reproduce the logged session.

パラメータ:

• application -- Motion application

• apiLogPath -- The path to the API log

戻り値:

The path to the created zip archive.

installPackage( Application&const application, stdfilesystempath&const:::: packagePath)void

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 -- Motion application

• packagePath -- The path to the cell package (zip archive) to install.

Experimental

MeshloadMesh( stdstring&const:: filename)

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.

パラメータ:

filename -- Path to the mesh file. A "package://" prefixed path is resolved against the Motion package directory; any other path is used as-is.

戻り値:

The mesh loaded from the file.

Meshmerge( MeshReferences&const meshes)

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.

パラメータ:

meshes -- A vector of references to the meshes to merge.

戻り値:

The merged Mesh instance.

stdvectorbool checkMeshCollisions( Planner&const planner, stdvectorConfiguration configurationsconst::<>&, unsignednumIgnoredLinksFromTip)::<>

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 numIgnoredLinksFromTip 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 numIgnoredLinksFromTip > 0.

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

パラメータ:

• planner -- The planner holding the robot model and environment

• configurations -- Configurations

• numIgnoredLinksFromTip -- Number of ignored links from tip

戻り値:

One bool per input configuration. True if the configuration is in collision, False otherwise.