********************************************************************************
**************************** BIOEMERGENCES WORKFLOW **************************** 
********************************************************************************

This file contains instructions for installing and running the BioEmergences
Workflow.
Visit the website (http://www.bioemergences.eu/) for more informations.

I - CONTENTS OF THE BIOEMERGENCES-WORKFLOW REPOSITORY
-----------------------------------------------------
Once uncompressed, the folder contains the following elements:
  - Algorithmes   : algorithms' source code, with their command for compiling
                    and running
  - BioEmergences : graphic user interface of BioEmergences Workflow to launch
                    pipelines manually
  - InstallScript : scripts to compile the libraries and the algorithmes
  - lib           : source code of required libraries
  - Loci2VTK      : image files converter
  - Mov-IT        : visualisation Interface
  - install.sh    : the script to install the workflow on your computer
  - LICENSE.txt   : the licence terms you accept by using the workflow
  - README.TXT    : this file



II - INSTALLATION AND SOFTWARE REQUIREMENTS
-------------------------------------------
The BioEmergences Workflow can only run on Unix-derived System so far.
It was tested on:
  - OS X (10.9.5, 10.10)
  - Ubuntu (12.04 LTS 32/64bits, 14.04 LTS 32/64bits)
  - Debian (7.6.0 64bits)

  II.i - Requirements
  -------------------

    II.i.a - OS X
    -------------
    In order to compile the Workflow, you have to install a c/c++ compiler.
    The simplest way is to launch the "AppStore" application and install
    "XCode". Once installed, run XCode and install the command line tools.
    If you are registered as a developer for apple (free and easy) you can
    download the command line tools directly from the apple developers
    website.

    II.i.b - LINUX
    --------------
    Installation will check for missing packages.

  II.ii - Installation
  ---------------------

    II.ii.a - OS X
    --------------
    Download and run the installation package:
    http://bioemergences.iscpif.fr/bioemergences/openworkflow-workflow.php

    II.ii.b - LINUX and OS X (command line)
    ---------------------------------------

    Download the compressed folder from:
    http://bioemergences.iscpif.fr/bioemergences/openworkflow-workflow.php

    /!\ Commands below are preceed with a "$" character. You must not copy this
        character when running a command. Sequences between [] (brackets) must
        be replaced by the appropriate text.

      1) Open a new terminal session
      2) Change current directory to the BioEmergences-Workflow folder
         $ cd [LOCAL-PATH-TO-BIOEMERGENCES-WORKFLOW]
      3) Run the following command:
         $ ./install.sh
         It might ask you for your password once

    The installation takes time (more or less 20 minutes).
      - First of all, this script may need to install a few packages:
        * java, for the GUIs interface, (package default-jre)
        * a c++ compiler,    (package build-essential with g++)                                                  
        * and some OpenGL libraries (packages freeglut3 and freeglut3-dev)                                       

      - Second of all, the script will compile specific versions of certain
        libraries:
        * ANN, a library for Approximate Nearest Neighbor searching (see
          http://www.cs.umd.edu/~mount/ANN/ for more info),
      	* CMAKE, a cross-platform open-source build system (see
          http://www.cmake.org for more info),
      	* MPICH, a high performance and widely portable implementation of the
          Message Passing Interface standard (see http://www.mpich.org for more
          info),
      	* BOOST, a library which provide support for several tasks and
          structures (see http://www.boost.org for more info),
      	* ITK, an cross-platform open-source system which provides developers
          with an extensive suite of software tools for image analysis (see
          http://www.itk.org for more info),
      	* VTK, an open-source, freely available software system for 3D computer
          graphics, image processing and visualization (see http://www.vtk.org
          for more info);
      
      - Then, the script will compile the algorithms of the BioEmergences
        Workflow;
      - Finally, the script will install the applications
     Loci2VTK, MovIt and the BioEmergences GUI to your BioEmergences-Workflow
     folder and remove the install script.

    If you know what you are doing, feel free to edit the install.sh file, but
    it might damage the installer.

    The installation process will create two files in the BioEmergences-Workflow
    folder. One is called BioEmergences (see III.i) and the other is called
    movit (see IV)

  II.iii - TROUBELSHOOTING
  -------------------------
  Please, make sure the absolute path to BioEmergences-Workflow does not contain
  spaces.

  On Ubuntu 14.04 64bits, an error may occur during the installation of
  libGL.so. The OpenGL librairies may be badly linked.
  To fix this error do the following: 
    1) Change current directory to /usr/lib/x86_64-linux-gnu
       $ cd /usr/lib/x86_64-linux-gnu
    2) Find broken symbolic links
       $ find . -type l -! -exec test -e {} \; -print
    3) Repair symbolic links (super-user password will be prompted)
       $ sudo ln -s [EXISTING-LIBRARY] [BROKEN-SYMLINKS]
    4) Restart the intallation process

    Example :
        $ ll /usr/lib/x86_64-linux-gnu/libGL.so
        ->  /usr/lib/x86_64-linux-gnu/libGL.so -> mesa/libGL.so
        $ ll /usr/lib/x86_64-linux-gnu/mesa/libGL.so
        -> /usr/lib/x86_64-linux-gnu/mesa/libGL.so -> libGL.so.1.2.0
        $ ll /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1.2.0
        -> no file found
        $ ll/usr/lib/x86_64-linux-gnu/mesa/libGL.*
        -> /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1
        $ sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1.2.0
        -> Repair symbolic links
        $ ./install.sh
        ->  Restart the intallation process

  II.iv - CHECK YOUR INSTALLATION FOLDER
  ---------------------------------------
  After the installation, your BioEmergences-Workflow folder should contain
  * OS X :
    - Algorithmes       : compiled algorithms along with their associated run
                          scripts
    - BioEmergencesGUI  : GUI application
    - lib               : compiled support libraries for the algorithms
    - licence.txt       : terms and licence you accept by using the standalone
                          version of the BioEmergences Workflow
    - Loci2VTK          : converter application
    - movit828          : MovIT software
    - README.txt        : this file
      
  * Linux :
    - Algorithmes       : compiled algorithms along with their associated run
                          scripts
    - BioEmergences     : GUI application
    - BioEmergencesGUI  : GUI application's files
    - lib               : compiled support libraries for the algorithms
    - LICENSE.txt       : terms and licence you accept by using the standalone
                          version of the BioEmergences Workflow (CC BY-NC-SA)
    - loci2vtk          : converter application
    - Loci2VTK          : converter application's files
    - movit             : Mov-IT software
    - MovIT             : Mov-IT software's files
    - README.txt        : this file

III - RUNNING THE BIOEMERGENCES WORFKLOW
----------------------------------------

  III.i - BIOEMERGENCES WORFKLOW DESCRIPTION
  ----------------------------------------
  The algorithms directory contains:
    - Converter: several tools to convert data
      * Convert3DTIFFtoVTK      : convert 3D tiff file to 3D VTK;
      * ConvertCentersTXTtoVTK  : convert list of TXT center files to VTK;
      * ConvertCentersVTKtoTXT  : convert VTK center files to TXT files;
      * ConvertLSMtoVTK         : convert LSM files format (Zeiss) to VTK
                                  format;
      * ConvertVTKto3DTIFF      : convert VTK images files to 3D TIFF stacks;
      * ConvertVTKtoPolydata    : convert VTK segmented images files to
                                  Polydata;
      * CreateMOV-IT            : create new experiment in the cache folder of
                                  Mov-IT;
      * MergeVTK                : merge segmented cell files in one big file for
                                  each time step.

    - Filtering: image Filtering algorithms
      * gmcfFiltering           : a preliminary image filtering algorithm
                                  removes noise from raw images through
                                  geodesic mean curvature flow (GMCF)

    - CenterDetect: centroid detection algorithms
      * DifferenceGaussia       : centroid detection algorithm which perfoms
                                  a difference of Gaussians convolution
                                  filtering (DoG)
      * LevelsetCenterDetection : center detection methods based on flux-based
                                  level set method which  relies on nonlinear
                                  multiscale PDEs (FBLS)

    - Segmentation: segmentation algorithms (SubSurf)
      /!\ Note that segmentation algorithms can use both Center Detection and
          Tracking output (respectively FBLS and Dog, and SimAnn). We invite
          the user to use (when possible) a tracking output, since the
          Simulated Annealing is able to correct detection errors /!\
      * MembraneSegmentation    : membrane shape segmentation using a
                                  subjective surface algorithm
      * NucleiSegmentation      : nuclear membrane shape segmentation using the
                                  subjective surface algorithm

    - Tracking: cell tracking algorithms
      * SimulatedAnnealing         : Simulated Annealing algorithm to perform
                                  cell tracking (SimAnn)

  III.ii - CONVERT YOUR DATA TO VTK
  ---------------------------------------------------------
  VTK is the image format we have choosen to work with rawdata. In order to use
  the algorithms proposed by BioEmergences, you have to convert your data to
  the VTK format.

  We provide Loci2VTK, a simple application to convert LOCI compatible file
  formats to compressed VTKs

  To convert your data, run Loci2VTK:
    1) choose your source files*
    2) choose your destination directory
    3) give a name to your experiment with the format: <yymmdda> where
        - yy is the last 2 digits of the acquisition year
        - mm is the acquisition month
        - dd is the acquisition day of the month
        - a is a letter from "a" to "z" in case you generated more than one
          dataset the same day
        - example: the experiment "141120a" is the first dataset made on
          2014, 20th November
    4) check the options according to your needs:
        - Extract metadata only   : generates XML files with metadata; no VTKs
                                    will be generated. Note that some
                                    informations may not be extracted
        - Force 8 bits conversion : scale voxels value to fit in one byte
    5) click on more to specify a custom spacing or adjust brightness & contrast
    6) click on Convert
  You can also use the converter in command line
  See the README.txt file inside the Loci2Vtk folder for details

  III.iii - USING THE BIOEMERGENCES GRAPHICAL USER INTERFACE
  ---------------------------------------------------------
  Double-click on the BioEmergences application to run the Graphical User
  Interface. The GUI is composed of one window containing "Click boxes" (one for
  each process). "Click boxes" must be filled from top to bottom.

    1) Choose your input data. If you do not have VTK files, click on the top
       left box and choose a microscope file. The converter Loci to VTK we
       provide uses the LOCI tools to recognize microscopy format and convert
       them to VTK (http://loci.wisc.edu). If your dataset is made of multiple
       files, select one of the dataset's file and Loci2VTK will be able to find
       the other files automatically. If you already have VTK files, click on
       the top right box and select the folder containing all the VTK files.
       Channels must not be separated.
    2) Click on "Select nucleus channel" and choose the nucleus channel from the
       proposed menu.
       Repeat the operation for membranes if membrane channel is provided.
       Select the destination directory in which every output files will be
       written.
    3) Run the algorithms for filtering, center detections, segmentations and
       tracking

  III.iv - USING COMMAND LINE TOOLS
  ----------------------------------
  Each algorithm folder contains a "LaunchLocal.sh" file. This file accepts
  two parameters (input and output):
  $ ./LaunchLocal.sh [INPUT] [OUTPUT]
  
  EXAMPLE:
    To run the gmcFiltering on VTK located in ~/input, run:
    $ bash Bioemergences-workflow/Filtering/gmcFiltering/LaunchLocal.sh ~/input ~/output
    In this example, output files will be written into the ~/output folder.

  Each algorithm has its own settings. Open Parameters.sh script with a text
  reader (cat, vi, nano, gedit, ...) for more information.

IV - VISUALIZE THE RESULTS WITH THE MOV-IT GRAPHICAL USER INTERFACE
-------------------------------------------------------------------
Run the Mov-IT application and follow instructions available online on the
BioEmergences Workflow website :
http://bioemergences.iscpif.fr/bioemergences/openworkflow-movit.php
