README

Statismo is a C++ library for generating and manipulating Statistical
Shape and Image Models. It supports all commonly known types of
statistical models, including Shape models, Deformation Models and
Intensity Models. The implementation and interpretation is based on
Probabilistic PCA, which generalizes the standard PCA models and gives
a fully probabilistic interpretation.

How to build Statismo: 
----------------------
Statismo is a header only library. There is no need to compile statismo. You simply include the necessary 
header files into your application and statismo is compiled together with  your application. 
However, statismo depends on some third-party libraries (such as HDF5) and to use it from your applications, 
you need to correctly specify all the path to the different include directories and libraries. 

To simplify this process, we have provided a CMake file that takes care of this process. 

To install statismo use the usual CMake workflow (here demonstrated for linux):
1) Create a directory that  holds your binary data and change into that directory
> mkdir build_dir
> cd build_dir
2) Configure the project. 
> ccmake path_to_statismo
Make sure that you set the CMAKE_INSTALL_PREFIX to the path where you want to install statismo 
3) Compile and install statismo
> make 
> make install

This builds the dependencies and copies the necessary files to the installation directory. 
In particular, it generates the file statismo-config.cmake, that holds the correct configuration. 
To use statismo from your application, you can now simply include the command
FindPackage(statismo) into your CMakeLists.txt file. This will set up the CMake variables 
- STATISMO_DIR 
- STATISMO_LIBRARIES 
- STATISMO_INCLUDE_DIRS 
- STATISMO_LIBRARY_DIR

See the examples (in the Example folder) to see how statismo is used.
To build the examples, set the options BUILD_VTK_EXAMPLES and BUILD_ITK_EXAMPLES with CMake and build statismo.

Python Wrapping
---------------
The C++ version of statismo can be used to create models from data that are represented in various different toolkits.  
This flexibility is achieved by letting the user provide special template classes (called Representers), that abstract all the 
aspects that are specific to a given toolkit. 
For the VTK and ITK toolkits, Statismo already comes with a set of Representers. For these representers, Python Wrappings can be generated, 
that enable to use of Statismo from Python.  

To generate these Wrappers, you need to enable the options BUILD_PYTHON_WRAPPING_VTK and BUILD_PYTHON_WRAPPING_ITK in CMake. 
Note that for generating the Wrappers for VTK, SWIG needs to be available, and VTK needs to be built with Python support. 
For generating the ITK wrappings, ITK needs to be compiled with wrapITK enabled.

Unit Tests
----------
To test your basic installation, simply run 
> make test 
in your build directory. 
Beside these basic tests, there is a larger set of unit tests available. These unit tests are written in Python, and consequently 
require that Statismo has been compiled with the option BUILD_PYTHON_WRAPPING_VTK.

To run the tests, write 
> make unit_test

Known issues
------------
Statismo has been implemented and thoroughly tested on Linux.
It also has been tested and used on Windows. Depending on your system, you may experience linking problems when building a debug configuration.   
For more information regarding this issue and possible workarounds, see the project wiki. 


Main Authors:
-------------
- Marcel Luethi
- Remi Blanc

Contributors:
------------
- Tobias Gass 
- Thomas Albrecht 
- Habib Bousleiman
- Orcun Goksel

License:
--------
Statismo itself is licensed under the BSD license. It depends, however, on other open source projects, which are distributed under different licenses. 
Most notably, these are Eigen, Boost and HDF5. You will find a copy of the respective license agreements in the folder ./3rdParty.