================================================================================
- Medical Data Segmentation Toolkit (MDSTk)
- Copyright (c) 2003-2007 by Michal Spanel, FIT, Brno University of Technology
--------------------------------------------------------------------------------
- Authors: Michal Spanel (spanel@fit.vutbr.cz)
- Date:    2003/12/24
-
- $Id: README.txt 489 2007-09-27 09:45:14Z spanel $
-
================================================================================

[What is MDSTk?]

'M'edical 'D'ata 'S'egmentation 'T'ool'k'it is a collection of 2D/3D image
processing tools originaly aimed at medical image segmentation. Base parts
of the MDSTk (image processing and system libraries, modules, etc.) are public,
distributed on its web site. We will be pleased if somebody find out that
this toolkit could be useful.

This file contains basic overview of the MDSTk as well as information
about its installation.


[Content]

1 Basic Features
2 Installation
 2.1 Required Software
 2.2 Compilation
 2.3 3rd Party Libraries
3 Brief guide
 3.1 Running Module from Command Line
 3.2 Samples
4 Source Code Description
 4.1 Libraries
 4.2 Modules
 4.3 Documentation
5 Authors and Main Contributors
6 Bug Reporting


[1 Basic Features]

    - Multiplatform toolkit running on Linux and Windows platform.
      Supported compilers are
        GCC 3.2+ compiler on linux systems,
        MinGW compiler (windows port of the GCC compiler),
        MS Visual C++ 7.1+ compiler on windows systems.
    - Uses the excellent CMake (Cross-platform Make) build system.
    - Highly modular architecture.
    - 2D/3D image processing library including a number of convolution
      filters, edge detectors (e.g. 3D canny edge detector), FFT, basic
      segmentation algorithms, ...
    - Math library providing static/dynamic vectors and matrices, sparse
      matrices, etc. Some advanced algorithms implemented: Fuzzy c-Means
      clustering, optimization of GMMs (Gaussian Mixture Models) using  
      Expectation-Maximization algorithm (EM algorithm).
    - Interface for supplied pre-compiled ATLAS, CLAPACK and UMFPACK
      linear algebra and math libraries (e.g. eigenvalues and eigenvectors
      problem).
    - Several image/slice formats supported: DICOM, JPEG and PNG.
    - Low-level vector graphics library for effective handling of polygonal
      surface models and tetrahedra meshes.
    - Benefit from templated C++ code, e.g. speed and scalability.
    - Interesting programming techniques used, such as smart pointers,
      reference counting, singletons, iterators and so on.
    - Inter-module communication over channels implemented via files,
      named/unnamed pipes (shared memory and network in future).
    - Multiplatform system library encapsulating threads, mutexes, critical
      sections, timers and etc.
    - Source code documentation generated using Doxygen.
    - Public BSD-like license, all source codes available.


[2 Installation]

(2.1) Required Software

    You should have the following software and/or libraries installed to compile
    and use MDSTk toolkit on Windows/Linux platform.

    - CMake (Cross-platform Make) - open-source build system.
        "CMake is used to control the software compilation process using simple
        platform and compiler independent configuration files. CMake generates
        native makefiles and workspaces that can be used in the compiler
        environment of your choice."
        http://www.cmake.org/

    - OpenGL and GLUT graphics libraries.

    Windows platform (MinGW):    
      - MinGW (Minimalist GNU for Windows) together with the GCC compiler.
        http://www.mingw.org/

      - MSYS (MinGW - Minimal SYStem)
        http://www.mingw.org/msys.shtml

      - Windows version of the GLUT library which can be found on the
        Nate Robin's GLUT for Windows page.
        http://www.xmission.com/~nate/glut.html

        Precomiled GLUT library for MinGW is prepared for you, it can be
        found in 'misc/glut/mingw_glut-v3.7.6.zip'. Simply unzip the archive
        to the MinGW root directory and place the file 'glut32.dll' to your
        'Windows\system32' directory.

      - WinAPI header files (can be downloaded from the MinGW web site).

    Windows platform (MS Visual C++):
      - Windows version of the GLUT library designed for MSVC which can be also
        found on the Nate Robin's GLUT for Windows page.

        Zipped precompiled GLUT library for Visual Studio can be found 
        in the 'misc/glut/vc_glut-v3.7.6.zip' archive. Unzip it into your
        MSVC directory and place the file 'glut32.dll' to your
        'Windows\system32' directory.

    Linux platform:
      - Both OpenGL and GLUT library should be alredy installed in all standard
        Linux distributions. 

      - Result of the 'ldd' command (Slackware Linux 9.1):
        libglut.so.3
        libGL.so.1
        libGLU.so.1
        libX11.so.6
        libXi.so.6
        libXmu.so.6
        libpthread.so.0
        librt.so.1
        libstdc++.so.5
        libm.so.6
        libgcc_s.so.1
        libc.so.6
        libXxf86vm.so.1
        libXext.so.6
        libdl.so.2
        libXt.so.6
        libSM.so.6
        libICE.so.6
        /lib/ld-linux.so.2

(2.2) Compilation

Download latest version of the MDSTk from its web site and unpack it somewhere.
If you don't have CMake installed on your system let's do it now. 

Under Linux use the 'cmake' or 'ccmake' utilities from a build directory
different from the source directory. Advantage of such out-of-source build
is that temporary files created by CMake and compiler won't disturb the source
directory. Also, it makes possible to have multiple independent build targets
by creating multiple build directories.

  > cd MDSTk
  > mkdir build
  > cd build
  > ccmake ..
  > make

All executables will be placed in the 'build/bin' directory and libraries
in the 'build/lib' directory.

If you want to build debug versions of libraries and binaries, modify
the CMake variable 'CMAKE_BUILD_TYPE'

  > ccmake .. -DCMAKE_BUILD_TYPE=Debug

Under Windows use the utility 'CMakeSetup' to generate project and solution
files for your MS Visual Studio. Open the solution 'MDSTk.sln' which
will be placed in the build directory and compile all libraries first.
Afterwards, choose and compile required modules (optionaly TESTs
and documentation).

Alternatively, you can use the same 'CMakeSetup' to generate Makefiles
for MinGW and MSYS. In the next step, the 'make' utility is called from
the build directory as mentioned above.

(2.3) 3rd Party Libraries

Here is a list of all external 3rd party libraries used by the MDSTk.
For convenience, all this libraries are supplied with the toolkit
in precompiled binary form. 

  ATLAS (Automatically Tuned Linear Algebra Software) library by R. Clint Whaley
  http://math-atlas.sourceforge.nte/
  
  FFTW (Fast Fourier Transform in the West) library by Matteo Frigo
  and Steven G. Johnson 
  http://www.fftw.org/
  
  UMFPACK library by Timothy A. Davis
  http://www.cise.ufl.edu/research/sparse/umfpack/  
  
  JPEG library by Independent JPEG Group
  http://www.ijg.org/
  
  libpng library by Glenn Randers-Pehrson et al.
  http://www.libpng.org/pub/png/
  
  zlib library by JEan-loup Gailly and Mark Adler
  http://www.zlib.net/

Some of these libraries are distributed under more restrictive license
then the toolkit one. For example, FFTW library uses the GNU GPL license.
If you feel restricted with this license, you can disable the library
during CMake configuration step. 


[3 Brief Guide]

MDSTk toolkit was designed to be highly modular. It consists of a number
of separate modules providing fundamental functions and algorithms. Individul
modules may be connected using simple channels into more complex units.
Actually, there are channels implemented over files, named pipes, stdio and
shared memory. Typicaly, modules are chained using shell unnamed pipes
and '|' character.

(3.1) Running module from command line

    -i  Specification of a module input channel. Channel is described by
    string of the form 'medium[:attrib1[:attrib2[...]]]'. Allowed medium
    types are 'stdio', 'file', 'pipe' and 'shm'. First one has no attributes,
    file and pipe has only one attribute filename. Communication over shared
    memory is not elementary (see documentation).
    
    -o  Output channel specification same as above.
    
    -log  Option selects a module log type. Allowed values are 'null' for no
    logging, 'stderr' for logging to the stderr, 'file' means logging to a file
    and 'both' selects logging to the both stderr and file.
    
    -h  Shows more detailed help.

(3.2) Samples

    > mdsLoadJPEG <data/jpeg/berounka.jpg | mdsSliceInfo
    or
    > mdsLoadJPEG -i file:data/jpeg/berounka.jpg | mdsSliceInfo
    - Reads input image and prints information about it.

    > mdsLoadDicom < data/dicom/80.dcm | mdsSliceRange | mdsSliceView
    - Loads DICOM image data, changes pixel value range from 0..4096
      (medical data) to the range 0..255 and shows the final grayscale image
      in a window.

    > mdsLoadDicom < data/dicom/80.dcm \
        | mdsSliceFilter -filter IF_GAUSSIAN -sigma 1.0 \
        | mdsSliceRange | mdsSliceView
    - Gaussian smoothing of the input image.


[4 Source Code Description]

All source codes of MDSTk libraries and modules can be found in the 'src'
directory. Because of templated design, huge code part can be found in header
files which resides in the 'include' directory.

(4.1) Brief description of libraries (src/lib directory)

  libBase         - Base classes, templates and functions (singletons,
                    small objects, type traits, logging, ...).
  libMath         - Static/dynamic vectors, matrices, random numbers, etc.
  libImage        - Image and volume processing functions.
  libImageIO      - Loading and saving of image data from/to various formats.
  libSystem       - Multiplatform library encapsulating threads, mutexes,
                    critical sections, timers and etc.
  libModule       - I/O channels, object serialization, ...
  libVectorEntity - Vector graphics library (polygonal surfaces, tetrahedra
                    meshes and so on).

(4.2) Base modules (src/mod directory)

  mdsCreateSHM          - Creates and handles a new block of shared memory.
  mdsLoadDicom          - Reads image in DICOM format from an input
                          channel and converts it to MDSTk native format.
                          Typical output is a density 12-bit grayscale image
                          called slice in medical imaging.
  mdsLoadJPEG           - Reads and converts JPEG image.
  mdsLoadPNG            - Reads and converts PNG image.
  mdsMakeVolume         - Module makes density volume data (grayscale 3D
                          image) from several input slices.
  mdsRGBImage2Slice     - Converts input RGB image to slice.
  mdsRGBImageView       - Shows input RGB image in OpenGL window.  
  mdsveJPEG             - Converts input slice to the JPEG image format.
  mdsvePNG              - Converts input slice to the PNG image format.
  mdsSliceCornerDetector - Provides basic image corner detection (e.g. Harris)
  mdsSliceCut           - Keeps values of a specified interval of pixels
                          unchanged, remaining ones are set to zero.
  mdsSliceEdgeDetector  - Advanced edge detection algorithms (e.g. Canny edge
                           detector).
  mdsSliceFFT           - This sample module computes two-dimensional DFT
                          of input slice.
  mdsSliceFilter        - Provides several image filtering functions such as
                          Median, Sobel and Prewit operators, Gaussian smoothing
                          and many others.
  mdsSliceHistEqualization - Histogram equalization.
  mdsSliceHistogram      - Shows histogram of input slice.
    
  mdsSliceInfo          - Shows information about input slice.
  mdsSliceRange         - Extends a given pixel value interval to specified
                          range (linear interpolation).
  mdsSliceSeg           - Sample slice segmentation module.
  mdsSliceSegHT         - Slice segmentation based on histogram thresholding.
  mdsSliceSegRG         - Simple region growing segmentation algorithm.
  mdsSliceSegEM         - Pixel-based segmentation using GMMs (Gaussian Mixture
                          Models and well known Expectation-Maximization
                          algorithm.
  mdsSliceSegFCM        - Another pixel-based segmentation algorithm. It uses
                          the fuzzy C-means clustering algorithm.
  mdsSliceSubsampling   - Module demonstrates use of the Gaussian pyramid for
                          image subsampling.
  mdsSliceTresholding   - Simple pixel value tresholding.
  mdsSliceView          - Draws input slice using GLUT and OpenGL.
  mdsVolumeBlending     - Merges two volumes.
  mdsVolumeCut          - Leaves a specified interval of voxel values unchanged
                          and sets remaining ones are set to zero.
  mdsVolumeFilter       - Several volume filtering functions (Median, Sobel
                          operator, etc.)
  mdsVolumeEdgeDetector - 3D Canny edge detection algorithm.
  mdsVolumeHistEqualization - Volume data histogram equalization.
  mdsVolumeHistogram    - Shows volume data histogram.
  mdsVolumeInfo         - Prints information about input volume.
  mdsVolumeLandmarkDetector - Experimental algorithms for detection of landmark
                              points in volume data.
  mdsVolumeRange        - Extends a given voxel value interval to specified
                          range.
  mdsVolumeSeg          - Sample volume segmentation module.
  mdsVolumeSegHT        - Volume segmentation based on histogram thresholding.
  mdsVolumeSegRG        - Region growing segmentation of volume data. Very slow
                          implementation! Should be remade in future.
  mdsVolumeSlit         - Splits input volume into several slices.
  mdsVolumeTresholding  - Simple voxel value tresholding.
  mdsVolumeView         - Reads input volume and visualizes it using GLUT
                          and OpenGL.

(4.3) Source code documentation

    MDSTk uses Doxygen as a documentation system. Doxygen makes it easy for
    a programmer to provide up-to-date source code documentation because
    it is a part of the source code. This documentation can be a great help
    for you if you want to find or add some toolkit feature. Automatically
    generated documentation is placed in the 'doc/doxygen' directory.
    
    How can you build the documentation? First, install the Doxygen system
    (http://www.doxygen.org/) and optionaly the Graphviz package
    (http://graphviz.org/) for drawing graphs such as class diagram.
    
    If you use Makefiles and 'make'
    command to compile the toolkit just type
    
      > make doc
    
    Even easier it is under MS Visual Studio. Open the generated solution
    choose project 'ALL_DOC' and compile it. This will make Doxygen
    documentation for you. You will find in your build directory.  


[5 Authors and Main Contributors]

You can contribute to development of the MDSTk in various ways, for example
by contributing source code, making new modules or by sending bug reports.
All contributors in any way are welcome!

(5.1) Major contributors
    
    Michal Spanel, spanel(at)fit.vutbr.cz
    http://www.fit.vutbr.cz/~spanel/
    Author of the MDSTk toolkit and leading contributor.

    Premysl Krsek, krsek(at)fit.vutbr.cz
    http://www.fit.vutbr.cz/~krsek/
    DICOM medical format parser, loading and saving of DICOM slices.
    Main author of the VectorEntity library.

    Miroslav Svub, xsvubm00(at)stud.fit.vutbr.cz
    http://www.stud.fit.vutbr.cz/~xsvubm00/
    Simple histogram based segmentation methods.
    Conversion to CMake build system. 

    Ondrej Siler, siler(at)fit.vutbr.cz
    http://www.fit.vutbr.cz/~siler/
    VectorEntity library.

(5.2) and others ...

    Michal Rozsypalek
    Martin Skotnica

If you noticed that some contributors are missing, please mail to authors.


[6 Bug Reporting]

We don't promise that this software works. But if you find any bugs, please
let us now. Mail your bug reports to spanel(at)fit.vutbr.cz.

================================================================================

