Data and configuration files

The following sections aim to give an overview of the configuration files for Zivid Motion, where they are located, and how to edit some of them.

Cell data

Cell configurations live in ~/.local/share/Motion/. This directory has two first-level subdirectories:

A data/ directory containing data tags. A data tag is a directory containing one cell definition.
A packages/ directory containing files that can referenced by and shared between multiple data tags. The contents of this directory is typically URDF files and meshes.

~/.local/share/Motion/
├─ data/
│  ├─ my_cell/
│  │  ├─ UserConfiguration.yml
│  │  ├─ config.zmd
│  │  ├─ ...
├─ packages/
│  ├─ my_cell/
│  │  ├─ meshes/
│  │  │  ├─ link_1.stl
│  │  │  ├─ ...
│  │  ├─ urdf/
│  │  │  ├─ robot.urdf
│  │  │  ├─ ...

Packaging

Zivid Motion provides functionality to package, share, and install cell configurations:

packageDataTag() collects all files required to execute the planner with the specified data tag into a zip archive.
packageApiLog() creates a zip file containing the files required to replay a specified API log.
installPackage() extracts a package’s contents into ~/.local/share/Motion/.

Example invocations from the command line using the Python API is shown below:

python -c 'import zividmotion; zividmotion.package_data_tag(data_tag="my_cell", output_path="my_cell_all.zip", include_generated_data=["Testing", "Production"])'
python -c 'import zividmotion; zividmotion.install_package(package_path="my_cell_all.zip")'
python -c 'import zividmotion; print(zividmotion.package_api_log(api_log_path="/path/to/api_log.json"))'

UserConfiguration.yml

The user configuration file is where the user can define cell configuration prior to runtime. It can be found in ~/.local/share/Motion/data/<data-tag>/UserConfiguration.yml. Changes to this file will require a re-generation.

Note

Frame references in UserConfiguration.yml should only refer to existing links in the urdf files. As an example, if the cell’s base frame is set to CellBaseFrame: "base_link", then <link name="base_link"/> must be defined in the urdf files.

Fields

AdaptivePart

The optional adaptive part is a container for objects that can be picked by the robot. It can be updated during runtime and covers both replaceable tools and carried objects.

AdaptivePart.SelfCollisionCheckLinks is a list of link indices that should be checked for self-collisions with the adaptive part.
AdaptivePart.Frame is the frame for the adaptive part. This frame is used to define the position and orientation of the bottom center of the adaptive part. The z-axis of the frame needs to be aligned with the rotation axis of the last joint, typically the flange frame.
AdaptivePart.Width is the adaptive part width in meters.
AdaptivePart.Height is the adaptive part height in meters.
AdaptivePart.DiscretizationWidth is the discretization width for the adaptive part in meters.
AdaptivePart.DiscretizationHeight is the discretization height for the adaptive part in meters.

The adaptive part’s width applies to both the local x and y direction. Large adaptive parts with low discretization values, will require more RAM and compute power than smaller, lower resolution adaptive parts.

Attachments

Attachments.SelfCollisionCheckLinks is a list of link indices that should be checked for self-collisions with the attachments.
Attachments.AttachmentList is a list of Attachment.

Attachment

An attachment that can be used as extensions of the robots last link. An attachment can be used to represent tools or object that are always held the same way.

Attachment.Id is a unique identifying string for the attachment.
Attachment.CadFilename is the filename of the CAD file for the attachment.
Attachment.Transform is the transform of the attachment relative to the flange frame.
Attachment.TouchCompliance specifies optional compliance Distance in meters and Direction for the attachment during touch motions. This can be used to model for instance compliant suction cups on grippers. The Direction specifies the direction of motion where the attachment will comply, expressed in the attachment frame.

CellBaseFrame

The base frame for the cell. This is the reference frame for all pose goals.

DefaultTcp

The default Tool Center Point for the robot. The TCP is the reference frame for carried objects.

DefaultTcp.Transform is the transform of the TCP relative to the flange frame.
DefaultTcp.ToolDirection is the preferred direction the TCP interacts with the world in, expressed in the TCP frame.

DynamicEnvironmentSafetyDistance

Added safety distance around the dynamic environments in meters. Higher values will increase the clearance to the dynamic environments when possible, but might also require more RAM and compute power.

FlangeFrame

Flange frame is the reference frame for TCPs and replaceable tools.

KinematicsSolver

Details about the kinematics solver to be used for the robot.

KinematicsSolver.InnerFrameOverride is an optional override for the inner frame of the kinematics solver. This specifies the first frame in the kinematics chain, considered by the kinematics solver. If the override is unset, it defaults to the robot base frame.
KinematicsSolver.OuterFrame is the outer frame of the kinematics solver. This is the last frame in the kinematics chain, considered by the kinematics solver.

RobotBaseFrameOverride

Optional override for the base frame for the robot. Can be used if the robot’s base frame is different than the cell’s base frame. If the override is unset, the robot base frame will be set to the same frame as the cell base.

UrdfFilenames

List of Urdf files for both the robot and the static environment.

StaticEnvironmentSafetyDistance

Added safety distance around the static environments in meters. Higher values will increase the clearance to the static environments when possible, but might also require more RAM and compute power.

Workspace

The workspace defines the physical limits of the robot’s operation area.

Frame is the reference frame for the workspace.
BottomCenterPosition is the position of the bottom center of the workspace in the workspace frame, specified in meters.
Dimensions is the size of the workspace along each axis in the workspace frame, specified in meters.
VoxelSize defines the physical dimensions, in meters, of each voxel in the 3D space. A lower value means more voxels (higher resolution), and will require more RAM and compute power. You can set different values for the two cell configurations Testing and Production. A common use case is to set a lower resolution in Testing for rapid iterations with faster generation and lower resource requirements during development.
RegionsOfInterest is an optional list of regions of interest within the workspace. See Regions of Interest for more details.

RegionOfInterest

When specified, the regions of interest are the only areas where the environment can be updated and considered dynamic. Areas outside the regions of interest are considered static. This is useful to reduce the memory requirements when only a given part of the workspace is changing. This is typically the case in pick-and-place applications, where only the area around the pick-and-place positions are changing.

Id is a unique identifying string for the region of interest.
BottomCenterPosition is the position of the bottom center of the region of interest in the workspace frame, specified in meters.
Dimensions is the size of the region of interest along each axis, specified in meters.
EscapeDirections is the preferred direction for escaping the region of interest, when escaping or entering cluttered areas. This should be defined in the direction “out” of the region of interest. In the case of entering a region of interest, the resulting path will move in the opposite direction of the escape direction. For a bin picking scenario, this is typically vertically upwards.
CalculateEnvironmentEscapeDirection defines if the escape direction should be calculated from the proximity of obstacles in the environment. If set to true, the calculated escape direction will get priority over the manually defined escape directions. If neither EscapeDirections nor CalculateEnvironmentEscapeDirection are defined, the planner will automatically calculate the escape direction using the DefaultTcp.

Example file

Below is an example UserConfiguration.yml file.

__version__: 1
UserConfigurationFile:
    AdaptivePart:
        SelfCollisionCheckLinks: [0, 1, 2, 3]
        DiscretizationHeight: 0.02
        DiscretizationWidth: 0.03
        Frame: "adaptive_part_frame"
        Height: 0.6
        Width: 0.8
    Attachments:
        SelfCollisionCheckLinks: [0, 1, 2, 3]
        AttachmentList:
            - Attachment:
                  Id: "gripper"
                  CadFilename: "package://zivid/meshes/gripper.stl"
                  Transform:
                      Position:
                          X: 0
                          Y: 0
                          Z: 0.1
                      Rotation:
                          Roll: 3.14159265
                          Pitch: 0
                          Yaw: 0
    CellBaseFrame: "base_link"
    DefaultTcp:
        Transform:
          Position:
              X: 0
              Y: 0
              Z: 0
          Rotation:
              Roll: 0
              Pitch: 0
              Yaw: 0
        ToolDirection:
            X: 0
            Y: 0
            Z: -1
    DynamicEnvironmentSafetyDistance: 0.06
    FlangeFrame: "flange_frame"
    KinematicsSolver:
        OuterFrame: "link6"
    StaticEnvironmentUrdfFilenames:
          - File:
                NameStr: "package://urdf/trolley.urdf"
    StaticEnvironmentSafetyDistance: 0
    UrdfFilenames:
        - File:
              NameStr: "package://urdf/robot.urdf"
    Workspace:
        Frame: world
        BottomCenterPosition: { X: 0, Y: 0, Z: 0.0 }
        Dimensions: { X: 5.0, Y: 5.0, Z: 3 }
        VoxelSize:
            Production: 0.02
            Testing: 0.05
        RegionsOfInterest:
            - RegionOfInterest:
                  Id: pick_area
                  BottomCenterPosition: { X: 1.0, Y: 0.0, Z: 0.0 }
                  Dimensions: { X: 2, Y: 1, Z: 3 }
                  EscapeDirections:
                      - EscapeDirection: { X: 0.0, Y: 0.0, Z: 1.0 }
                  CalculateEnvironmentEscapeDirection: "yes"

RuntimeConfiguration.yml

Description

The planner will create the runtime configuration file ~/.config/Zivid/Motion/RuntimeConfiguration.yml the first time it is started. The ApiLog section of the configuration file has three options.

Setting the option ContinuouslySaveSetObstaclesDetails: yes will save details about each SetObstacles call individually. Take note that this requires more memory, and the cumulative size of the api log files can become large, and this feature should typically only be used for debugging purposes.

Setting Trigger to Never will disable writing of api log files. Setting Trigger to EveryPathCall will enable writing of api log files after every path call. Take note that this will introduce a performance overhead, and the cumulative size of the api log files can become large, and should typically only be used for debugging purposes. Setting Trigger to OnException will enable saving of api log files if an exception is thrown during a path call.

With the default value Folder: __not_set__ the planner will save api log files in the default folder, which is <USER_HOME>/.cache/Zivid/Motion/State. Change to Folder:<API_LOG_FOLDER> to save the api log files in <API_LOG_FOLDER> instead.

Example file

Below is an example RuntimeConfiguration.yml file.

__version__: 1
RuntimeConfiguration:
  ApiLog:
    ContinuouslySaveSetObstaclesDetails: no
    Trigger: Never
    Folder: __not_set__