
  Section of Biomedical Image Analysis
  Department of Radiology
  University of Pennsylvania
  3600 Market Street, Suite 380
  Philadelphia, PA 19104

  Web:   https://www.rad.upenn.edu/sbia/
  Email: sbia-software at uphs.upenn.edu

  Copyright (c) 2012 University of Pennsylvania. All rights reserved.
  See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.



INTRODUCTION
============

  This document contains the build and installation instructions.

  For general build and installation instructions which apply to any software
  developed on top of the SBIA Build system And Software Implementation
  Standard (BASIS) [1], please refer to the respective how-to guide of the
  BASIS documentation [2].



OBTAINING A COPY OF THE SOFTWARE
================================

  Please see the corresponding section of the BASIS how-to guide [2].



INSTALLING A BINARY DISTRIBUTION PACKAGE
========================================

  Please see the corresponding section of the BASIS how-to guide [2].



RUNTIME REQUIREMENTS
====================

  This software has no runtime dependencies.



BUILDING THE SOFTWARE FROM SOURCES
==================================

  Build Dependencies
  ------------------

  The following software has to be installed (if not optional).

  - BASIS >= 2.0

    Web Site: http://www.rad.upenn.edu/sbia/software/basis/

    This project is based on BASIS, a meta-project developed at SBIA to
    standardize and simplify the software development.

  - ATLAS 3.8.3 or greater
 
    Web Site: http://math-atlas.sourceforge.net/
    Download: https://sourceforge.net/projects/math-atlas/files/Stable/
    Ubuntu:   libatlas-dev

  - Boost 1.33 or greater

    Web Site: http://www.boost.org/
    Download: http://www.boost.org/users/download/
    Ubuntu:   libboost-dev

  - boost-numeric-bindings 20081116 or later

    Web Site: http://mathema.tician.de/software/boost-numeric-bindings
    Download: http://mathema.tician.de/dl/software/boost-numeric-bindings

    In particular, the ATLAS bindings are used by this software.

  - nifticlib 1.1 or greater

    Web Site: http://niftilib.sourceforge.net/
    Download: http://sourceforge.net/projects/niftilib/files/nifticlib/
    Ubuntu:   libnifti1-dev or nifticlib

  - OpenCV 1.0 or 1.1pre1

    Web Site: http://opencv.willowgarage.com/wiki/
    Download: https://sourceforge.net/projects/opencvlibrary/files/
    Ubuntu:   libcv-dev, libcvaux-dev (hardy)

    Note that with OpenCV 2 (we tried versions 2.0.0, 2.2.0 and 2.3.1),
    the runtime of ODVBA suffers quite some. It is strongly recommended to
    build this software with OpenCV 1.0.0 or OpenCV 1.1pre1.

    In future versions of ODVBA it may need to be investigated how this
    performance issue can be resolved. The cvEigenVV() C function of OpenCV 2
    used by the Non-negative Discriminative Projection (NDP) seems to be the
    bottleneck. It would be worthwhile to give the C++ equivalent a shot.
    Another solution might be the use of cvSVD() or its C++ counterpart.

  - Open MPI 1.3.3 or greater (optional)

    Web Site: http://www.open-mpi.org/
    Download: http://www.open-mpi.org/software/ompi/v1.4/
    Ubuntu:   mpi-default-dev

    If an Open MPI library is found on your system, the odvba-mpi executable
    is build next to the serial odvba executable. The odvba-mpi executable
    is suitable for execution on either one machine with multiple cores or,
    in particular, on a cluster with multiple compute nodes. A subset of the
    total number of permutation tests is then performed by separate MPI
    processes. The results are assembled in the end by the main process to
    write the final results.


  Build Steps
  -----------

  The common steps to build, test, and install software based on CMake,
  including this software, are as follows:

  1. Extract source files.
  2. Create build directory and change to it.
  3. Run CMake to configure the build tree.
  4. Build the software using selected build tool.
  5. Install the built files.

  On Unix-like systems with GNU Make as build tool, these build steps can be
  summarized by the following sequence of commands executed in a shell,
  where $package and $version are shell variables which represent the name
  of this package and the obtained version of the software.

  $ tar xzf $package-$version-source.tar.gz
  $ mkdir $package-$version-build
  $ cd $package-$version-build
  $ ccmake -DBASIS_DIR:PATH=/path/to/basis ../$package-$version-source

    - Press 'c' to configure the build system and 'e' to ignore warnings.
    - Set CMAKE_INSTALL_PREFIX and other CMake variables and options.
    - Continue pressing 'c' until the option 'g' is available.
    - Then press 'g' to generate the configuration files for GNU Make.

  $ make
  $ make test    (optional)
  $ make install (optional)

  An exhaustive list of minimum build dependencies, including the build tools
  along detailed step-by-step build, test, and installation instructions can
  be found in the corresponding "Building the Software from Sources" section
  of the BASIS how-to guide on software installation [2].

  Please refer to this guide first if you are uncertain about above steps or
  have problems to build, test, or install the software on your system.
  If this guide does not help you resolve the issue, please contact us at
  <sbia-software at uphs.upenn.edu>. In case of failing tests, please attach
  the output of the following command to your email:
 
  $ ctest -V >& test.log

  In the following, only package-specific CMake settings available to
  configure the build and installation of this software are documented.


  CMake Options
  -------------

  BoostNumericBindings_DIR  Directory where the files of the
                            boost-numeric-bindings were extracted to.
  NiftiCLib_DIR             Installation directory of the nifticlib
                            library, e.g., /usr/local.
  OpenCV_DIR                Installation directory of the OpenCV library.


  Advanced CMake Options
  ----------------------

  BLAS_atlas_LIBRARY        Path of the ATLAS library.
  BLAS_cblas_LIBRARY        Path of the C BLAS library.
  BLAS_f77blas_LIBRARY      Path of the Fortran BLAS library.
  Boost_INCLUDE_DIR         Include directory of the Boost library,
                            e.g., /usr/include.
  Boost_LIBRARY_DIRS        Directory where the Boost libraries are installed,
                            e.g., /usr/lib.



REFERENCES
==========

  [1] http://www.rad.upenn.edu/sbia/software/basis/

  [2] http://www.rad.upenn.edu/sbia/software/installation.html
