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

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.

Public Functions

Planner createPlanner(PlannerSettings plannerSettings) 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

std::string toString() const

Get string representation of the Application.

class Planner

Plans collision-free robot paths in a cell.

Create a Planner with Application::createPlanner().

Public Functions

ConfigurationGoals computeInverseKinematics(const PoseGoals &poses, const Configuration &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.

PathResult path(const InitialState &initialState, const PathRequest &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

void setObstacles(const std::vector<Obstacle> &obstacles)

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

void clearObstacles()

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

void setCarriedObject(const Mesh &carriedObject)

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

void clearCarriedObject()

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

void setReplaceableTool(const ReplaceableTool &replaceableTool)

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

void clearReplaceableTool()

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

void setAttachments(const std::vector<std::string> &attachments)

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.

void setTcp(const Tcp &tcp)

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

Tcp getTcp() const

Returns the current Tool Center Point of the robot.

戻り値:

The current TCP

void clipPointCloudWithBox(const BottomCenteredTransformedBox &box)

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.

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

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.

std::filesystem::path exportApiLog(const std::optional<std::filesystem::path> &outputDirectory = std::nullopt)

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.

void replayApiLog(const std::filesystem::path &path)

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.

std::string toString() const

Get string-representation of Planner

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

Public Functions

void setRobotConfiguration(const 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 -- The robot configuration to display

void wait()

Blocks until the user closes the visualization window.

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

Public Static Functions

static Visualizer viewPlanner(Planner &planner)

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

static Visualizer viewCell(const Application &application, const std::string &cellName)

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

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.

Public Functions

InitialState(const Configuration &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(const PathResult &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

std::string toString() const

Get string representation of the InitialState.

Public Static Functions

static InitialState FromTouch(const Configuration &startConfiguration)

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

struct PathRequest

Request to pass to a path call.

Public Types

enum class Type

Used to specify the motion type.

Values:

enumerator free

For moving in free space.

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

enum class GoalPrioritizationMethod

Used to specify the goal prioritization method.

Values:

enumerator listOrder

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

enumerator shortestPath

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

Public Functions

std::string toString() const

Get string representation of the PathRequest.

Public Members

ConfigurationGoals goals

The goals to plan to.

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

Type type = Type::free

Decides the motion type.

GoalPrioritizationMethod goalPrioritizationMethod = GoalPrioritizationMethod::shortestPath

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

std::optional<Vector3f> 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.

std::optional<std::string> description = {}

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

std::optional<float> 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.

bool diagnoseFailures = {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.

struct BlendRadius

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

std::string toString() const

Get string representation of the BlendRadius.

Public Members

float entry

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.

float exit

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.

struct Waypoint

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

Public Types

enum class Movement

Enum describing different ways the robot can move between waypoints.

Values:

enumerator joint

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

enumerator linear

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

Public Functions

std::string toString() const

Get string representation of the Waypoint.

Public Members

Configuration configuration

The joint configuration of the waypoint.

Movement movement

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.

BlendRadius blendRadius

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.

class Path

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

Public Types

using value_type = Waypoint

The type of the elements stored in the path.

using const_iterator = std::vector<Waypoint>::const_iterator

Iterator type for immutable access to the waypoints.

Public Functions

const_iterator begin() const

Iterator to the beginning of the waypoints.

const_iterator end() const

Iterator to the end of the waypoints.

const_iterator cbegin() const

Iterator to the beginning of the waypoints.

const_iterator cend() const

Iterator to the end of the waypoints.

std::size_t size() const

The number of waypoints in the path.

bool empty() const

Check whether the path contains no waypoints.

const Waypoint &operator[](std::size_t index) const

Access the waypoint at the given index.

const Waypoint &front() const

Access the first waypoint in the path.

const Waypoint &back() const

Access the last waypoint in the path.

std::string toString() const

Get string representation of the Path.

class PathResult

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

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

Public Types

enum class Error

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

Values:

enumerator blockedStart

The start configuration is blocked.

enumerator blockedEnd

All the valid goal configurations are blocked.

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

enumerator kinematicViolation

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

Public Functions

Path path() 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

Configuration finalConfiguration() 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

explicit operator bool() const

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

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

std::string toString() const

Get string representation of the PathResult.

Public Members

std::optional<Error> error

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

std::optional<uint32_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.

Tcp tcp

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.

std::optional<Diagnostics::PathDiagnostics> 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.

class Obstacle

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

using PointCloud = std::vector<Vector3f>

A vector of points representing a point cloud.

using Colors = std::vector<ColorRGBA>

A vector of colors.

Public Functions

std::string toString() const

Get string representation of the Obstacle.

Public Static Functions

static Obstacle fromMesh(std::string name, const Mesh &mesh)

Initializes an Obstacle instance from a Mesh.

static Obstacle fromPointCloud(std::string name, PointCloud pointCloud)

Initializes an Obstacle instance from a point cloud.

static Obstacle fromColoredPointCloud(std::string name, PointCloud pointCloud, Colors colors)

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.

class Mesh

A triangle mesh.

Public Functions

Triangles toTriangles() 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.

std::size_t triangleCount() const

Returns the number of triangles in the mesh.

戻り値:

The number of triangles.

Mesh transform(const Pose &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.

Mesh bottomCenterTransform() 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.

Mesh withColor(const ColorRGBA &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

static Mesh fromTriangles(const Triangles &triangles)

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.

static Mesh createBox(const Vector3f &extents)

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.

static Mesh createCylinder(float radius, float height, unsigned resolution = 64)

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.

static Mesh createSphere(float radius, unsigned resolution = 64)

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.

struct ToolGeometry

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

Public Members

Mesh rigidSection

The mesh of the rigid section of the tool

std::optional<Mesh> compliantSection = std::nullopt

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.

Public Functions

ReplaceableTool(std::string name, ToolGeometry geometry)

Constructs a replaceable tool with the given name and geometry.

パラメータ:

• name -- The name of the replaceable tool.

• geometry -- The geometry of the replaceable tool.

std::string toString() const

Get string representation of the ReplaceableTool.

struct Tcp

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

It contains the transform and tool direction.

Public Functions

std::string toString() const

Get string representation of the Tcp.

Public Members

Pose transform

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

Vector3f toolDirection

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

This is used for interaction planning in Touch operations.

struct ConfigurationGoal

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

Public Functions

std::string toString() const

Get string representation of the Goal.

Public Members

Configuration configuration

The configuration to attempt to plan to

class ConfigurationGoals

A collection of path-planning goals.

Public Functions

ConfigurationGoals(const std::vector<Configuration> &jointConfigurations)

Initializes a ConfigurationGoals instance directly from a vector of configurations.

パラメータ:

jointConfigurations -- The joint configurations

ConfigurationGoals(const std::vector<ConfigurationGoal> &goals)

Initializes a ConfigurationGoals instance from a vector of goals.

パラメータ:

goals -- The goals

const std::vector<std::optional<ConfigurationGoal>> &goals() const

Returns the stored goals

戻り値:

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

bool noneValid() const

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

std::string toString() const

Get a string representation of the object.

struct PoseGoal

A goal given as a TCP pose.

Public Functions

std::string toString() const

Get a string representation of the object.

Public Members

Pose pose

The pose to compute a joint configuration for.

class PoseGoals

A collection of pose goals.

Public Functions

PoseGoals(const std::vector<Pose> &poses)

Initializes a PoseGoals instance directly from a vector of poses.

パラメータ:

poses -- The poses

PoseGoals(const std::vector<PoseGoal> &goals)

Initializes a PoseGoals instance from a vector of goals.

パラメータ:

goals -- The goals

const std::vector<PoseGoal> &goals() const

Returns the stored goals

std::string toString() const

Get a string representation of the object.

class Pose

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(const Matrix4x4 &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.

Pose compose(const Pose &other) const

Composes this pose with another pose.

パラメータ:

other -- The transform applied first.

戻り値:

The pose that applies other followed by this pose.

Matrix4x4 toMatrix() const

Converts the pose to a 4x4 matrix.

戻り値:

4 by 4 matrix.

std::string toString() const

Get string representation of the Pose.

戻り値:

Pose as string.

Public Static Functions

static Pose fromXyzRpy(const Vector3f &translation, float roll, float pitch, float yaw)

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.

class Matrix4x4

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

Public Types

using ValueType = float

The type stored in the matrix.

using Iterator = std::array<float, 16>::iterator

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

using ConstIterator = std::array<float, 16>::const_iterator

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

Public Functions

Matrix4x4() = default

Default-constructs a zero-initialized matrix.

explicit Matrix4x4(const std::array<float, rows * cols> &data)

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

explicit Matrix4x4(std::initializer_list<float> values)

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

Throws if the list does not have 16 elements.

explicit Matrix4x4(std::initializer_list<std::initializer_list<float>> values)

Constructs a Matrix4x4 from a nested initializer list.

Each inner list is a row.

Throws if there are not 4 rows of 4 elements.

Iterator begin()

Iterator to the beginning of the matrix.

Iterator end()

Iterator to the end of the matrix.

ConstIterator begin() const

Iterator to the beginning of the matrix.

ConstIterator end() const

Iterator to the end of the matrix.

ConstIterator cbegin() const

Iterator to the beginning of the matrix.

ConstIterator cend() const

Iterator to the end of the matrix.

float &at(std::size_t row, std::size_t col)

Access specified element with bounds checking.

Throws if the row or column is out of range.

const float &at(std::size_t row, std::size_t col) const

Access specified element with bounds checking.

Throws if the row or column is out of range.

float &operator()(std::size_t row, std::size_t col)

Access specified element without bounds checking.

const float &operator()(std::size_t row, std::size_t col) const

Access specified element without bounds checking.

float *data()

Pointer to the underlying row major data.

const float *data() const

Pointer to the underlying row major data.

Matrix4x4 inverse() const

Get the inverse of this matrix.

std::string toString() const

Get string representation of the Matrix4x4.

Public Static Functions

static Matrix4x4 identity()

Get the identity matrix.

Public Static Attributes

static constexpr std::size_t rows = {4}

The number of rows in the matrix.

static constexpr std::size_t cols = {4}

The number of columns in the matrix.

enum class Profile

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:

enumerator testing

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

enumerator production

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

struct PlannerSettings

Settings to instantiate the Planner.

Public Functions

PlannerSettings(std::string cellName_, Profile profile_)

Initializes the settings for a cell and profile.

パラメータ:

• cellName_ -- The name of the cell

• profile_ -- The profile to plan with

std::string toString() const

Get string representation of the PlannerSettings.

Public Members

std::string cellName

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

Profile profile

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

struct BottomCenteredTransformedBox

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

Public Functions

std::string toString() const

Get string representation of the BottomCenteredTransformedBox.

Public Members

Pose transform

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

Vector3f dimensions

The dimensions of the box.

struct ColorRGBA

Color with red, green, blue and alpha channels.

Public Functions

std::string toString() const

Get string representation of the ColorRGBA.

Public Members

unsigned char r

The red channel.

unsigned char g

The green channel.

unsigned char b

The blue channel.

unsigned char a

The alpha channel.

struct Vector3f

Vector of three coordinates as float, expressed in meters.

Public Functions

std::string toString() const

Get string representation of the Vector3f.

Public Members

float x

The x coordinate.

float y

The y coordinate.

float z

The z coordinate.

class Configuration

Joint angles of the robot, expressed in radians.

Public Types

using value_type = float

The type stored in the configuration.

using const_iterator = Storage::const_iterator

Iterator type for immutable access to the joint angles.

Public Functions

Configuration() = default

Default-constructs an empty configuration.

explicit Configuration(std::initializer_list<float> values)

Constructs a Configuration from a list of joint angles.

template<typename Iterator>
inline Configuration(const Iterator beginIt, const Iterator endIt)

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

const_iterator begin() const

Iterator to the beginning of the joint angles.

const_iterator end() const

Iterator to the end of the joint angles.

const_iterator cbegin() const

Iterator to the beginning of the joint angles.

const_iterator cend() const

Iterator to the end of the joint angles.

std::size_t size() const

The number of joint angles.

const float &operator[](std::size_t index) const

Access the specified joint angle.

const float *data() const

Pointer to the underlying joint angle data.

bool operator==(const Configuration &other) const

Check if two configurations have equal joint angles.

std::string toString() const

Get string representation of the Configuration.

struct Triangle

A triangle defined by three Vector3f corners.

Public Functions

std::string toString() const

Get string representation of the Triangle.

Public Members

Vector3f a

The first corner.

Vector3f b

The second corner.

Vector3f c

The third corner.

Diagnostics

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

Public Functions

std::string toString() const

Get string representation of the PathDiagnostics.

Public Members

ConfigurationDiagnostics start

The diagnostics for the start configuration.

std::vector<std::optional<ConfigurationDiagnostics>> 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.

struct ConfigurationDiagnostics

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

Public Members

std::vector<ObstacleCollision> 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.

std::optional<SelfCollision> selfCollision

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

std::vector<JointLimitViolation> jointLimitViolations

All joint limit violations found for the configuration.

struct ObstacleCollision

Describes a single collision between the robot and an obstacle.

Public Members

std::vector<RobotPart> 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.

ObstacleType obstacleType = {}

The kind of object the robot collided with.

std::string obstacleName

The name of the obstacle.

enum class ObstacleType

The kind of object the robot collided with.

Values:

enumerator cellMesh

A static mesh belonging to the cell.

enumerator userMesh

A user-provided mesh obstacle.

enumerator userPointCloud

A user-provided point cloud obstacle.

struct SelfCollision

Describes the robot colliding with itself.

Public Members

std::vector<RobotPart> robotParts

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

struct JointLimitViolation

Describes a single joint that is outside its limits.

The values are in the same unit as Configuration.

Public Members

std::string jointName

The name of the violating joint.

float jointValue = {}

The requested joint value.

float lowerLimit = {}

The lower joint limit.

float upperLimit = {}

The upper joint limit.

struct Link

A robot link.

Public Members

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

std::string name

The name of the link in the robot model.

Frames fixed to that link belong to the same part.

struct Attachment

An attachment mounted on the last link.

Public Members

uint32_t index = {}

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

struct CarriedObject

The carried object held at the TCP.

struct ReplaceableTool

The replaceable tool, reported as one part.

using RobotPart = std::variant<Link, Attachment, CarriedObject, ReplaceableTool>

A single robot part involved in a collision.

std::string toString(const RobotPart &robotPart)

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

Typedefs

using Triangles = std::vector<Triangle>

Vector of triangles, for example a triangle mesh.

using ProgressCallback = std::function<void(double, const std::string&)>

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

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

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

void packageCell(const Application &application, const std::string &cellName, const std::filesystem::path &outputPath, const std::vector<Profile> &includeGeneratedData)

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.

std::filesystem::path packageApiLog(const Application &application, const std::filesystem::path &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.

void installPackage(const Application &application, const std::filesystem::path &packagePath)

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

Mesh loadMesh(const std::string &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.

Mesh merge(const MeshReferences &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.

std::vector<bool> checkMeshCollisions(const Planner &planner, const std::vector<Configuration> &configurations, unsigned numIgnoredLinksFromTip)

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.