Documentation for color images in histogram matching

[Borda]

Description

cleaning unused variables and adding a note about using different colour space than RGB

Checklist

• Clean style in the spirit of PEP8

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.
• Consider backporting the PR with @meeseeksdev backport to v0.14.x

[pep8speaks]

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

• In the file skimage/transform/histogram_matching.py:

Line 27:80: E501 line too long (80 > 79 characters)
Line 57:80: E501 line too long (81 > 79 characters)
Line 71:80: E501 line too long (82 > 79 characters)

Comment last updated at 2019-04-27 14:59:53 UTC

[hmaarrfk]

sigh, sphinx broke things for you.....

[Borda]

@hmaarrfk I know, but it came from the actual master... :-/

[hmaarrfk]

I don't really understand what you are trying to say:

Using RGB image, assume converting input image to some "continuous" color space [2]_.

Can you explain in more words

[Borda]

@hmaarrfk can you look at the updated version?

[sciunto]

I would prefer to see a paper rather than a researchgate thread.

[Borda]

I have not found any paper about it yet, but see the following example

[Borda]

I found a similar topic here - mapbox/rio-hist#3

[sciunto]

If you add the example, you can remove this link. The example will speak by itself.

[Borda]

@sciunto just to clarify, skimage does not support python 2.7 any more, right?

[jni]

@Borda that is correct, you don't need to worry about Py2.7 support and can use syntax for Py3.5+, including the matmul symbol, @.

[hmaarrfk]

the wording still isn't quite right:

assume to use another colour space

ins't entirely grammatically correct.

You should say something more like:

If multichannel is set to True, images are analyzed on a per channel basis.

This is a fact.

Results for images stored in RGB color space may not behave as expected since transitions are not always smooth in each channel.

General statement that encourages more thought.

Finally, if you want to make this really awesome, I would encourage you to make an example with the images you used in the comment.

[Borda]

@hmaarrfk example sounds reasonable, but would I include the image in this repo or download it online when needed? is there any guidence on how to create an example with new/own images?

[hmaarrfk]

I think the first PR would be to add the image(s) to the dataset of images shipped with scikit-image.

That PR would include:

1. A license for the image compatible with scikit-image. see discussion about this here: Missing scientific (domain-specific) images and corresponding examples and tutorials #3384
2. Adding them to the data directory
   https://github.com/scikit-image/scikit-image/blob/master/skimage/data/__init__.py
3. Ensure it shows up on the gallery (I forget how to do this at the moment).

It seems like you would include two images, the reference, and the source.
Generally here the challenge is to ensure we have the right license for the images.

Not sure how you got that data, but it seems that even lower res images might work to make your point, but high res images would be fine too. I'll push to include your full images.

After you get the data in scikit-image, we can have a more focused discussion on how to improve the example and whatnot.

[Borda]

I need to check the condition of sharing first and try to remember who is the source...

[stefanv]

Hey, @Borda, thank you for helping us clarify the documentation; that's always valuable.

I am struggling to understand the new text. Why do you say HSV is "continuous", and RGB is not? I can help wordsmith this a bit, but I don't have a good understanding of the issue at hand.

[stefanv]

Woops, I think all the futzing with this led to incorrect indentation.

[Borda]

it seems that with setting multichannel=True the change is not so drastically...
https://github.com/Borda/BIRL/raw/devel/figures/Rat-Kidney_histogram-matching.jpg

[hmaarrfk]

Can you add the full code?

[Borda]

import os
import matplotlib.pyplot as plt
from skimage.io import imread
from skimage.transform import match_histograms
from skimage.color import rgb2hsv, hsv2rgb, rgb2lab, lab2rgb, lab2lch, lch2lab

rgb2lch = lambda im: rgb2lab(lab2lch(im))
lch2rgb = lambda im: lab2rgb(lch2lab(im))

path_imgs = 'https://raw.githubusercontent.com/Borda/BIRL/master/data_images/rat-kidney_/scale-5pc/'
path_img_ref = path_imgs + 'Rat-Kidney_HE.jpg'
path_img_move = path_imgs + 'Rat-Kidney_PanCytokeratin.jpg'

os.system('wget %s' % path_img_ref)
os.system('wget %s' % path_img_move)

img_ref = imread(os.path.basename(path_img_ref))
img_move = imread(os.path.basename(path_img_move))
use_multichannel = True

fig, axarr = plt.subplots(ncols=3, nrows=2, figsize=(12, 6))
axarr[0, 1].set_title('Reference')
axarr[0, 1].imshow(img_ref)
axarr[0, 0].set_title('Source')
axarr[0, 0].imshow(img_move)

axarr[0, 2].set_title('Hist. matching using RGB')
axarr[0, 2].imshow(match_histograms(img_move, img_ref, multichannel=use_multichannel))
axarr[1, 0].set_title('Hist. matching using HSV')
axarr[1, 0].imshow(hsv2rgb(match_histograms(rgb2hsv(img_move), rgb2hsv(img_ref), multichannel=use_multichannel)))
axarr[1, 1].set_title('Hist. matching using LAB')
axarr[1, 1].imshow(lab2rgb(match_histograms(rgb2lab(img_move), rgb2lab(img_ref), multichannel=use_multichannel)))
axarr[1, 2].set_title('Hist. matching using LCH')
axarr[1, 2].imshow(lch2rgb(match_histograms(rgb2lch(img_move), rgb2lch(img_ref), multichannel=use_multichannel)))

[Borda]

@hmaarrfk do you think that it should/could be included or drop this PR?

[hmaarrfk]

maybe you should rephrase your conclusion, and tell users to use multichannel=True for RGB images?

[Borda]

@hmaarrfk Sure and in the doc of the function match_histograms or still add an example?

[Borda]

@hmaarrfk ^^

[hmaarrfk]

If you can add that to the docs, then just adding it there is fine. Otherwise, this should be a separate example. The documentation will find the example automatically I think

[hmaarrfk]

I think showing it in an email example gallery will go a long way to helping others. Especially with syntax