3D Segmentation Optical Imagining Software This document provides installation and usage directions for the cell segmentation programs. Details on the algorithms used, and justifications can be found in 3D Segmentation of Whole Cells and Cell Nuclei in Tissue using Dynamic Programming Dean P. McCullough, Prabhakar R. Gudla, Karen Meaburn, Amit Kumar, Michael Kuehn, Stephen J. Lockett 1. Copyright: All software associated with this project is copyrighted 2007 by Dean P. McCullough. The source code Copyright License for this software is contained in the file COPYING, a part of this distribution. 2. Installation: This code requires GTK+2.0. In order to test if the necessary libraries have been properly installed. execute: pkg-config --libs gtk+-2.0 This should return something like: -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 -lm -lpangocairo-1.0 -lfontconfig -lXext -lXrender -lXinerama -lXi -lXrandr -lXcursor -lXfixes -lpango-1.0 -lcairo -lX11 -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0 Details will depend on system configuration. Also execute: pkg-config --cflags gtk+-2.0 which should return something like: -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include Most Linux installations will have these properly configured. Next run 'make'. This should create two executable file 'cell_wall' which does the cell segmentation, and 'shape' which computes some shape statistics on each segmented cell. 3. Image File format: This program assumes that the image files are in Image Cytometry Data Standard (ids) format. In this format, each image is stored as two files. The first, with the extension .ics or .ICS, is an ascii file containing image characteristics. An example for one of the images used in testing this code is given below: ics_version 1.0 filename Kathy_5z6ac layout parameters 4 layout order bits x y z layout sizes 8 512 512 27 layout coordinates video layout significant_bits 8 representation format integer representation sign unsigned representation compression uncompressed representation byte_order 1 parameter labels intensity x-position y-position z-position history software DIPlib with dipIO The second file, with the extension .ids or .IDS, is a binary file with the actual image voxel values. See http://libics.sourceforge.net for more information on this format. 4. cell_wall Execution: In a command window simply execute /cell_wall The program will ask a series of questions, to configure the the software for your image. a. It will ask if you wish to see the details of the copyright license. Usually, one will simply b. Next, it will ask for the Base Name of image file: Give the relative path name of the file without the .ics or .ids extensions. c. Next, it will ask if overlap should be allowed between cells. Indicate yes or no. I usually indicate no. The program will open a log file (append to it, if it already exists), and provide some information about the size of the image. d. It will then usually ask for the aspect ratio. Usually the interval between successive voxels in the z direction is greater than that in the x or y direction. This ratio (z-distance/x-distance) is the aspect ratio. If this ratio is in the *.ics file, it is read from that file, and no input is requested. e. Should a first difference be done on the image? If the entire cell is stained, rather than just the cell wall, some type of first difference is required to make the edge stand out. f. Ratio of scaling: The program gives the value of the largest voxel and for the smallest voxel. It is often desirable to rescale these. If a value of .02 is given, then the largest 2% of the voxels are set to 255, and the smallest 2% are set to 1. The other voxels are scaled between these two values. If no scaling is desired, then enter 0. The program will indicate what these 2% and 98% values were before scaling, and the scaling factor. g. Avoid voxels with 0 value (Y,N): Should we avoid including in the surface voxels with value 0? This is usually desirable when we wish to not have overlap between adjacent cells. 5. GUI: At this point, a gui is generated. This gui has four regions: The left image, which is a rectangular coordinate image for some value of z. The control buttons for the left image. The control buttons for the right image. The right image, which is at this point inactive. It will contain the polar coordinate image centered at the cell being segmented. However, the command window, the window which was used to start the program, is still active, and should be displayed. a. Image generated, please select center of cell The "up" and "down" buttons in the control section for the left image can be used to find the best z-axis position for the center of a cell to be examined. Then the mouse can select a point approximately in the center of this cell in the left image. The exact xy-plain or point selected is not that important. b. Please now select a boundary point for this cell: In the same z-axis position, select a point in the left image on the surface of the cell. c. Please click anywhere on diagram to continue. The best 2-dimensional cell wall is then computed, and displayed. Using the selected center of the point as the origin, and the selected boundary point as the north pole, the polar coordinate version of the image is also generated in the right window. Click anywhere on the left window to continue. d. Is boundary acceptable (y,n,q): Is this 2-dimensional cell wall acceptable? If yes, the program will continue with this cell. If no, the user is invited to edit this cell wall. Please select additional boundary points for this cell using the right button. When finished, click left. When click left, the program will recompute and display the new 2-d cell wall based on the editing points. If q, then quit this cell, and return to the step of defining the center of the cell. e. Please click anywhere on diagram to continue. The three dimensional surface has been computed and displayed in both the left and right windows. By using the "up" and "down" buttons, one can look at the position of the cell wall for other values of z in the left window. By using the numbered buttons in the right control panel, the image can be rotated to any of 256 angles. f. Is surface acceptable (y,n,q): Again, if yes, the program will continue. If no, g. Add or delete points (a,d): It has been relatively unsuccessful to subtract points, and is usually easier to add edit points. h. Please select additional boundary points for this cell using the right button. When finished, click left. Either image (or both images) can be used for selecting points. However, in general, it seems easiest to use the right image for this, changing the rotation to find those areas which need correction. if q, then quit this cell, and return to the step of defining the center of the cell. 6. Buttons: Left image buttons: The label indicates the z-axis level being displayed. The "up" and "down" buttons change this z-axis level being displayed. "Save cell wall" saves into a gzip file the segmented cell that has just been segmented for future processing. It also marks as 0 the voxels in this cell (will display as blue at this point.) "Load cell walls" will look for all previous saved cell wall gzip files, and read each, setting the voxel values to 0. This is used to resume an interrupted session. "Save image" creates a jpeg image of the left display. This is used to create images for reports. Right image buttons: The label indicates the angle of the display (0 - 255). The numbered buttons will change this angle by the indicated amount, in the indicated direction. "Save polar" creates a jpeg image of the right display. The jpeg files are labeled sequentially to prevent overwrite. 7. Parameters: Many compile time parameters are set in the sphere_image.h file. These are primarily the maximum space set aside for various arrays. These can be changed by editing this file. In defining the spherical coordinate image, only those voxels between minrat and maxrat of the distance between the selected center and edge point are used. Currently, these are set in read_image.c to .3 and 4.0. If the cells are quite irregularly shaped, then this might not be adequate. They can be changed and the code recompiled. 8. 'shape' execution: The program 'shape' is primarily a scaffold to show how to compute statistics on the cells. You might wish to modify it to compute the particular statistics of interest to you. After running cell_wall, and creating "saving" a number of cell walls, in the command window which contains these cell description files (*.wall.#.gz files), simply execute /shape. The program will ask a series of questions, to configure the the software for your image. a. Base Name of image file: Give the relative path name of the image files without the .ics or .ids extensions. b. Aspect Ratio of Z axis to XY plain: Again, give the aspect ratio. c. It will then load each cell description file, compute some statistics on that cell, and then go to the next file. The program stops when the next expected file can not be found, with a message of the form "Failed on Kathy_5z6ac.wall.6.gz". d. The program will write the statistics to standard out, but it also creates a file named "image name".stats containing the important information. For each cell, this file will contain i) The center coordinates ii) The surface area iii) The volume iv) A shape statistic based on the ratio of these two values. v) The eigen vectors and eigen values. vi) The ratio of the largest to smallest eigen value (another shape statistic).