Make it easy to browse example images

[cdeil]

It's very nice that scikit-image comes with example images in skimage.data

In my opinion the following two changes would make it easier to browse and use them:

• in the overview table and docstrings mention the shape and dtype. (closed via [MRG+1] Insert metadata in docstrings of images in skimage.data.* #2236)
• Show a thumbnail (maybe show full image in new tab on click?) either as a collection in a separate section on this page or a Gallery page or with each API entry.

[stefanv]

That's a splendid idea. This would be perfect as a GSoC warm-up project: @sharky93, @vighneshbirodkar

[vighneshbirodkar]

I gave this a shot. One way I can think of to do this is parse the docstrings in doc/source/conf.py and insert the dtype and shape of the array.

edit : You can also insert an html directive with image thumbnail and link it to a new tab

[cdeil]

doc/source/conf.py should only contain simple Sphinx config.

If you write a function to parse dtype and shape from the functions in skimage.data.__all__, I think it should go in skimage/data/__init__.py so that it's also available e.g. from the command line (e.g. as list_data() that has an option to print out the table optionally as rst instead of ascii) and not just the HTML sphinx docs.

I'm not familiar with the scikit-image docs build, but probably your code that generates the nice HTML docs should go in skimage/tools (if it's just a Python script) or skimage/ext (if you make it a Sphinx extension).

@vighneshbirodkar Thanks for doing this!

[vighneshbirodkar]

@cdeil
Where is list_data() defined ?

I'll probably put a script in doc/tools to enumerate the functions in skimage.data.__all__ and save the images and their smaller thumbnail in a folder.

And then a script in skimage/data/__init__.py can parse the docstrings. I can put the dtype and shape in the first line and an html markup for the thumbnail and image later in the docstring.

[cdeil]

I meant to implement something like skimage.data.list_data(), it currently doesn't exist.
I'm not sure if it's a good idea ... @stefanv will know.

[stefanv]

A person can already access the members of the data submodule, so I don't think there's a specific need to add a module to list them. What would be good is to add the shapes, which we can do by hand (there are only a few, and those values won't change).

What I think would be a good use of time is to add a Javascript gallery that shows all the example images (something like a side-scrolling "film strip" bar).

[soupault]

@stefanv Can we just add hyperlink to the docstrings (e.g. make some part of https://github.com/scikit-image/scikit-image/blob/master/skimage/data/__init__.py#L68-L73 a hyperlink to https://github.com/scikit-image/scikit-image/blob/master/skimage/data/astronaut.png), or would you prefer to pursue JavaScript solution?

[emmanuelle]

Part of this issue has been resolved by adding the shape of images to docstrings (#2236), but the gallery part didn't go through, maybe because solutions based on javascript were too complicated. Why not add a gallery example plotting all functions, like the code below? One problem which I can see is that we would require the image to take the whole width of the image, while gallery examples have small thumbnails.

import inspect
import numpy as np
import matplotlib.pyplot as plt
from skimage import data

datasets = data.__all__[2:] # remove load and data_dir
number = len(datasets)

functions = inspect.getmembers(data, inspect.isfunction)
functions = [_function for _function in functions if _function[0] in datasets]

fix, ax = plt.subplots(4, 5, figsize=(20, 25))
plt.gray()
ax_ravel = ax.ravel()

for i, axx in enumerate(ax_ravel[:number]):
    im = functions[i][1]()
    if functions[i][0] == 'lfw_subset':
        im = np.block([[im[0], im[1]], [im[2], im[3]]])
    if functions[i][0] == 'stereo_motorcycle':
        im = np.hstack((im[0], im[1]))
    axx.imshow(im)
    axx.set_title(functions[i][0])

for axx in ax_ravel:
    axx.axis('off')

plt.show()

[jni]

Nice code! =)

What will we do when we include a 3D image example? =)

[emmanuelle]

@jni well the code could be improved to be less of an ugly hack if needed. About 3D images, we'll see when we add mayavi as a doc dependency :-)

[jni]

@emmanuelle no I really like your uses of inspect! They have inspired me to use it more in my own work. It's so useful!

[soupault]

@jni Well, do you think it would be easier to plot 3D data using JavaScript? 🙂Same applies for >3D images (e.g. taken from satellite cameras).

There is one thing I don't like about the approach of plotting all the data in a dedicated gallery example - the gallery is already quite populated, and it'll be challenging for the users to locate such page.

Maybe we should introduce data section to it, and have few examples: one for all 2D images, one for 3D, one for xD, etc, and pin such section to the top?

[jni]

@soupault very good points. It could be its own page, linked from "data types and what they mean", for example, or "getting started" directly.

I think we are pretty lackadaisical about doc dependencies (vs core dependencies), so we could certainly use ipyvolume or bokeh or something else to render 3D images in a widget.

[soupault]

The requested functionality has been finalised in #3388, see http://scikit-image.org/docs/dev/auto_examples/index.html -> Data section.