The CuikSuite Documentation
[Introduction] [Installation] [Tutorial] [Support] [Applications] [Benchmarks] [Disclaimer]



Introduction

The CuikSuite is a set of applications to solve position analysis and path planning problems with applications mainly to robotics, but also to molecular biology.

The CuikSuite algorithms are specially adequate for systems with one of more kinematic loops and with a dimensionality of the configuration space much below the cardinality of the problem (i.e., the number of degrees of freedom of the system is much below the number of variables in the problem). This type of system is specially hard to deal with other position analysis/path planning systems.

Some of the key features of the CuikSuite are:

  • Position analysis (including direct/inverse kinematics) of arbitrary systems using branch-and-bound techniques.
  • Singularity analysis of arbitrary robotic systems.
  • Parallel implementation (multi-core) of the branch-and-bound techniques.
  • Path planning for systems with arbitrary kinematic constraints using higher-dimensional continuation tools.
  • Assymptotically optimal path planners for kinematically constrained problems.
  • Grasp synthesis and optimization for general hands and objects.
  • Generation of the kinematic equations from high level robot descriptions.
  • Import models from ROS (URDF files).
  • Generation of kinematic problems from molecular files.
  • Motion analysis for molecular systems.
  • Comprehensive set of tools to manipulate robot models and to visualize solution sets and paths.

This CK-13 paper gives a general description to the tools included in the CuikSuite. Further details on the techniques and application implemented in the CuikSuite can be found in our publications:

Please, note that there is a previous version of the CuikSuite that only included the branch-and-prune methods based on linear relaxations and was basically oriented to position analysis. This former version was used to obtain the results of our TRO-09 paper. This version can be downloaded from here.

The CuikSuite has been developed in the context of a series of projects mainly founded by the Spanish Goverment. For more information about this project, including publications that introduce the algorihtms implemented in the CuikSuite see the project webpage.

Installation

License

The CuikSuite has been developed by the KRD group at IRI as a part of the Cuik project and is licensed under GPLv3 License.

For the impatient

If you are only interested in testing whether or not the CuikSuite is adequate for your needs (and you have a large bandwidth) you can download this virtual machine (3Gb) that can be imported to VirtualBox. The virtual machine has an Ubuntu linux 14.04 LTS (64 bits) with CuikSuite already installed and compiled. The performance of the suite, however, is low due to the virtualization. Moreover, the version of the CuikSuite on this virtual machine is a bit oudated, although it includes the main functionalities.

The virtual machine has just one user (cuiksuite) whose password is the username.

A virtual machine with a previous version of the CuikSuite on a Ubuntu 12.02 (32 bits) can be downloaded here.

For the Ubuntu-addicted

For convenience, we offer pre-compiled Ubuntu pacakges to install the CuikSuite via apt-get. Only packages for Ubuntu Trusty 14.04 LTS are available..

IMPORTANT: This binary distribution works on a clean Ubuntu install. If you already installed different (newer or older) version of the libaries used by the CuikSuite (e.g., clp, openbabel, assimp) then the installation will generate a conflict. Some users also informed that geomview also genererates a conflict with imagemagick package.

To use the pre-compile packages execute the folowing in a terminal:

  • sudo su
  • echo "deb http://www.iri.upc.edu/cuik/ubuntu trusty main" >> /etc/apt/sources.list
  • exit

replace trusty by precise if you are using Ubuntu 12.04 instead of 14.04.

Get the key used to sign the packages

  • gpg –keyserver keyserver.ubuntu.com –recv 750D212D
  • gpg –export –armor 750D212D | sudo apt-key add -

Now we can install the CuikSuite executing

  • sudo apt-get update
  • sudo apt-get install cuiksuite

That should be it!

In this process some conflicts have been reported with openbabel or imagemagick. If you have them installed, please remove them before installing the CuikSuite.

The CuikSuite uses versions of some libraries that are more recent than those packaged for Ubuntu 12.04 LTS. Moreover, the version of geomview in the repositories has a bug and can only handle small models. Therefore, we distribute an early version of geomview (both for Ubuntu 12.04 and 14.04). Thus, some of the packages we distribute might conflict with packages in the standard repositories. In case of troubles, you can combine the installation of the pre-compile packages with the installation from source code described next (use apt-get to install some of the dependencies and install the conflicting ones and the CuikSuite package from source).

For the rest of the world

The CuikSuite requires of the following libraries and packages

  • cmake a cross-platform build system to generate the makefiles.
  • tcsh since the included scripts are based on this shell.
  • A Simplex library: Three possible options are (in order of preference)
    • CLP: This is the recommended option. It is almost as fast as glpk, but much more stable and more gentle with the user. Only version 1.10 has ben tested. More recent Clp vesions (1.14 and newer) are no compatible with the CuikSuite due to the lack of the C interface.
    • GLPK This Simplex implementation is quite efficient but it tends to have numerical problems and, what is worst, in many cases of numerical inestability is simply aborts the execution instead of returning an error code to the caller. If this happens the execution of the corresponding CuikSuite application will be aborted too and this is quite anoying.
    • LP_SOLVE The inteface to lp_solve is defined but we hardly tested it. Use at your own risk.
  • The CBLAS and CLAPACK (or LAPACKE) numerical libraries. Alternatively, the GSL numerical library.
  • A MPI library. The recomended option is to use OpenMPI. This is only necessary if you want to execute cuik in a multi-core environment. If the library is not available the sources will be automatically compiled in single CPU mode.
  • flex and bison
  • doxygen and graphviz. Only required to generate the documentation.
  • Geomview to visualize some outputs. Be aware that version 1.9.4 (the one usually included in Linux distributions) is broken. You had better install version 1.8.2-rc9. If you are new to geomview this tutorial might be helpful to get familiar with this tool.
  • xfig to visualize some particular outputs. Tnis can be safely skipped in most of the cases.
  • The assimp library to read mesh files (tested with version 3.0.1270). If not available, only OFF and binary STL files will be accepted.
  • A least one of the following collision detection libraries
  • A kd-tree nearest neighbour library. This is optional, but recommended. Two possible options are
    • The Cuik-KDtree library.
    • Our modified version of the MPNN nearest-neighbour search.
  • OpenBabel for the bio-chemistry applications. If not installed, the interface for molecular problems will not be compiled.
  • The RigidCLL collision library for molecular structures.

The sequence of commands to install all these packages (and their dependencies) under Linux or Mac are given in the files

  • scripts/installDependenciesLinux
  • scripts/installDependenciesMac

respectively. Please, note that geomview requires OpenGL and Glut (either hardware-accelerated or via mesa). The details on how to install OpenGL and Glut are not included in the files since they depend on the specific hardware and the available drivers.

After installing the dependencies, we can finally install the CuikSuite. We download the package:

Instead of wget in Mac you can use curl -O.

Next, we generate the makefiles

  • cd CuikSuite2/build
  • cmake ..

In recent versions of Mac OS X (i.e. Mavericks) you had better avoid the default compiler (clang) adding parameters to cmake

  • cmake .. -DCMAKE_CXX_COMPILER=/opt/local/bin/g++-mp-4.8 -DCMAKE_C_COMPILER=/opt/local/bin/gcc-mp-4.8

where gcc 4.8 (or any other version) can be installed via mac ports.

cmake will complain if some of the pre-requisites are still missing. Then, we can compile the package executing

  • make

At this point the CuikSuite executables are available localy in the bin folder. If necessary, you can install them into the system executing

  • make install

In this documentation we assume this last step is not executed.


Finally, to generate this documentation type

  • make doc

The html documentation can be browsed from CuikSuite/doc/html/index.html

Support

The CuikSuite is in continuous development and thus, we can offer a limited support to external users.

Please, send us an e-mail at porta at iri.upc.edu if you have any troubles installing or using the suite.

For general questions about this software, please check the CuikSuite FAQ

Applications

The CuikSuite includes different applications. Follow the links below to get information about the functionality of each one of them and the way to use them. The main applications are:

But the suite also includes many auxiliary applications:

Beside the main applications, the CuikSuite also includes several scripts to automate different tasks.

Here you can find a chart briefly describing the syntax and grammar for cuik and the world files. This description is quite obsolete and its better if you check the examples.

To get an overview of the different files used in the CuikSuite have a look at this.

Disclaimer

The CuikSuite is distributed in the hope that it will be useful, but without any warranty. it is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. should the program prove defective, the KRD group does not assume the cost of any necessary servicing, repair or correction.

In no event unless required by applicable law the author will be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if the author has been advised of the possibility of such damages.