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

  Web:   http://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
====================

  The main gondola function/program which implements the
  Generative-Discriminative Basis Learning is written in MATLAB.

  - MATLAB >= R2009b

    Web Site: http://www.mathworks.com/
    Download: n/a

    MATLAB is required to execute the main gondola function if during the build
    the option BASIS_COMPILE_MATLAB was set to OFF or if no MATLAB Compiler is
    available. In this case, a Bash (Unix) or Windows NT Command (Windows)
    script is generated by BASIS which calls MATLAB as follows:

    /path/to/bin/matlab -nodesktop -nosplash -nojvm -c "gondola([options])"

    with the proper formatting of the program options as arguments to the
    gondola() MATLAB function.

  - MATLAB Image Processing Toolbox
  
    Web Site: http://www.mathworks.com/products/image/
    Download: n/a

    Required at runtime only if the MATLAB sources were not compiled using the
    MATLAB Compiler.

  - MATLAB Compiler Runtime

    Web Site: http://www.mathworks.com/products/compiler/mcr/index.html
    Downlaod: http://www.mathworks.com/products/compiler/mcr/index.html

    If the software has been compiled using the MATLAB Compiler, the MATLAB
    Compiler Runtime (MCR) has to be installed. 

  The scripts used to perform the cross-validation experiments are implemented in
  Python, where Jython is further used to enable the use of the Weka Java API.
  Additionally, the non-core Python modules of the SBIA Utilities, NumPy, and SciPy
  packages (see Build Dependencies) are required to execute the gondola-crossval
  script. The path to these modules is configured during the build of GONDOLA.

  - Python >= 2.5.2

    Web Site: http://www.python.org/
    Download: http://www.python.org/getit/

    The main scripts gondola-config and gondola-crossval are implemented in Python.
    These are not required for the core algorithm which is implemented by the
    gondola MATLAB function. However, Python is available for all supported platforms
    and already intalled on most Unix systems.

  - Jython >= 2.5.1
  
    Web Site: http://www.jython.org/
    Download: http://www.jython.org/downloads.html

    Jython is a Java implementation of the Python language interpreter. It enables
    the use of Java classes in scripts using the Python language and is in particular
    required by the command-line tools which determine the best parameters for each
    classifier and train them as these make use of the Weka Java API.
 


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/
    Download: http://www.rad.upenn.edu/sbia/software/distributions/basis-2.0.0-source.tar.gz

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

  - ITK >= 3.18
  
    Web Site: http://www.itk.org/
    Download: http://www.itk.org/ITK/resources/software.html

    Although there have been major changes in ITK 4.0, there is likely enough
    backward compatibility for this software which only makes use of the image
    readers and writers of ITK. Nevertheless, we have NOT tested this software
    with ITK 4.0.

  - LIBLINEAR >= 1.8
 
    Web Site: http://www.csie.ntu.edu.tw/~cjlin/liblinear/
    Download: http://www.csie.ntu.edu.tw/~cjlin/cgi-bin/liblinear.cgi?+http://www.csie.ntu.edu.tw/~cjlin/liblinear+tar.gz

    LIBLINEAR is a fast linear SVM solver used in the GONDOLA optimization procedure. 
    Make sure that you compile both LIBLINEAR and its MATLAB extensions (MEX-files).

  - MOSEK >= 6.0
  
    Web Site: http://www.mosek.com/
    Download: n/a

    This software was tested with version 6.0 of MOSEK. MOSEK is used in optimizing
    one of the blocks. Since this is not free software and has a very limited application
    within GONDOLA, it has been replaced by an implementation of the
    Spectral Projected Gradient (SPG) algorithm. The running time with SPG is noticeably
    better than with MOSEK, which is a more general purpose optimization framework.
    We therefore do not recommend the use of MOSEK for external use of GONDOLA. The support
    for MOSEK has mainly be kept for the further development of GONDOLA or methods derived
    from it which may be easier using MOSEK.

  - MATLAB >= R2009b
  
    Web Site: http://www.mathworks.com/
    Download: n/a

    Note that the The Image Processing Toolbox is required by this software.

  - MATLAB Image Processing Toolbox
 
    Web Site: http://www.mathworks.com/products/image/
    Download: n/a

  - MATLAB Compiler >= R2009b

    Web Site: http://www.mathworks.com/products/compiler/index.html
    Download: n/a

    The main gondola program can be either run from within MATLAB or the
    command-line as binary exectuable when compiled using the MATLAB Compiler (mcc)
    This requires a license for the MATLAB Compiler. Alternatively, BASIS can
    generate a Bash or Windows NT Command script which runs the gondola
    MATLAB function as follows:

    /path/to/bin/matlab -nodesktop -nosplash -nojvm -c "gondola([options])"

    While the compilation via the MATLAB Compiler does not require the
    installation of all MATLAB source files, should there be no difference
    in the running time.

    If your GNU Compiler version is not compatible with your version of MATLAB,
    you need to install a version which is compatible with the MATLAB Compiler.
    You must further ensure to build all build dependencies listed here such
    as the in particular the ITK with this version of the GNU Compiler.

    Note that for example MATLAB R2010 is not compatible with the GNU Compiler
    version >= 4.4, but version <= 4.3.

    This software has been tested in particular with GNU Compiler version 4.1.2
    on CentOS 5 and version 4.3 on Ubuntu, where the GNU Compiler has been
    build from sources on Ubuntu to avoid the incompatibility issue with the
    newer compiler version that is installed by default.

  - NumPy

    Web Site: http://numpy.scipy.org/
    Download: http://www.scipy.org/Download

  - SBIAUtilities >= 1.0.0

    Web Site: n/a
    Download: http://www.rad.upenn.edu/sbia/software/distributions/sbiautilities-1.0.0-source.tar.gz

    The sbia.utilities.pyxel Python module of the SBIA Utilities package is used to read
    and write spreadsheets with the results of the cross-validation experiments in the
    CSV format.

  - SciPy
 
    Web Site: http://www.scipy.org/
    Download: http://www.scipy.org/Download

  - Weka >= 3.7.3
 
    Web Site: http://www.cs.waikato.ac.nz/ml/weka/
    Download:

    Note that the main command-line programs of this software will also work with
    Weka 3.6.0. The ranking of the basis vectors, however, requires Weka 3.7.


  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. Test the built software.
  6. 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
  -------------

  - MOSEK_DIR
  - SBIAUtilities_DIR
  - PythonModules_DIR
  - Weka_DIR
  - Weka_PACKAGES_DIR
  - ITK_DIR
  - LIBLINEAR_DIR
  - MATLAB_DIR


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

  - BASIS_COMPILE_MATLAB
  - MOSEK_mosekopt_MEX
  - PYTHON_EXECUTABLE
  - JYTHON_EXECUTABLE
  - PythonModules_numpy_DIR
  - PythonModules_scipy_DIR
  - LIBLINEAR_libsvmread_MEX
  - LIBLINEAR_libsvmwrite_MEX
  - LIBLINEAR_predict_MEX
  - LIBLINEAR_train_MEX



REFERENCES
==========

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

  [2] http://www.rad.upenn.edu/sbia/software/basis/howto/install/
