README

SOPNET

===========

Submodules
----------

If you haven't done so already, make sure that all submodules are up-to-date:

  $ git submodule update --init

Build System
------------

Create a build directory (e.g., ./build), change into it and type

  $ cmake [path_to_sopnet_directory (e.g. '..')]

Dependencies
------------

cmake will try to find the required packages and tell you which ones are
missing. All packages except for the vigra library and the Gurobi solver can be
installed using the default Ubuntu repositories:

  • libboost-all-dev (make sure libboost-timer-dev is included)
  • liblapack-dev
  • libfftw3-dev
  • libx11-dev
  • libx11-xcb-dev
  • libxcb1-dev
  • libxrandr-dev
  • libxi-dev
  • freeglut3-dev
  • libglew1.6-dev
  • libcairo2-dev
  • libpng12-dev
  • libtiff4-dev
  • libhdf5-serial-dev (optional)

To get a recent version of vigra, perform the following steps:

Vigra
-----

  Get vigra from

    $ git clone git://github.com/ukoethe/vigra.git

  or

    http://hci.iwr.uni-heidelberg.de/vigra/vigra-1.8.0-src.tar.gz

  and build it
  (http://hci.iwr.uni-heidelberg.de/vigra/doc/vigra/Installation.html). Set the
  Vigra_BUILD_DIR to the  directory where you built it.

Gurobi Solver
-------------

  Download and unpack the Gurobi solver, request a licence (academic licences
  are free). Run

  $ ./grbgetkey <you-licence-id>

  in the gurobi bin directory from an academic domain to download the licence
  file (gurobi.lic). Make sure the environment variable GRB_LICENCE_FILE points
  to it. Set the cmake variable Gurobi_ROOT_DIR to the path containing the lib
  and bin directory.


After cmake finished without errors, run

  $ make


Usage
=====

After successful compilation, two executables have been created: 'sopnet' and 
'graphcut'.

graphcut
--------

Use this binary to create a set of segmentation hypotheses from membrane 
probability images. When started, this binary expects a sequence of membrane 
probability images in a directory "./membranes". You can play with the 
parameters by adjusting the sliders and walk through the stack by pressing 'a' 
and 'd'.

When invoked with the argument 'createSequence' (either via command line or 
config file, see ./graphcut --help), 'graphcut' will create a sequence of 
segmentations for varying values of the foreground prior. Each segmentation is 
put in a directory "./sequence" and an average of all sequences for each 
membrane probability image is put into "./slices". The latter version contains 
all the relevant information about the extracted hypotheses in its component 
tree and is the input to 'sopnet'.

sopnet
------

Sopnet expects four versions of the image stack in four directories: 
'./membranes' for the membrane probability images, './slices' for the 
segmentation hypotheses (created by a sequence of graph-cuts), './raw' for the 
original intensity images, and './groundtruth' for same-intensity-is-same-neuron 
ground-truth segmentation.

When invoked with the argument 'train' (either via command line or config file, 
see ./sopnet --help), 'sopnet' will use the ground-truth to train a random 
forest on neuron slice assignments. The classifier will be stored in 
'segment_rf.hdf'. Without the argument, 'sopnet' will reconstruct neurons using 
the trained classifier. For both operations, you can specify a subset of the 
sections to use from the stack.

Configuration
=============

All program options can be set either by command line or a config file (for a 
listing of all available options, type '[name_of_executable] --help').  The 
default name of the config file is [name_of_executable].conf.  Hence, a symlink 
'sopnet-train' to the binary 'sopnet' will read its configuration from 
sopnet-train.conf.