Installing OpenVDB
==================

Requirements
------------
- A C++11-compatible compiler, such as
  GNU GCC (gcc.gnu.org), version 4.8 or later,
  Clang (clang.llvm.org), version 3.8 or later,
  or Intel ICC (software.intel.com), version 15 or later

- GNU gmake (www.gnu.org/software/make/), version 3.81 or later

- Boost (www.boost.org), version 1.53.0 or later; 1.57.0 or later
  for the Python module
  (Linux: yum install boost-devel; OS X: port install boost +python27)

- libz (zlib.net)
  (Linux: yum install zlib-devel)

- OpenEXR (www.openexr.com), for the 16-bit float Half class in half.h
  and for .exr file output in vdb_render

- Intel Threading Building Blocks (threadingbuildingblocks.org),
  version 3.0 or later

Other compilers or versions might work but have not been tested.


Optional:

- Doxygen 1.8.11 or later (www.stack.nl/~dimitri/doxygen/), for documentation

- CppUnit (www.freedesktop.org/wiki/Software/cppunit), version 1.10 or later
  (Linux: yum install cppunit-devel)

- Houdini HDK (http://www.sidefx.com/get/download-houdini/), version 15.0
  or later

- Blosc compression library (www.blosc.org), version 1.5.0 or later
  (included in the Houdini HDK as of version 14.0)

- Ghostscript (www.ghostscript.com), version 8.70 or later, for documentation
  in PDF format

- pdfLaTeX (www.pdftex.org), version 1.21 or later, for documentation
  in PDF format

- log4cplus (log4cplus.sourceforge.net), version 1.1.2 or later,
  for error logging

- GLFW 2.7 (www.glfw.org), for the OpenVDB viewer

- OpenGL 3.2 or later, for the OpenVDB viewer

- Python 2.5, 2.6 or 2.7, for the Python module

- NumPy (www.numpy.org), for the Python module

- Epydoc (http://epydoc.sourceforge.net/), version 3.0 or later,
  for Python module documentation

Other versions might work but have not been tested.


Installation
------------
1.  Set values appropriate to your environment for the following variables
    at the top of the Makefile:

    INSTALL_DIR         the directory into which to install libraries,
                        executables and header files (e.g., /usr/local)

    BOOST_INCL_DIR      the parent directory of the boost/ header directory
                        (e.g., /usr/include)
    BOOST_LIB_DIR       the directory containing libboost_iostreams, etc.
    BOOST_LIB           linker flags for libboost_iostreams and libboost_system
    BOOST_THREAD_LIB    linker flags for libboost_thread

    ILMBASE_INCL_DIR    the parent directory of the OpenEXR/ header directory
                        (which contains half.h)
    ILMBASE_LIB_DIR     the directory containing libHalf.so and/or libHalf.a
    ILMBASE_LIB         linker flags for libIlmThread, libIex and libImath
    HALF_LIB            linker flag(s) for the Half library (e.g., -lHalf)

    EXR_INCL_DIR        the parent directory of the OpenEXR/ header directory
                        (Note: some OpenEXR headers incorrectly include other
                        OpenEXR headers with, e.g., '#include <ImfName.h>'
                        instead of '#include "ImfName.h"'.  When compiling
                        with Clang, set EXR_INCL_DIR to the parent directory
                        of the OpenEXR/ directory and ILMBASE_INCL_DIR to the
                        OpenEXR/ directory itself to avoid errors.)
    EXR_LIB_DIR         the directory containing libIlmImf
    EXR_LIB             linker flags for libIlmImf

    TBB_INCL_DIR        the parent directory of the tbb/ header directory
    TBB_LIB_DIR         the directory containing libtbb
    TBB_LIB             linker flag(s) for the TBB library (e.g., -ltbb)

    BLOSC_INCL_DIR      the parent directory of the blosc.h header
    BLOSC_LIB_DIR       the directory containing libblosc
    BLOSC_LIB           linker flags for libblosc

    CONCURRENT_MALLOC_LIB_DIR
                        a directory containing a scalable, concurrent malloc
                        replacement library such as jemalloc or TBB malloc
                        (leave blank if no such library is available, but
                        be aware that using standard malloc in concurrent
                        code incurs a significant performance penalty)
    CONCURRENT_MALLOC_LIB
                        linker flag(s) for the malloc replacement library
                        (e.g., -ltbbmalloc_proxy -ltbbmalloc)

    CPPUNIT_INCL_DIR    the parent directory of the cppunit/ header directory
                        (leave blank if CppUnit is not available)
    CPPUNIT_LIB_DIR     the directory containing libcppunit.so or libcppunit.a
    CPPUNIT_LIB         linker flag(s) for the cppunit library
                        (e.g., -lcppunit)

    GLFW_INCL_DIR       the directory containing glfw.h
                        (leave blank if GLFW is not available;
                        GLFW is needed only for the command-line viewer tool)
    GLFW_LIB_DIR        the directory containing libglfw
    GLFW_LIB            linker flags for the GLFW library (e.g., -lglfw)
    GLFW_MAJOR_VERSION  the major version number of the GLFW library
                        (header filenames changed between GLFW 2 and 3,
                        so this must be specified explicitly)

    LOG4CPLUS_INCL_DIR  the parent directory of the log4cplus/ header directory
                        (leave blank if log4cplus is not available)
    LOG4CPLUS_LIB_DIR   directory containing liblog4cplus.so or liblog4cplus.a
    LOG4CPLUS_LIB       linker flags for the log4cplus library
                        (e.g., -llog4cplus)

    PYTHON_VERSION      the version of Python for which to build the OpenVDB
                        module (e.g., 2.7)
                        (leave blank if Python is unavailable)
    PYTHON_INCL_DIR     the directory containing the Python.h header file
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/Headers)
    PYCONFIG_INCL_DIR   the directory containing the pyconfig.h header file
                        (usually but not always the same as PYTHON_INCL_DIR)
    PYTHON_LIB_DIR      the directory containing the Python library
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/lib)
    PYTHON_LIB          linker flags for the Python library
                        (e.g., -lpython2.7)
    BOOST_PYTHON_LIB_DIR
                        the directory containing the Boost.Python library
    BOOST_PYTHON_LIB    linker flags for the Boost.Python library
                        (e.g., -lboost_python-mt)
    NUMPY_INCL_DIR      the directory containing the NumPy arrayobject.h
                        header file (leave blank if NumPy is unavailable)
                        (on OS X, this is usually /System/Library/Frameworks/
                        Python.framework/Versions/$(PYTHON_VERSION)/Extras/
                        lib/python/numpy/core/include/numpy)
    EPYDOC              the path to the Epydoc executable
                        (leave blank if Epydoc is unavailable)
    PYTHON_WRAP_ALL_GRID_TYPES
                        if set to "no", expose only FloatGrid, BoolGrid
                        and Vec3SGrid in Python, otherwise expose (most of)
                        the standard grid types defined in openvdb.h

    DOXYGEN             the path to the Doxygen executable
                        (leave blank if Doxygen is unavailable)

    Note that if you plan to build the Houdini OpenVDB tools (distributed
    separately), you must build the OpenVDB library and the Houdini tools
    against compatible versions of the Boost, OpenEXR and TBB libraries.
    Fortunately, all three are included in the Houdini HDK, so by default
    several of the variables above reference the Houdini environment variables
    $HDSO, $HFS and $HT.  Source the houdini_setup script provided with
    your Houdini installation to set those environment variables.

    Also note that certain new features in OpenVDB 4 (see the CHANGES file
    for details) necessitated changes to the ABI of the Grid class,
    rendering it incompatible with earlier versions of the library, such as
    the ones built into Houdini 15, 15.5 and 16.  Passing grids between
    native VDB nodes in a scene graph and nodes built against the new ABI
    will lead to crashes, so to use OpenVDB 4 with those versions of Houdini,
    set abi=3 to compile with the incompatible features disabled.

    To build the OpenVDB Python module, you will need local installations
    of Python, Boost.Python, and optionally NumPy.  Houdini ships with
    Python 2 as well as Boost.Python headers, but unfortunately it includes
    neither the libboost_python library nor NumPy, so both Boost.Python
    and NumPy have to be built separately.  Point the variables
    $(BOOST_PYTHON_LIB_DIR), $(BOOST_PYTHON_LIB) and $(NUMPY_INCL_DIR)
    to your local installations of those libraries.

2.  From the top-level openvdb/ directory, type "make" (or "make -s" for
    less verbose output) to locally build the library and commands.
    The Makefile supports parallel builds (e.g. "make -j 8").

    A default local build generates the following libraries and executables
    (but see the Makefile for additional targets and build options):

    openvdb/libopenvdb.so.5.0.0         the OpenVDB library
    openvdb/libopenvdb.so               symlink to libopenvdb.so.5.0.0
    openvdb/pyopenvdb.so                the OpenVDB Python module (if Python
                                        and Boost.Python are available)
    openvdb/vdb_print                   command-line tool that prints info
                                        about OpenVDB .vdb files
    openvdb/vdb_render                  command-line tool that ray-traces
                                        OpenVDB volumes
    openvdb/vdb_test                    unit test runner for libopenvdb
                                        (if CppUnit is available)

    From the openvdb/ directory, type "make test" to run the unit tests
    and verify that the library is working correctly.  (Alternatively, once
    the library has been installed (Step 5), run the unit test executable
    directly with "./vdb_test", or "./vdb_test -v" for more verbose output.)
    Type "make pytest" to run the Python module unit tests.

3.  From the openvdb/ directory, type "make doc" (or "make -s doc")
    to generate HTML library documentation, then open the file
    openvdb/doc/html/index.html in a browser.  Type "make pydoc"
    (or "make -s pydoc") to generate HTML Python module documentation,
    then open openvdb/doc/html/python/index.html in a browser.

4.  Optionally (if OpenGL and GLFW are available), from the top-level openvdb/
    directory, type "make vdb_view" (or "make -s vdb_view") to locally build
    the OpenVDB viewer tool.  Then type "./vdb_view" for usage information.

5.  From the openvdb/ directory, type "make install" (or "make -s install")
    to copy generated files into the directory tree rooted at $(INSTALL_DIR).
    This creates the following distribution:

    $(INSTALL_DIR)/
        bin/
            vdb_print
            vdb_render
            vdb_view
        include/
            openvdb/
                Exceptions.h
                ...
                openvdb.h
                tools/
                tree/
                ...
                version.h
        lib/
            libopenvdb.so
            libopenvdb.so.5.0
            libopenvdb.so.5.0.0

        python/
            include/
                python$(PYTHON_VERSION)/
                    pyopenvdb.h
            lib/
                python$(PYTHON_VERSION)/
                    pyopenvdb.so
                    pyopenvdb.so.5.0

        share/
            doc/
                openvdb/
                    html/
                        index.html
                        ...
                        python/
                            index.html
                            ...

EOF
