Add compact watershed and clean up existing watershed

[jni]

Cleaned up the watershed code, which had lots of legacy code buried in there. Then on that nice frame I hung the new compact watershed algorithm, which gives much nicer results even for puny values of compactness.

Checklist

• Clean style in the spirit of PEP8
• Docstrings for all functions
• Gallery example in ./doc/examples (new features only)
• Unit tests

Gallery example to follow... Update: it's here! See output below.

[jni]

[sciunto]

Nice results @jni !

A quick comment. How this example looks like with the compact watershed? http://scikit-image.org/docs/dev/auto_examples/segmentation/plot_watershed.html#sphx-glr-auto-examples-segmentation-plot-watershed-py

Also, is it necessary to make two different examples on watershed in the gallery instead of improving the existing one? I'm afraid that the multiplication of examples on same/similar functions will increase the entropy and the likelihood to find the right example.

[jni]

@sciunto compact watershed will do worse in the above example, unfortunately (it will cause the smaller object to "leak" into the bigger one). So I think it's best to leave it as a separate example...

[jni]

@scikit-image/core anyone up for reviewing this?

CC @LeeKamentsky @thouis @kevin-keraudren

[LeeKamentsky]

👍 from me, esp for the cleanup. A lot of that was long overdue. The compact watershed is optional which gives people the choice whether or not to use it and IMHO, it is a great idea, especially for blobby objects. Another possibility would be to sort by pixel intensity and then distance in the heap code, instead of conflating the pixel value as a combination of pixel intensity and distance, but as it stands, you have a dial to tweak to offset the weighting of distance in your segmentation rather than having a tiebreaker and pragmatically, that's probably better.

So, if you need my blessing, here it is and thanks for improving the code.

[ahojnnes]

Both what I am wondering while reading? Maybe change to "Both algorithms..."

[kevin-keraudren]

Since the compact watershed is very similar to SLIC, why not do some cross-referencing with the See also sections of the docstrings?
Also, you could add the compact watershed to the SuperPixel example: http://scikit-image.org/docs/dev/auto_examples/plot_segmentations.html

[jni]

@LeeKamentsky

So, if you need my blessing, here it is and thanks for improving the code.

Thanks! =D Actually the purpose of pinging you was more in case you wanted to incorporate it into CellProfiler (though I realise that's not your primary concern anymore).

@kevin-keraudren

I would also consider adding the geodesic watershed:

Capital idea! As I was writing it I had a feeling that it wouldn't be too much trouble computing the geodesic, but I didn't realise just how trivial it would be.

@ahojnnes thanks for the review, working on it! =)

[codecov-io]

Current coverage is 90.75% (diff: 84.50%)

Merging #2211 into master will increase coverage by 0.05%

@@             master      #2211   diff @@
==========================================
  Files           303        303          
  Lines         21849      21797    -52   
  Methods           0          0          
  Messages          0          0          
  Branches       2019       2002    -17   
==========================================
- Hits          19817      19782    -35   
+ Misses         1670       1657    -13   
+ Partials        362        358     -4   

Powered by Codecov. Last update c394264...d34f7ab

[jni]

@kevin-keraudren so I feel like I need an additional float accumulator for the geodesic, containing the distance travelled thus far. This can be reconstructed from the difference between the current element's value and the image value at that location — but only if euclidean compactness is turned off. (With it on, you still can do it, but it's just a mess.) I'm wondering whether I should leave this for another PR... Or maybe I'm just missing something?

[kevin-keraudren]

@jni In the case of the normal watershed, we initialise the seeds with elem.value = image[index] and new pixels are added to the heap with:

new_elem.value = image[index]
if compactness > 0:
    new_elem.value += (compactness *
                                     _euclid_dist(index, elem.source, strides))

In the case of the geodesic watershed, there is no need for another accumulator, instead we initialise the seeds with elem.value = 0 and we add new points to the heap with:

new_elem.value = elem.value + sqrt((gradient_cost*(image[index] - image[elem.index])**2 +
                                                           euclidean_cost * _euclid_dist(index, elem.index, strides)**2))

So it requires more code changes than I first suggested, and either we are in normal watershed/compact watershed mode, or we are in geodesic watershed mode, but we should not have compact-geodesic-watershed mode!

[jni]

@kevin-keraudren I think I'll leave the geodesic for another time then. I think it would actually make a lot of sense for multichannel images, too (instead of having to compute the gradient beforehand).

@ahojnnes @sciunto @soupault this is ready for another round of review, I think!

[ahojnnes]

A larger or smaller value? This is ambiguous to me...

[ahojnnes]

LGTM, apart from Travis...

[jni]

Build succeeds locally after latest (blind) fix... @stefanv @blink1073 any ideas on how to troubleshoot this Sphinx error?

Warning, treated as error:
<autosummary>:1: WARNING: citation not found: R314

[sciunto]

space after > sign?

[jni]

@sciunto, I've rebased on top of current master, which has a single-threaded sphinx build. No code has changed so I suggest merging if Travis is happy. =)

[jni]

I'll point out that Travis has passed (\o/) except for the Xcode bit which hasn't started (won't start?).

[sciunto]

OK, I restarted travis and now, it passes. I'm also +1, so I merge.

Thanks @jni It's a very nice piece of work.