gensei (generate serial images)
===============================

The script volume_slicer.py generates images corresponding to slices of a block
specimen filled with ellipsoids. The ellipsoids have known properties such as
the volume fraction within the block, dimensions (semiaxes a, b, c), volumes of
individual ellipsoids, a length-to-width ratio and number.

Although some basic parameters can be set using the command line options, it is
preferable to describe the objects and generation rules in an input file - see
'examples/basic.py', where four classes of objects are defined, and each
configuration item is described.

Its purpose is to verify results, obtained by various software for
reconstructing 3D data (e.g. a living tissue microstructure) given a set of 2D
slices using usually stereological methods, on a dataset with well-defined and
known properties.

The file <slice_info.txt>, which is saved together with the generated images,
contains a detailed report on the generated images. Should the properties of
generated objects images differ from the original settings, the original
parameters are listed in round brackets.

The true volume of the ellipsoids is calculated analytically as (4/3)(pi)abc,
where a, b, c are the semiaxes of the ellipsoid that are known.

The volume based on sections is estimated using the Cavalieri principle (see,
for example, [ref1], [ref2]), i.e. the sum of areas of
the profiles of an object is multiplicated by the thickness of the sections.

The surface of the ellipsoids is calculated according to the approximate Knud
Thomsen's formula [ref3], which yields a relative error of at most 1.061%.

The surface based on sections is another approximative method, which tries to
simulate the results of a three-dimensional reconstruction of the sections. The
surface based on sections is calculated as the sum of circumferences of the
profiles of an object multiplicated by the thickness of the sections.
WARNING: In the current version, the circumference computation is very crude!

License: New BSD License, see the LICENSE file.

[ref1] Howard, C. V. and Reed, M. G. (1998). Unbiased Stereology: Three
       Dimensional Measurement in Microscopy. Royal Microscopical Society,
       Microscopy Handbook Series No.  41. Springer, New York.
[ref2] http://en.wikipedia.org/wiki/Cavalieri's_principle
[ref3] http://en.wikipedia.org/wiki/Ellipsoid#Surface_area

Dependencies:
-------------

numpy [1], scipy [1], matplotlib [2]

Those packages should be in your favourite Linux distribution. On Windows,
installing EPD [3] should get you running.

[1] http://scipy.org
[2] http://matplotlib.sourceforge.net
[3] http://www.enthought.com/products/epd.php

Installation:
-------------

1. Download either the latest release or a development snapshot from [4].
2. Unpack the archive, go to the directory with volume_slicer.py script.
3. Optionally, install gensei by

   python setup.py install # system-wide
   python setup.py install --root=<user directory> # local installation


[4] http://code.google.com/p/gensei/

Command Line Usage:
-------------------

Go to the source directory with volume_slicer.py script and try:

- Linux (POSIX systems):
  - print help:
    $ ./volume_slicer.py -h
  - run with default settings:
    $ ./volume_slicer.py
  - run example:
    $ ./volume_slicer.py examples/basic.py
  - run example, override some settings:
    $ ./volume_slicer.py examples/basic.py --resolution=100x100 --n-object=20 

- Windows (cmd):
  - print help:
    python volume_slicer.py -h
  - run with default settings:
    python volume_slicer.py
  - for other usage, see above (Linux), just replace "./volume_slicer.py" by
    "python volume_slicer.py"

The script can be run also inside ipython using the %run command.

--
Robert Cimrman