Getting started

Getting help

Don’t panic!

If you have problems downloading or installing plastimatch, please send an email to our mailing list. We’re friendly people.

http://groups.google.com/group/plastimatch

Downloading the code

The recommended method for downloading plastimatch is to use subversion to download the source code, and then compile the source. To download using subversion, use the following command:

$ svn co http://forge.abcd.harvard.edu/svn/plastimatch/plastimatch/trunk plastimatch

You will need to supply the user name and password:

User: anonymous
Password: <empty>

If you are using Windows, you will need a subversion client. We recommend cygwin (http://cygwin.com) for command-line users, and TortoiseSVN (http://tortoisesvn.tigris.org) for graphical users.

If you have already downloaded a previous version, you can update to the latest version by executing the following command from within the plastimatch source directory:

$ svn update

Build dependencies

Cmake (required)

Plastimatch uses cmake, so you must download and install cmake before you can build plastimatch. Download from here:

http://cmake.org/

Cmake 2.6 or higher is required. Cmake 2.8 is required if you want to build the Slicer plugin, or if you want to compile reg-2-3.

C/C++ Compiler (required)

You will need a C/C++ compiler. If you are running Windows, we recommend Microsoft Visual Studio (Express or Full, 2005 or 2008). If you are running unix, we recommend gcc. You can download the Microsoft Visual Studio Express compiler from here:

http://www.microsoft.com/Express/

Microsoft Visual Studio 2010 is also fine, but you will not be able to use CUDA.

You may also use the MinGW compiler.

ITK (required)

ITK is required for the main plastimatch program. But if you only want the DRR and FDK programs, you don’t need it. Get ITK from here:

http://itk.org/

We recommend version ITK 3.20.X. ITK version 4.0 is not supported.

When you build ITK, the following settings are recommended:

CMAKE_BUILD_TYPE                          Release
BUILD_EXAMPLES                            OFF
BUILD_SHARED_LIBS                         (EITHER)
BUILD_TESTING                             OFF
ITK_USE_REVIEW                            ON
ITK_USE_OPTIMIZED_REGITRATION_METHODS     ON

Note, if you are using Debian, Ubuntu, or related distributions, the ITK package provided by the repository is compiled against GDCM 2.X instead of GDCM 1.X. You can use this ITK, but you will not be able to import or export DICOM-RT.

VTK (optional)

VTK is required for compiling reg-2-3, for 2D-3D image registration. You don’t need VTK if you only need plastimatch. Get VTK from here:

http://vtk.org/

Only VTK version 5.6.1 is supported. On linux x86_64 platforms, you will need to adjust the compile flags, and add “-fPIC” to CMAKE_CXX_FLAGS and CMAKE_C_FLAGS.

In addition, VTK 5.6.1 has a small bug which prevents it from compiling on gcc version 4.6. You will need to edit the VTK source code. Specifically, you need to edit the file Utilities/vtkmetaio/metaUtils.cxx, and add the following line somewhere near the top of the file (for example after line 20):

#include <cstddef>

CUDA (optional)

CUDA is needed if you want GPU acceleration of the DRR, FDK, and B-Spline registration codes. You need to install the driver and toolkit, but the SDK is not needed.

Please note that CUDA is constantly evolving in order to provide new high performance computing features. The following table will help you with selecting the correct CUDA version to install/upgrade:

CUDA 2.X              Not supported
CUDA 3.0              Recommended
CUDA 3.1              Recommended
CUDA 3.2              Recommended
CUDA 4.0              Not supported

Download CUDA from here:

http://developer.nvidia.com/object/cuda_archive.html

3D Slicer (optional)

3D Slicer is needed if you want to build the Slicer plugin. Download Slicer from here:

http://slicer.org/

Slicer version 3.6 and 4.0 are supported. See the section below for detailed instructions on how to build the 3D Slicer plugin.

FFTW (optional)

The FFTW library is used to implement the ramp filter for FDK cone-beam reconstruction. So if you are not using the FDK code, you don’t need this. We recommend the most current version of FFTW 3.

http://www.fftw.org/

On windows, the precompiled DLLs work fine. However, you do need to create the import libraries. See this page for details:

http://www.fftw.org/install/windows.html

Fortran (optional)

Plastimatch requires fortran, which can be satisfied with either a real fortran compiler, or with the f2c library. If neither of these are installed, plastimatch supplies its own version of f2c. You can hint which of these is used using the following CMake options:

Option                 Default      Description
------                 -------      ------------
PLM_PREFER_F2C         OFF          Prefer the f2c library over fortran
PLM_PREFER_SYSTEM_F2C  ON           Prefer the system f2c library over
                                      the included f2c library

DCMTK (optional)

DCMTK is needed for mondoshot and a few other small utilities. On Unix, it is a breeze, but Windows can be tricky. My experience is that the pre-built binaries don’t seem to work, and you will get the best results if you build it yourself. Here is a rough guide how to compile and use on windows:

Building dcmtk 3.5.4 on windows

1. Download and unpack source code for 3.5.4
2. Run CMake - set WITH_LIBPNG, WITH_LIBTIFF, WITH_ZLIB to OFF
3. Build
4. Install - this will create a directory “dcmtk-3.5.4-win32-i386” with the same parent as the source directory
5. Run CMake on plastimatch - set DCMTK_DIR to the install directory

Building dcmtk 3.6 on windows

1. Download and unpack source code
2. Run CMake - set WITH_LIBPNG, WITH_LIBTIFF, WITH_ZLIB to OFF
3. Set install directory (if desired); I use $HOME/build/dcmtk-3.6.0-install
4. Build DCMTK
5. Run CMake on plastimatch - set DCMTK_DIR to the install directory

Building dcmtk 3.6 on linux x86_64 with gcc

1. Download and unpack source code
2. Run CMake - add -fPIC to CMAKE_CXX_FLAGS and CMAKE_C_FLAGS
3. Set install directory (if desired); I use $HOME/build/dcmtk-3.6.0-install
4. Build DCMTK
5. Run CMake on plastimatch - set DCMTK_DIR to the install directory

WxWidgets (optional)

WxWidgets is needed if you want to build “Mondoshot”, the dicom screen capture program. Download WxWidgets from here:

http://wxwidgets.org

Compiling plastimatch (Windows)

Run CMake as follows:

1. Select source directory and binary directory
2. Click configure
3. Select makefile format (e.g. MS VC 2005)
4. <CMake configures>
5. Set the ITK directory (sometimes it might be found automatically)
6. Set directories for optional components (such as slicer)
7. Click configure
8. <CMake configures>
9. Click OK
10. <CMake generates>

Then build in Visual Studio as follows:

1. Navigate to your binary directory
2. Open the project file plastimatch.sln into MSVC.
3. Change the build type (e.g. release, debug) to match ITK (and other dependencies. You probably want release.
4. Click “Build Solution”. Let the project build.

Special instructions for running cmake with MSYS/gcc on Windows

There is a trick to building with MSYS/gcc. The trick is that you need to run the win32 cmake from the MSYS command line instead of the GUI. For example, here is the command that I use:

$ mkdir /c/gcs6/build/plastimatch-mingw
$ cd /c/gcs6/build/plastimatch-mingw
$ /c/Program\ Files/CMake\ 2.8/bin/cmake \
    -DITK_DIR=/c/gcs6/build/itk-mingw \
    -G"MSYS Makefiles" \
    /c/gcs6/projects/plastimatch

Then, edit CMakeCache.txt to set your options. Re-run cmake to create the MSYS Makefile, and then run make to build.

Special instructions for Visual Studio 2010

The CUDA compiler nvcc is not compatible with Visual Studio 2010. That is why we use Visual Studo 2008. But, if you insist on using VS 2010, there are some workarounds (Google is your friend).

Compiling plastimatch (Unix)

Run CMake as follows:

1. mkdir /path/to/build/files; cd /path/to/build/files
2. ccmake /path/to/source/files
3. Type “c” to configure
4. <CMake configures>
5. Set the ITK directory (sometimes it might be found automatically)
6. Set directories for optional components (such as slicer)
7. You probably want to change the build type to “Release” (type it in)
8. Type “c” to configure
9. <CMake configures>
10. Type “g” to generate
11. <CMake generates>

Then build as follows:

1. Navigate to the plastimatch binary directory

2. Type “make”

   Users with multicore systems can speed up the process of compiling plastimatch considerably by invoking make with the -j option. For example, a user with a dual-core system would type:

   make -j 2

   whereas a user with a quad-core system would type:

   make -j 4

   You can probably get even better performance by increasing the the number of processes (specified by the -j option) beyond the number of cores. One rule of thumb is to use approximately 1.5 times the number of available CPUs (see [1], [2]).

Compiling the 3D Slicer extensions

METHOD ONE:

1. Build slicer from source. Use slicer 3.6, not slicer 4.

   http://www.slicer.org/slicerWiki/index.php/Slicer3:Build_Instructions

   If you are on Vista, you need to turn off UAC. If you are on Vista or 7, you need to run cygwin as administrator I suggest these options:

   ./Slicer3/Scripts/getbuildtest.tcl --release -t ""

   The slicer build takes a while. Let it run overnight.

2. Run slicer, just make sure the build went ok.

3. Make a new build directory for plastimatch.

4. Run CMake

   Configure. Set Slicer3_DIR to the Slicer3-build directory. You don’t need to set ITK – the script should use Slicer’s ITK. Configure again. Generate.

5. Build plastimatch. You should find the plugins here:

   lib/Slicer3/Plugins/Release

6. Fire up slicer. You need to tell slicer where the plugins are located

   View -> Application Settings -> Module Settings Click on the “Add a preset” icon Browse to the lib/Slicer3/Plugins/Release directory Click Close Restart slicer

7. You should see the plastimatch plugin in the module selector

METHOD TWO:

1. Build 3D Slicer as described above.

2. Use slicer’s extension builder script to make the plugin:

   ./Slicer3/Scripts/extend.tcl --release -t "" plastimatch-slicer

3. You should find the plugins here:

   Slicer3-ext/plastimatch-slicer-build/lib/Slicer3/Plugins/Release

4. Plugins get uploaded here:

   http://ext.slicer.org/ext/trunk

   Your plugin gets put in one of the subdirectories, organized by the platform and the svn version number of slicer.

5. Add module path as described above -OR- download using extension manager