<commit_before># ray: segmentation of nD images

Ray is a python library for performance and evaluation of image segmentation.  
It supports n-dimensional images (images, volumes, videos, videos of 
volumes...) and multiple channels per image.

## Requirements (tested versions)

* Python 2.x (2.6, 2.7)
* numpy (1.5.1, 1.6.0)
* Image (a.k.a. Python Imaging Library or PIL) (1.3.1)
* networkx (1.4, 1.5)
* h5py (1.5.0)
* scipy (0.7.0, 0.9.0)
* scikits.learn (0.7.1, 0.8)

All of the above are included in the Enthought Python Distribution, so I would
recommend you just install that if you can.

### Recommended

* progressbar 2.3-dev
* [vigra/vigranumpy](hci.iwr.uni-heidelberg.de/vigra/) (1.7.1)

progressbar is in PyPi and trivial to install:

```
sudo easy_install progressbar
```

For vigra, you are on your own. It is used for the random forest classifier,
but if you don't install it you can still use SVM or AdaBoost classifiers.

## Installation

Well, there's nothing to install per se (distutils support coming at some point
in the far future). Download the source and add whatever path you downloaded it
to to your Python path.
<commit_msg>Improve documentation with use cases.<commit_after># ray: segmentation of nD images

Ray is a python library for performance and evaluation of image segmentation.  
It supports n-dimensional images (images, volumes, videos, videos of 
volumes...) and multiple channels per image.

## Requirements (tested versions)

* Python 2.x (2.6, 2.7)
* numpy (1.5.1, 1.6.0)
* Image (a.k.a. Python Imaging Library or PIL) (1.3.1)
* networkx (1.4, 1.5)
* h5py (1.5.0)
* scipy (0.7.0, 0.9.0)

All of the above are included in the Enthought Python Distribution, so I would
recommend you just install that if you can.

### Recommended

* progressbar 2.3-dev
* [vigra/vigranumpy](hci.iwr.uni-heidelberg.de/vigra/) (1.7.1)
* scikits.learn (0.7.1, 0.8)

progressbar is in PyPi and trivial to install:

```
sudo easy_install progressbar
```

For vigra, you are on your own. It is used for the random forest classifier,
but if you don't install it you can still use SVM or AdaBoost classifiers.

## Installation

Well, there's nothing to install per se (distutils support coming at some point
in the far future). Download the source and add whatever path you downloaded it
to to your Python path.

## Usage

### Mean agglomeration

Suppose you have already trained a pixel level boundary detector, and want to
perform mean agglomeration on it. This is the simplest form of agglomeration
and was the initial design spec for Ray. Now:

```
from ray import imio, agglo, morpho
prob = imio.read_image_stack('probabilities-*.png') # prob is a numpy ndarray
# can be one file for 2D segmentation, or many files for 3D.
label_field = morpho.watershed(prob) # warning: slow
g = agglo.Rag(label_field, prob) # the region adjacency graph
threshold = 0.5
g.agglomerate(threshold) # agglomerate until the boundary mean is 0.5
seg = g.get_segmentation() # the label field resulting from the agglomeration
g.agglomerate(inf) # agglomerate to completion
ucm = g.get_ucm() # get the ultrametric contour map (UCM) for the segmentation
```

A UCM can be thresholded to provide the segmentation at any threshold of 
agglomeration. It may, however, result in a split when a segment becomes
thinner than one pixel.

{'fraction_non_alphanumeric': 0.09082706766917294, 'fraction_numerical': 0.024661654135338346, 'mean_word_length': 4.085626911314985, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2667705', 'n_tokens_mistral': 1126, 'n_tokens_neox': 1049, 'n_words': 464}