se2ez is a library to support planning for kinematic trees in the plane. This library contains a set of tools for modeling and manipulating robots and robot states with the end goal of providing an efficient, modular interface for whatever robotic research goals you may have. In particular, this library is focused on supporting motion planning for general robots.

Documentation can be viewed online at https://kavrakilab.github.io/se2ez/

A Brief Overview

se2ez is split into a few high-level modules that separate different pieces of functionality. These modules so far are core, gui, and plan.

Core Module

The core module in se2ez provides all the modeling tools you might expect for kinematic robots. Currently, it has the tools to load or construct a se2ez::Robot (a kinematic tree) that is composed frames (se2ez::Frame), each which could be actuated by a joint (se2ez::Joint). Each frame can have multiple pieces of geometry (se2ez::Geometry) attached to it, which can be a box, circle, or polygon. From a se2ez::Robot, a se2ez::State can be constructed, which represents a configuration of the kinematic tree. Forward kinematics can be done using a se2ez::State. Inverse kinematics is provided through KDL in variations of a se2ez::TreeIK. Collision checking, along with signed distance computation, is provided through an se2ez::CollisionManager. Currently, there exists an implementation using Box2D, se2ez::Box2DCollisionManager. Using the collision checking manager, configuration space visualization is provided in se2ez::CSpaceGrid.

More features are coming soon (:tm:)! Many things are currently not "fully" documented, but Doxygen exists for most core classes.

Plan Module

The plan module offers OMPL constructs for motion planning using se2ez::Robots via the core modules kinematics.

More features are coming soon (:tm:)! Many things are currently not documented.

GUI Module

The gui modules in se2ez provide an interface to interactive visualization of a robot. The idea of the gui system is that there exist panels (se2ez::gui::Panel) that are held in main window (se2ez::gui::MainWindow). To craft a GUI for whatever your needs, it is simple to create a main window and add whatever panels you want. Currently, there exist the following panels:

se2ez::gui::JointPanel, for visualizing joint states and their component frames or geometry. Additionally, collisions, signed distance, and inverse kinematics are provided for interactive positioning and diagnostics of the robot.
se2ez::gui::PlanPanel, for interactive motion planning visualization through OMPL.
se2ez::gui::CSpacePanel, for interactive visualization of the configuration space of an existing robot.

Dependencies & Building

se2ez is dependent on the following libraries:

Eigen 3 or above (libeigen3-dev)
KDL 1.3 or above (liborocos-kdl-dev)
CGAL 3 or above (libcgal-dev and libcgal-qt5-dev)
Boost 1.58 or above (libboost-all-dev)
Qt 5.9.5 or above (qtdeclarative5-dev)
Box2D (libbox2d-dev)

You can install these all with the following command from apt if on and Ubuntu machine:

sudo apt-get install \
  libeigen3-dev \
  liborocos-kdl-dev \
  libcgal-dev \
  libcgal-qt5-dev \
  libboost-all-dev \
  qtdeclarative5-dev \
  libbox2d-dev

se2ez also uses OMPL and yaml-cpp as git submodules. Before building, make sure the submodule is updated, either at initial clone or with:

git submodule update --init --recursive

se2ez uses cmake. Simply run the following in the top-level directory to build the library and scripts:

mkdir -p build/release
cd build/release
cmake ../..
make

If you need debugging symbols, run the following in the top-level directory:

mkdir -p build/debug
cd build/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../..
make

If you need the compile flags, use the following argument:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ../..

YAML File

An example of the YAML file format that describes a se2ez::Robot is given in yaml/test.yml, and also below:

robot:                # All files must begin with "robot"
  - name: "base"      # The name of the frame within the robot
    joint: "fixed"    # The joint type. Can be from the following: 
                      #   ["fixed", "float", "flying", "translate", "prismatic", "revolute", "continuous"]
    parent: "root"    # The frame's parent in the tree. "root" always exists and is the root of the tree.
    tip: [0, 0, 0]    # The transform to this frame's time, given as [x, y, theta]
  - name: "link_1"
    joint: "revolute"
    parent: "base"
    tip: [1, 0, 0]
    limits:           # If a joint is controllable, it must have limits (limits can be omitted if fixed)
      upper: 1.57     # Revolute joints (and prismatic) are 1-d, so a single value can be given for upper and lower limits
      lower: -1.57
    geometry:         # Geometry is attached to the frame at the tip, and is a list of all geometry attached
      - type: "box"               # The geometry type. Can be from the following:
                                  #   ["box", "circle", "convex", "simple"]
        dimensions: [0.1, 0.1]    # The dimensions of the geometry. Dimensions is type specific.
        color: [0.5, 0.5, 0.5, 1] # Color of geometry. [r, g, b, a]
        offset: [0, 0, 0]         # Offset transfrom from frame's tip (optional)
  - name: "block"
    joint: "float"
    parent: "root"
    limits:
      upper: [1, 1, 1.57]    # As joint is floating, specify bounds on [x, y, theta]
      lower: [-1, -1, -1.57]
    allowed: ["link_1"]      # Allowable collisions can be specified as a list.
    geometry:
      - type: "convex"
        points:              # For polygon types, the points of the polygon are a list.
          - [0.1, 0.1]
          - [0.5, 0.1]
          - [0.1, 0.5]
        color: [0.5, 0.5, 0.5, 1]
...
states:                      # Files can also have named states that can be retrieved from the robot.
                             # This is a list of named states.
  - name: "start"            # Each state must have a name.
    configuration:           # Each state must also have its configuration, a list of per frame joint values dependent 
                             # on joint type.
      - frame: "link_1"      # Name of the frame / joint
        value: [0]           # Value
      - frame: "block"
        value: [0, 0, 1.57]
...
constraints:            # Files can also have named constraints that can be retrieved.
  - name: "bar_1"       # This is a list of named constraints.
    type: "line"        # Type can be ["point", "line"]
    ee: "ee"            # End-effector this line constraint is for. Must be in robot.
    a: [-1.0, -1.0]     # First end point of the constraint line.
    b: [ 5.0,  4.0]     # Second end point of the constraint line.
  - name: "hold"  
    type: "point"
    ee: "ee"        
    base: "root"        # All constraints can have a different base frame specified.
    point: [-1.0, -1.0] # First end point of the constraint line.

Named states can be loaded separately.

Scripts

Some example scripts are provided within the scripts/ directory. These are organized based upon the module the feature they are showcasing is from. More documentation is forthcoming.

Core Scripts

collision.cpp: Demonstrates how to use a se2ez::CollisionManager.
cspace.cpp: Simple utility for generating configuration space slice images from the command-line.
geometry.cpp: Demonstration of some of the geometry operations provided for polygon processing.
ik.cpp: Demonstration of how to use the inverse kinematic solvers from se2ez::IKSolver.
robot.cpp: Demonstration of how to construct a robot (se2ez::Robot) in code.
yaml.cpp: Command-line utility for loading a robot and printing debug information.

GUI Scripts

plan_gui.cpp: Simple GUI for doing interactive planning.
cspace_gui.cpp: Simple GUI for visualizing configuration space slices.

Plan Scripts

plan.cpp: Demonstration of how to build a robot and then plan motions using se2ez::plan::EZPlans.
plan_yaml.cpp: Simple command-line utility for planning for a robot loaded from YAML.
plan_constraint.cpp: Simple command-line utility for planning for a robot loaded from YAML under a YAML-loaded constraint.