Improve DistanceTransform usability

[hanslovsky]

@tischi recently contacted me about using DistanceTransform and had a few questions about it. After helping him out we compiled a short list of improvements that would make calling DistanceTransform easier:

• [x] Documentation should clearly state that Euclidian distance is actually squared Euclidian distance.
• [x] There should be convenience methods for binary distance transform (converting true to zero and false to positive infinity)
• [x] Information about distance transform from sampled functions should be added to each individual overload (not only in class doc) so callers can see it when they auto-complete in eclipse
• [x] add comment that weights in squared Euclidian transform are not being squared (while coordinates are), i.e. callers need to pass squared weights, e.g. to adjust for pixel anisotropy

[imagejan]

I agree these things are useful to know, I can probably improve my use case from KNIME where I currently default to the Ops implementation, but want to offer the ImgLib2 DistanceTransform as an option:

https://github.com/fmi-faim/fmi-ij2-plugins/blob/6bbd5c82dfb867f02b97291a6a94c8dc7961e1ac/src/main/java/ch/fmi/AnisotropicDistanceMap.java#L65-L85

@tischi what's your use case?

[tischi]

shouldn't it rather be: converting true to positive infinity and false to zero? (i.e. the other way around )

[tischi]

My use case is to perform a distance transform based watershed, where I want to be in control about the creation of the seed regions. That is why I need to compute the distance transform myself rather than using the one build into the ops watershed.

my code is here: https://github.com/tischi/imglib2-drosophila-registration/blob/master/src/main/java/de/embl/cba/drosophila/shavenbaby/ShavenBabyRegistration.java#L109

[imagejan]

@tischi but you're aware that you can use the DistanceTransform op (as I did in my example) and don't need to use a watershed op, right?

Of course, you're free to do it in pure ImgLib2, and I'd be glad to see this here improved as well.

[hanslovsky]

shouldn't it rather be: converting true to positive infinity and false to zero? (i.e. the other way around )

Have a look at the definition of the distance transform of sample functions:

D( p ) = min_q f(q) + d(p,q)

true describes a pixel of interest, e.g. "on boundary" or "within object", i.e. the distance should be zero at those places, which is true if true is converted to zero.

[tischi]

true describes a pixel of interest, e.g. "on boundary" or "within object", i.e. the distance should be zero at those places, which is true if true is converted to zero.

ok. makes sense!

[tischi]

but you're aware that you can use the DistanceTransform op (as I did in my example) and don't need to use a watershed op, right?

In fact, if I find an implementation both in ops and imglib2-algorithm, I find it hard to choose which one to use...are there guidelines or is it just a matter of taste?

[hanslovsky]

I don't think there is a general answer to that. I personally never use ops and some of the ops are wrappers around imglib2-algorithm but some of the ops do not have an imglib2-algorithm equivalent.

[imagejan]

Yes, ideally we'd have all the algorithm implementations in imglib2-algorithm, and all the ops making use of them - without any duplication. But with the added benefit of ops doing the type matching/conversion as needed, and possibly being pluggable with an improved implementation if there is one in the future.

[ctrueden]

ideally we'd have all the algorithm implementations in imglib2-algorithm, and all the ops making use of them - without any duplication.

I mostly agree with this. One issue though is dependencies—if an imagej-ops algorithm needs extra JAR files, are we going to make imglib2-algorithm also have all these dependencies? It should ideally be well-separated, with each class of algorithms with same dependencies living in a particular ImgLib2-side library. And then Ops can unify everything. Or we can have multiple ops libraries as well, each wrapping one of the imglib2-algorithm libraries. There is no perfect design, since people have different opinions about modularity vs. convenience.

[hanslovsky]

I addressed all the bullet points in the initial comment and will create a PR.