Quickstart

Introduction

This article is a quick introduction to Zivid Motion. It will show you how to unpack a cell, generate planning data and plan paths avoiding simple obstacles. The aim for this quickstart guide is to give a simple example without diving too deep into details.

If you haven’t already installed Zivid Motion, head over to Installation and return to this article once you’ve installed Zivid Motion.

Unpacking the cell

The cell data is provided in a zip file next to the installation files you got from the Zivid Motion team.

~/Downloads/motion-quickstart/
├─ data.zip
├─ zivid_pythonmotion*.whl
├─ zivid-motion*.deb

The very first thing you need to do is to unpack the cell data:

$ unzip data.zip -d ~/.local/share/Motion/

~/.local/share/Motion/ should now contain data needed for this quickstart guide. To learn more about the contents of this directory, see the Cell data section in Data and configuration files.

Generate planning data

You need to generate planning data before you can start planning. This is a pre-processing step that accelerates the runtime planner calculations. You need to re-generate whenever changes are made to source files in ~/.local/share/Motion/, the planner will throw an error if you forget.

Run the code below to generate. Generation time depends on the specs of your system, but should not take more than a minute for this example.

from zividmotion.zividmotion import generate, GenerationSettings

DATA_TAG = "my_cell"
CONFIG = "Testing"

generation_settings = GenerationSettings.from_dict(
  {
      "DataTag": DATA_TAG,
      "GenerateConfig": CONFIG,
  }
)
print("Generating...")
generate(
    generation_settings=generation_settings,
    progress_callback=lambda progress, step: print(f"Generation progress on step {step}: {progress:.2f}% complete")
)
print("Generation complete. Results stored on drive under data-tag.")

Planning paths

Time to plan some paths! The simple example below will lead you through four simple steps:

  1. Initialize the planner

  2. Plan a path from one joint configuration to another

  3. Set an simple geometric obstacle to block the path

  4. Plan the path again, and see how the planner finds a new path around the obstacle

from zividmotion.zividmotion import create_box_mesh, Planner, PlannerSettings, Obstacle, InitialState

DATA_TAG = "my_cell"
CONFIG = "Testing"

'''
  A visual representation of the cell will open when initializing the planner with UseVisualizer set to True.
'''
planner_settings = PlannerSettings.from_dict(
  {
      "DataTag": DATA_TAG,
      "CellConfig": CONFIG,
      "UseVisualizer": True,
  }
)

print("1. Initializing planner...")
planner = Planner(planner_settings=planner_settings)
print("Planner successfully initialized.")

start_joint_config = [0.0, -1.27, 1.83, 2.7, -1.42, 0]

input("2. Press Enter to plan path to goal...")

'''
  A simple planning problem where the shortest path is spinning the first joint 180 degrees.
'''
goal_configuration = [3.14, -1.27, 1.83, 2.7, -1.42, 0]

plan_result_1 = planner.path(initial_state=InitialState(start_joint_config), goal_configurations=[goal_configuration])

print(plan_result_1)

input("3. Press Enter to set an obstacle...")

'''
  This obstacle will block the direct path, forcing the planner to find a new path around it.
'''
box_mesh = create_box_mesh(center_point=[0,-600,350], size=[120,400,500])
obstacle = Obstacle(name='obstacle', triangles=box_mesh)
planner.set_obstacles(obstacles=[obstacle])

input("4. Press Enter to plan path to goal again...")

plan_result_2 = planner.path(initial_state=InitialState(start_joint_config), goal_configurations=[
  goal_configuration
])

'''
  The planner should now have found a new path around the obstacle. When comparing the two
  plan results, you can see that plan_result_2 contains multiple waypoints to pass around
  the obstacle.
'''
print(plan_result_1)
print(plan_result_2)

input("Press Enter to finish tutorial")

Next steps

This was a very quick introduction to Zivid Motion to give you an idea of how to use the runtime API to plan paths and set dynamic obstacles in the environment. Recommended next readings are: