C++ library for point set registration using the Coherent Point Drift algorithm. This library is derived from Matlab code written by Andriy Myronenko and is available under the same license (GPL2).

This project provides a library, libcpd (libcpd64 for the 64-bit version), for use in your own applications. It also provides an optional command-line executable, called simply cpd, which provides a subset of the library's functionality for quick command-line usage.

The C++ API is as-of-yet undocumented, but to see it in action check out PDAL's cpd plugin.

Refer to the cpd source and the armadillo documentation for more information on the API and usage.

Register two point sets using the nonrigid_lowrank algorithm:

cpd file1.txt file2.txt > output.txt

The input files must be whitespace-delimited files with XYZ values only. The output file will be whitespace-delimited with the following columns: X, Y, Z, dX, dY, dZ, where dX, dY, and dZ are the change in position in the X, Y, and Z directions respectively for that point.

Run cpd --help for a description of the command-line options available for customizing the CPD algorithm.

cpd has been tested on the following systems:

• Mac OSX 10.10.1, x86_64-apple-darwin14.0.0 with
• Ubuntu 12.04 LTS Server Edition 64 bit

And the following compilers:

• Apple LLVM verison 6.0 (clang-600.0.54) (based on LLVM 3.5svn)
• Clang 3.2.x
• GCC 4.8.x

cpd depends on the following:

• armadillo: C++ linear algebra library
• lapack: linear algebra package
• arpack: large scale eigenvalue solutions
• figtree: fast improved gauss transform with tree data structure (cpd depends on this fork)
• gflags (optional): commandline flags processing, required only if you're building the commandline application

To build cpd yourself, you will need all of the above, plus:

• git: distributed version control system
• cmake: cross-platform, open-source build system (version 2.8.7 or higher required)
• a modern compiler that supports -std=c++0x, e.g. gcc-4.8 or a newer clang

Instructions are provided below for installing on Mac OSX and linux. Windoze, you're on your own.

OSX comes with lapack and arpack, so you're all set there. Most of the rest of the dependencies are available through homebrew, a great package manager for OSX. If you're don't have homebrew, get it. Then, install stuff:

brew update
brew install cmake armadillo

If you're planning on using the command line application, additionally do:

brew install gflags

You'll need to install figtree yourself. Head over to the github source and follow the install instructions there.

Now you're ready to install cpd.

Use apt-get to grab some stuff:

sudo apt-get update
sudo apt-get install git cmake liblapack-dev libarpack2-dev libsuperlu3-dev gfortran

If you have an old gcc, you may need to update it. See one of cpd's continuous integration scripts for one way to update your gcc.

You'll need to install armadillo and figtree from source. Again, you can just follow the scripts: armadillo, figtree.

Now you're ready to install cpd.

Now download and install cpd:

git clone https://github.com/gadomski/cpd.git
mkdir cpd/build && cd cpd/build

# you can omit the -DBUILD_CLI=ON part if you don't need the commandline app
cmake .. -DBUILD_CLI=ON

make

To test that things built correctly:

bin/cpd-test

If you want to install cpd to system-wide directories:

make install

If you're on a linux or didn't use homebrew on OSX, you may need a sudo make install.

If you have problems at any point during the build, please open a new issue.

cpd follows semantic versioning. In particular, any release with a 0.x.x prefix should be considered initial development, and used with the understanding that anything could change at any time. However, when in initial development we will do our best to increment the MINOR version when we make big, breaking changes, and notify users accordingly in the release notes.

Releases will be tagged and available via Github. Each MINOR release will also have its own branch (e.g. v0.1) which will be used to release PATCH fixes. Main development will occur in the master branch.

This software is distributed under the terms of the original Matlab implementation. A complete copy of the GPL2 license can be found in LICENSE.txt of this source tree. Each source file also contains a brief preamble specifying the license.

This version is copyright (c) 2014 Pete Gadomski [email protected].

The original Matlab implementation was copyright (c) 2008-2009 Andriy Myronenko. His website is here: https://sites.google.com/site/myronenko/home.

We use github's issues and pull requests. Please feel free to contribute either.

This library was developed by @gadomski with support from the Army Corps of Engineers Cold Regions Research and Development Lab.