Installing on Mac OS X using Homebrew

This tutorial explains how to install the Point Cloud Library on Mac OS X using Homebrew. Two approaches are described: using the existing PCL formula to automatically install, and using Homebrew only for the dependencies with PCL compiled and installed from source.

Mac OS X logo

Prerequisites

No matter which method you choose, you will need to have Homebrew installed. If you do not already have a Homebrew installation, see the Homebrew homepage for installation instructions.

Using the formula

Homebrew includes a formula for installing PCL. This will automatically install all necessary dependencies and provides options for controlling which parts of PCL are installed.

Note

The PCL formula is currently in development. It will be submitted to Homebrew shortly. Until then, you can download it from PCL.RB. To prepare it, follow these steps:

  1. Install Homebrew. See the Homebrew website for instructions.
  2. Execute brew update.
  3. Download the formula and place it in /usr/local/Library/Formula (or an appropriate location if you installed Homebrew somewhere else).

To install using the formula, execute the following command:

$ brew install pcl

You can specify options to control which parts of PCL are installed. For example, to disable the Python bindings and visualisation, and enable the documentation, execute the following command:

$ brew install pcl --nopython --novis --doc

For a full list of the available options, see the formula’s help:

$ brew options pcl

You can test the installation by executing the tests included with PCL:

$ brew test pcl

Once PCL is installed, you may wish to periodically upgrade it. Update Homebrew and, if a PCL update is available, upgrade:

$ brew update
$ brew upgrade pcl

Installing from source

In order to compile every component of PCL, several dependencies must be installed. Homebrew includes formulae for all PCL dependencies except OpenNI, so this step is relatively easy.

Dependency information

Required

The following libraries are Required to build PCL.

  • CMake version >= 2.8.3 (http://www.cmake.org)

    Cross-platform, open-source build system.

    Note

    Though not a dependency per se, the PCL community relies heavily on CMake for the libraries build process.

  • Boost version >= 1.46.1 (http://www.boost.org/)

    Provides free peer-reviewed portable C++ source libraries. Used for shared pointers, and threading.

  • Eigen version >= 3.0.0 (http://eigen.tuxfamily.org/)

    Unified matrix library. Used as the matrix backend for SSE optimized math.

  • FLANN version >= 1.6.8 (http://www.cs.ubc.ca/~mariusm/index.php/FLANN/FLANN) Library for performing fast approximate nearest neighbor searches in high dimensional spaces. Used in kdtree for fast approximate nearest neighbors search.

  • Visualization ToolKit (VTK) version >= 5.6.1 (http://www.vtk.org/) Software system for 3D computer graphics, image processing and visualization. Used in visualization for 3D point cloud rendering and visualization.

    Note

    The current release of PCL (1.2) does not support visualisation on Mac OS X. PCL 1.3 is expected to correct this.

Optional

The following libraries are optional and provide extended functionality within PCL, such as Kinect support.

  • Qhull version >= 2011.1 (http://www.qhull.org/)

    computes the convex hull, Delaunay triangulation, Voronoi diagram, halfspace intersection about a point, furthest-site Delaunay triangulation, and furthest-site Voronoi diagram. Used for convex/concave hull decompositions in surface.

  • libusb (http://www.libusb.org/)

    A library that gives user level applications uniform access to USB devices across many different operating systems.

  • PCL Patched OpenNI/Sensor (http://www.openni.org/)

    The OpenNI Framework provides the interface for physical devices and for middleware components. Used to grab point clouds from OpenNI compliant devices.

  • Doxygen (http://www.doxygen.org)

    A documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.

  • Sphinx (http://sphinx.pocoo.org/)

    A tool that makes it easy to create intelligent and beautiful documentation. PCL uses this and Doxygen to compile the documentation.

Advanced (Developers)

The following libraries are advanced and provide additional functionality for PCL developers:

Installing dependencies

Most of the dependencies will be installed via Homebrew. The remainder, we will compile from source.

Install CMake

$ brew install cmake

Install Boost

$ brew install boost

Install Eigen

$ brew install eigen

Install FLANN

$ brew install flann

Install VTK

To install VTK, you need a modified Homebrew formula for VTK. Please download it from VTK.RB.

$ brew install vtk --qt OR --qt-extern [if you have your own Qt installation already]

Note

If you are installing PCL 1.2, you may skip this dependency.

Install Qhull (optional)

$ brew install qhull

Install libusb (optional)

$ brew install libusb

Install Doxygen (optional)

$ brew install doxygen

Install Sphinx (optional)

$ brew install sphinx

Install patched OpenNI and Sensor

Download the patched versions of OpenNI and Sensor: openni_osx.zip and ps_engine_osx.zip.

Extract, build, fix permissions and install OpenNI:

$ unzip openni_osx.zip -d openni_osx
$ cd openni_osx/Redist
$ chmod -R a+r Bin Include Lib
$ chmod -R a+x Bin Lib
$ chmod a+x Include/MacOSX Include/Linux-*
$ sudo ./install.sh

In addition the PrimeSense XML configuration file found within the patched OpenNI download needs its permissions fixed and to be copied to the correct location to for the Kinect to work on Mac OS X:

$ chmod a+r openni_osx/Redist/Samples/Config/SamplesConfig.xml
$ sudo cp openni_osx/Redist/Samples/Config/SamplesConfig.xml /etc/primesense/

Extract, build, fix permissions and install Sensor:

$ unzip ps_engine_osx.zip -d ps_engine_osx
$ cd ps_engine_osx/Redist
$ chmod -R a+r Bin Lib Config Install
$ chmod -R a+x Bin Lib
$ sudo ./install.sh

Compiling PCL

At this point you should have everything needed installed to build PCL with almost no additional configuration.

Check out the PCL source from the trunk:

$ svn co http://svn.pointclouds.org/pcl/trunk pcl
$ cd pcl

Create the build directories, configure CMake, build and install:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Note

If you are installing PCL 1.2, disable the visualisation module, or compilation will fail:

$ cmake .. -DBUILD_visualization:BOOL=OFF

The customization of the build process is out of the scope of this tutorial and is covered in greater detail in the Customizing the PCL build process tutorial.

Compiling the documentation (optional)

If you installed the Doxygen and Sphinx dependencies, you can compile the documentation after compiling PCL. To do so, use this command:

$ make doc

The tutorials can be built using this command:

$ make Tutorials

Note

The Homebrew formula for Sphinx may not install the extension necessary to link to the Doxygen-generated documentation. In this case, you will need to install Sphinx and the extension manually. Start by installing Sphinx using easy_install:

$ easy_install -U Sphinx

Next, install Mercurial (see the Mercurial documentation) and the extension:

$ hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
$ cd sphinx-contrib/doxylink
$ python setup.py install

Using PCL

Now that PCL in installed, you can start using the library in your own projects by following the Using PCL in your own project tutorial.