/cdac

Cell-Derived Active Contour algorithm for tracking cells in live microscopy images

Primary LanguageCGNU General Public License v3.0GPL-3.0

This is ROBIE: Robust OBject Inference Environment

It is a utility that is designed to track the outlines of cells in time-lapse microscope images and is especially suited to conditions of low contrast, high noise, and slow frame rate.

The details of the algorithm were outlined in the paper, "A Cell Derived Active Contour (CDAC) Method for Robust Tracking in Low Frame Rate, Low Contrast Phase Microscopy - An Example: The human hNT Astrocyte", submitted to PLoS ONE. Using the code in this package it should be possible to exactly reproduce the results seen in that paper.

----------------------------- Environment ------------------------------

The code was designed to be compiled and run in a GNU/Linux environment. The code was tested in the following operating system environment (given by $uname):

	Linux en-439-0325-004 3.0.0-32-generic #51-Ubuntu SMP x86_64 GNU/Linux

And the following hardware:

	Intel Core i5-2500 w/ 6 GB RAM

Other environments and cpu architectures have not been tested.

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

Before compiling, you will need to make sure you have the following libraries installed:

libxml: http://xmlsoft.org/
libavl: http://www.stanford.edu/~blp/avl/
libics: http://libics.sourceforge.net/

These libraries are open-source and can be downloaded from their respective websites, compiled, and installed. If your distribution has a package manager, however, it is best to first check if they are available there. Note that LibICS was not part of the standard package repositories of most GNU/Linux distributions at the time of this release.

To compile the code, in addition to the standard (binary) packages, you will also need the development (header) packages.

If you need the image export functionality, you should also have the NetPBM package (not library!) installed: http://netpbm.sourceforge.net/

------------------------------ Compiling -------------------------------

Compiling follows the standard procedure:
# ./configure
# make
# make install

For further details, see INSTALL.

------------------------- Program Descriptions -------------------------

This program is organized as follows.

The package is composed of several programs and several modules which are shared across programs. The programs are:

	robie
	robie-present
	extract2
	cellcmp2
	textextr
	cellrend2.sh
	svgtotext
	doall.sh
	
'robie' is the main program; it accepts as input 1. a series of images (either as separate PGM files or a single ICS file) 2. initial outline for the cells we want to track 3. a kappa value, and outputs either a series of SVG images of the cell outlines or a series of text files describing the outline (in native format). Example usage of the program is given in the next section.

'robie-present' is a utility program used to generate the figures seen in the paper. It takes the output of robie (text files + input images) and clips them to a specified rectangle and tiles them together in a single image.

'extract2' is a utility program used to extract the individual images from an ICS file. This comes in handy when preparing images for the paper, as robie-present is not capable of reading ICS files. This program has many advanced features; however, none of them were used in the preparation of the paper. For the preparation of the paper, the images were extracted as raw 16-bit pgms.

'textextr' extracts (x,y) coordinate data from the internal format files.

'cellcmp2' is a utility for comparing the outlines of cells produced using various different methods, using the Hausdorff metric. This utility was used to generate the data seen in the distance comparison plots.

'cellrend2.sh' is a script for creating artificial 'microscope' images from outline data. Requires the NetPBM package to work.

'svgtotext' is a small utility for converting the outlines in SVG images to the internal format used in the program. This is useful for preparing data for visualization and comparing outlines.

'doall.sh' is an automated script for going through the procedure of extracting the microscope data, running robie on it, assembling the output into a collage, and comparing the generated outlines with that produced by hand.

---------------------------- Tracking cells ----------------------------

The main focus of the software is tracking cells and this may be done in the following way.

1. Find the outline(s) of the desired cells in the data. The program accepts outlines in SVG format, and thus any SVG editor may be used. A good SVG editor (and the one that was used in this work) is the freely-available Inkscape program. Note that for the program to accept the outline, all nodes in the path *must* be of type 'corner' (smooth or bezier nodes not accepted). The ID of the paths can be used to distinguish the cells; the program preserves the IDs when producing SVG output. To set the ID of the path in inkscape, right-click the path and select "Object Properties". Multiple cells can be identified in the same SVG file. For example, call the resulting file 'outline.svg' (without the quotes).

2. If the input data (microscope image sequence) is available in 12-bit (16-bit formatted) grayscale ICS format, it may be left as-is. Otherwise, input data must be converted to a sequence of 'raw' PGM images (either 8-bit or 16-bit PGMs are accepted). To tell the program which files to use, the program accepts filenames in printf-style format. For example, if the filenames are img0001.pgm, img0002.pgm, etc., the name img%04d.pgm must be used on the command line.

3. Make sure there exists a folder where the program can write output data to.

4. Run the program, using the following arguments:

$ robie <filename.ics | filename<format>.pgm> <outline.svg> startframe endframe kappa <output-dir> <phase.txt> [-t] [low_conf_rm]

For basic use, phase.txt is not required and can be set to 'none'. So, given the example names specified in (1) and (2), a valid invocation would be:

$ robie img%04d.pgm outline.svg 10 100 0.02 robieoutput/ none -b

This reads files img0010.pgm, img0011.pgm, ..., img0100.pgm, assuming outline.svg contains the outline for img0010.pgm, tracks the cell, and outputs a series of SVG files (for quick viewing) alongside a series of ascii human-readable outline files in the directory robieoutput/. 

The format of the outline files is as follows. First there is a number indicating the number of cells that have been tracked. Then a sequence of cell data follows. The first number in this sequence is the number of different 'possibilities' for the cell outline (usually just 1). Then a sequence of outlines follows. The first number here is the number of points in the outline, followed by a table of the form:

<x> <y> <phase>

Where (<x>,<y>) are the coordinates of the vertex point and <phase> is a number between 0 and 2*pi that can be used to relate vertices of different time frames together.


------------------------------ Disclaimer ------------------------------

This software is STRICTLY EXPERIMENTAL and provided solely in the interest of scientific transparency, under the terms of the GNU GPL. This is due to the fact that disclosure of software, experimental or otherwise, is required as per the conditions of publishing in PLoS ONE. While it is legal to use this software in a professional workflow or for purposes of teaching and/or entertainment, use in any of these ways is emphatically discouraged, and the author bears no responsibility for any damages that may result to data, professional integrity, intelligence quotient, or honor.

While the software has been extensively tested under 'controlled' conditions, it will most likely produce unexpected behavior 'in the wild'. Use at your own risk.