Add rolling ball algorithm for background substraction

[FirefoxMetzger]

Description

Adds an example to implement the rolling ball algorithm.
Relevant Issue: #3538
Relevant Paper: Biomedical Image Processing

For reviewers

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  doc/release/release_dev.rst.

[pep8speaks]

Hello @FirefoxMetzger! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file benchmarks/benchmark_restoration.py:

Line 123:80: E501 line too long (88 > 79 characters)

Comment last updated at 2020-10-30 09:03:58 UTC

[mkcor]

Also, you probably want "To implement this algorithm in skimage we can use the following:" to appear afterwards.

@FirefoxMetzger drawing your attention to the above review comment, you might have missed it in the midst of the rest ;)

[FirefoxMetzger]

@mkcor Is there a tutorial/documentation on how to run the tests locally? That way, I can at least make sure they all pass before pushing commits

[mkcor]

@mkcor Is there a tutorial/documentation on how to run the tests locally? That way, I can at least make sure they all pass before pushing commits

Sure! In the contribution guidelines, you can find a section on testing: https://scikit-image.org/docs/stable/contribute.html#testing
But, as I was hinting, this PR is primarily concerned with the docs: https://scikit-image.org/docs/stable/contribute.html#building-docs Build the docs, as documented, with make html (it will spit out errors and warnings if any). Then, in your case, open local file scikit-image/doc/build/html/auto_examples/segmentation/plot_rolling_ball.html in your web browser. Hope that helps!

[stefanv]

Note that the float input case is quite common, so we will need to figure out how to handle this. We can: only support in images (error otherwise), or convert float to it images, or figure out a float-specific version.

[sciunto]

Note that the float input case is quite common, so we will need to figure out how to handle this. We can: only support in images (error otherwise), or convert float to it images, or figure out a float-specific version.

We can start with the first option, which lets the possibility for improvements.

[FirefoxMetzger]

I'm back from my vacation.

@jni I've updated the function as you suggested. I moved the code to skimage.restoration and merged rolling_ball and rolling_ellipsoid into rolling_ball with the signature discussed above. I also created helper functions for ball_kernel and ellipsoid_kernel to keep existing functionality. I didn't update the gallery example yet, but the tests and benchmarks are up to date.

I noticed that 0.18 is still not released. Does this mean this PR will be on ice until release?

[FirefoxMetzger]

@stefanv Is there any ETA or timeline on how we want to proceed with this feature?

I still think it's quite the cool feature, and it would be a real shame to not get it added.

[stefanv]

@jni Can we get this in for the next release still?

[jni]

Yes, @stefanv if you can comment on the API choices we can get it in. We were holding off so we could have time to discuss the API at length.

[rfezzani]

Thank you again @FirefoxMetzger , just left a couple of suggestions 😉

[jni]

Actually I realise that currently the API matches my preference (@emmanuelle and @mkcor in the meeting agree that it's fine to think of a general ball 😂) so I'm happy to merge as-is. =) Note that if #4951 merges before this, the test using cells.tif will need to be updated, and vice versa.

@FirefoxMetzger as always, thank you so much for all your hard work and for your patience!!! 🙏 🙏 🙏 🙏

[mkcor]

Actually I realise that currently the API matches my preference (@emmanuelle and @mkcor in the meeting agree that it's fine to think of a general ball 😂

@jni generalized ball 😇

[FirefoxMetzger]

Thanks, @rfezzani ! you have a really good eye for details. Your suggestions and reviews are always appreciated.

Thanks, @jni for the praise. I will check #4951 and see what needs to be changed here.

When reading the code again, I noticed two improvements (refactoring for consistency) that can be made to the docstrings of rolling_ball and rolling_ball_cy. I will add them and then re-read all the docstrings to see if they make sense

[jni]

Oops:

Suggested change

	path = data.image_fetcher.fetch('data/cells.tif')
	image = io.imread(path)[:5, ...]
	image = data.cells3d()[:5, 1, :, :]

I'll get this right eventually but I think you get the point, I'll go back in my hole now 😂

[rfezzani]

Thank you @FirefoxMetzger, once CI is green and you feel that it's fine, we are ready to go 😉

[FirefoxMetzger]

I finished the changes to the docstrings.

I merged the changes from master (to enable cells3d) and this broke the testing pipeline on my end (pytest doesn't find any tests when called with pytest path\to\test_rolling_ball.py). Tests seem to be working fine in CI though ... could be a Windows/Linux thing or outdated packages on my end; still investigating.

[FirefoxMetzger]

@rfezzani Would you mind having a look at the Travis CI errors for Mac and telling me if you can make any sense of it? The issue seems to be that the script can't find a python3.7 executable (it should be python3 if I read the logs correctly), and then crashes. I didn't modify any CI code, so I'm doubtful if this PR is the cause. Is there any known issue with the CI for Mac?

If it's not an issue that needs fixing in this PR, I'm happy with the current version. Otherwise, I could do with a pointer to tell me where to look for the issue.

[rfezzani]

This PR is not the only affected 🙁. Travis CI is unfortunately causing a lot of trouble 😭..

[jni]

Boom. Many thanks @FirefoxMetzger! 🎉

pytest doesn't find any tests when called with pytest path\to\test_rolling_ball.py

This is crazy! It's the same with me! It's not this PR, this is the case in master. Bizarrely, pytest skimage/filters/tests/test_thresholding.py finds one test: only the setup:

 $ pytest skimage/filters/tests/test_thresholding.py -v
================================= test session starts =================================
platform linux -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1 -- /home/jni/miniconda3/envs/all/bin/python
cachedir: .pytest_cache
PySide2 5.14.2.1 -- Qt runtime 5.14.2 -- Qt compiled 5.14.2
rootdir: /home/jni/projects/scikit-image, inifile: setup.cfg
plugins: timeout-1.3.4, napari-plugin-engine-0.1.6, ome-zarr-0.0.14, httpserver-0.3.4, ordering-0.6, qt-3.3.0, cov-2.8.1
collected 1 item                                                                      

skimage/filters/tests/test_thresholding.py::TestSimpleImage::setup PASSED       [100%]

================================== 1 passed in 0.26s ==================================

I'll make an issue!

[FirefoxMetzger]

🚀 💯

[stefanv]

Beautifully done. Thank you @FirefoxMetzger and reviewers!

[imagesc-bot]

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/background-subtraction-in-scikit-image/39118/7