	Cartilage Image Analysis Program
	Copyright (c) 1992-1996 University of Alberta


Introduction
------------
	
This software was written to aid in the analysis of fluorescence images of
cartilage.  Such images are of thin slices stained with red and green dyes
to indicate cell viability.  This software can be used to automatically count
the cells visible in such images and determine the colour of each cell.  Also,
the images typically showed more than one region of the tissue so a method of
distinguishing different regions using lines is also provided.

This software has been used with images of other tissues.  In cases where the
automatic counting algorithm fails, hand counting of up to two cell types can
be done using the mouse.


Licence
-------

This packages is provided under the terms of the GNU General Public Licence.
Please read the COPYING file for more details.


Disclaimer
----------

This software is considered beta quality.  It is relatively bug free when
used in an environment similar to the one it was designed and written in.
This software is provided "AS IS" with no warranty or guarantee either
written or implied.  It is being made available primarily to other developers
who may be interested in the ideas contained within.


Theory of Operation
-------------------

The analysis done on the thin slices of cartilage is the simple counting of
alive vs. dead cells from fluorescence images.  The cells are counted in the
three main regions of the cartilage.  The superficial, intermediate and deep
layers.  The difficulties found were that manually counting the cells in all
images was a very tedious task.  Therefore, an automatic method had to be
found.

The method used for counting cells basically consists of two steps.  First,
find the brightest part of the cells, assumed to be the center.  Then working
from this point, the cell is filled by following the gradient of intensity down
to the edge.  Once the cell has been filled, the total red intensity, total
green intensity, and intensity weighted coordinates of the center of the cell
are stored in a data file for later analysis.  To indicate the different layers
in the cartilage, lines are drawn on the image and these lines are recorded in
the data file to aid further analysis.

Before any of this analysis is done, the images are processed to eliminate 
useless information.  This processing involves smoothing and contrast
enhancement.  The smoothing eliminates any local extreamum in intensity not
corresponding to the center of the cell and helps to create a Gaussian
distribution of intensity across the cell.  The contrast enhancement puts the
average background intensity to zero, and maximizes the contrast of the rest
of the image.  Contrast enhancement is done on the red and green parts
separately.  This is because the red part typically requires more enhancement
than the green.  These enhancements are done in a consistent manner on all
images.

Finding the center of the cell is a relatively simple task.  Search for the
brightest pixel.  This search begins in the upper left corner and proceeds in
blocks of about 50x50 pixels.  Once a bright point is found, the cell is filled
in.  To fill in the cell, proceed outward in all directions until either some
constant minimum intensity is reached, or intensity starts to increase.  In
this latter case, another cell has been found and therefore the fill must stop.
Practically, this filling works from the center to the left and right edges,
and then as each horizontal line is completed the fill continues up and down.
Once the cell is completely defined, the total red and total green in the cell
is stored in a file.  Also stored in the data file are the intensity weighted
coordinated of the center of the cell.  Using intensity weighting provides a
more accurate position for the center of the cell than a simple centroid of the
pixels.

Lines are then drawn to indicate the boundaries between the different layers of
the cartilage.  The locations of these lines are also stored in the data file
for future reference and analysis.

Using the total red and total green intensities, the color of the cell can be
determined.  Simple take the ratio of red to green and compare it to some
constant.  Anything higher is red, lower is green.  To tally the red and green
cells in each region of the cartilage, the coordinates of the cell are compared
with the locations of the boundary lines to determine which layer the cell is
in.  Then the cells are simply counted up.  This provides the viability
information needed.


Contents
--------

This package contains the following files and directories:

  AUTHORS.txt   - authors of this software
  COPYING.txt   - licence
  ChangeLog.txt - list of changes
  README.txt    - this file
  TODO.txt      - future plans
  cartanal.*    - main program files
  lib           - essential image processing library
  old           - older versions of this software
  tgacomp.*     - image compression program


Installation
------------

This release consists of source code only.  To be useful, the code must first
be compiled.  It is believed that this code was last compiled for Windows 95
using Borland C++ version 4.5.  You will have the greatest chance of success
compiling this software yourself if do it within a similar development
environment.


Usage
-----

* Cartanal is a Win32 program and should be run on Windows NT or Windows 95.
  This version has not been tested on Win32s machines and will not be
  supported on these machines.

* The option "Use 24-bit DIB Display" in the preferences dialog is currently
  not implemented.  In the future this option can be used to obtain better
  colour quality when using Cartanal on machines with greater than 256 colours.

* The options "Display Histograms" and "Display Stack Usage" are included for
  debugging purposes and should normally be turned off.

* The option "Use Old Enhance" forces enhancement to be done using the
  algorithm of previous versions.  This option will be removed in future
  versions.

* The option Display RGB Values can be used to see the RGB values of pixels as
  the mouse is moved over the display window.

* A Hand Counting feature has been added which will allow the user to use the
  mouse to count cells and have the results stored in a text file similar
  to the .dat files.  The Hand Counted data is stored in a .hnd file.

* The option Background StDevs indicates how may Standard Deviation units from
  the mean background the threshold should be placed.  1 (ie. 10/10) is the
  default but higher values can be used to give a darker image while smaller
  values give a lighter image.

* The option Extra Smoothing should be used when working with high
  magnification images.  For low magnification images this option should be
  turned off to ensure that cells are not smoothed into the background.

* The Localization of Features option can be used to select how the image will
  be enhanced for contrast and brightness.  Global is the old method where the
  entire image is enhanced using one set of values for background and
  threshold, while selecting the medium or local settings will cause
  calculation of background and threshold to be done for local regions within
  the image and then enhancement is done within each local region.


Bugs
----

* When selecting more than one file at a time in the "Add File" dialog, there
  is a limit to the number of files that can be chosen.  Therefore, one must
  limit selections to about 8 or so files at once.

* As explained above, the option "Use 24-bit DIB Display" has not been
  implemented in this version.

* The little white circles displayed when counting are not automatically
  repainted when the display window gets burried behind other windows.  The
  cells have actually been counted; the white circles just get lost.  The
  final display when counting is complete and accurately indicates which cells
  have been counted (darkened) and which have not.

* The help file is that of version 1.3 and thus does not reflect the new
  features of version 2.1.


Home Page
---------

Located at:

	http://stoa.dhs.org/~cvs/cartanal/

Please send comments, criticism, bug reports, etc. to:

	Chris.Studholme@ualberta.net


--
$Id: README.txt,v 1.1.1.1 2004/11/12 21:42:58 cvs Exp $
