===========

Submodules
----------

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

  $ git submodule update --init

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

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
  • libx11-dev
  • libx11-xcb-dev
  • libxcb1-dev
  • libxrandr-dev
  • libxi-dev
  • freeglut3-dev
  • libglew1.6-dev
  • libcairo2-dev
  • libpng12-dev
  • libmagick++-dev
  • libcurl4-openssl-dev
  • libtiff4-dev
  • libhdf5-serial-dev (optional)

A recent version of vigra will be downloaded and compiled automatically.

To compile the python wrappers (pysopnet), you need additionally:

  • libboost-python-dev
  • libpython-dev

The build process is managed by cmake of which you need at least version 2.8.8.

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 or set the environment variable GUROBI_ROOT_DIR accordingly
  before calling cmake.

Compiling
---------

If you are just interested in the python wrappers, it is enough to call

  $ python setup.py install

from the repository's main directory. This will launch cmake and install the
wrappers, given that all dependencies are fulfilled. You might have to run the
above command as root to install the wrappers in the python system directory.

For a standard build, create a build directory (e.g., ./build), change into it
and type

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

Cmake will try to find the required packages and tell you which ones are
missing. 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.