Improvement of documents (phase 1)

[kimikage]

The current documentation is categorized by technical field, so it is difficult for beginners to understand. For example, beginners will first read the Colorspaces page. However the page contains documents which most beginners do not need, such as CMFs.

Of course, adding a tutorial page is a good idea. However, I think there is still room for improvement.

The following is my plan.

Introduction

• Simplify the supported colorspaces (PR Add cross-sectional charts and some examples to docs #406)
  • They are also in the "Colorspaces" page.
• Add the installation instructions, i.e. ]add Colors (PR Add cross-sectional charts and some examples to docs #406)
• Add notes for "reexport" (PR Add cross-sectional charts and some examples to docs #406)

Construction and Conversion (<-- Colorspaces)

Available colorspaces

• Add inline figures showing the examples of 2-D cross sections (PR Add cross-sectional charts and some examples to docs #406)

🆕 Constructors

• Add examples of constructors (e.g. RGB, RGB{Float64}, RGBA, ARGB32)
  • The constructors are implemented in ColorTypes.jl, so only examples are given there.
• Add notes for Normed

🆕 Generating random colors

• Add notes for non-RGB colors
• Add examples for sampling RGB24 colors without replacement
  • cf. issue [unimportant] Using sample with RGB #434

Color parsing

• Add the explicit reference to hex (PR Add cross-sectional charts and some examples to docs #406)
• Add the link to "Named Colors" (PR Add cross-sectional charts and some examples to docs #406)

Color conversion

• Add examples with the extra arguments (e.g. alpha, wp)

🆕 Displaying colors

• Add the document about color swatches

Color Differences (<-- Colorspaces)

• Use docstrings (PR Add charts for colordiff to docs and Use docstrings for metrics #409)
• Add some graphical examples (PR Add charts for colordiff to docs and Use docstrings for metrics #409)

Colormaps and Colorscales (<-- Colormaps, Colorscales)

Color interpolation (<-- Generating a range of colors, Weighted color means)

• Add notes for the vector space and the reference to ColorVectorSpace.jl
• Add examples for non-RGB color types. (PR Add normalize_hue and Enhance hue handling in range #405)

Colormaps

Predefined sequential and diverging colormaps

Sequential and diverging color palettes

• Move the details to the docstrings of sequential_palette()/diverging_palette
• Add inline example figures (PR Update documentation for colormaps #515)

Generating distinguishable colors

• Move the details to the docstring of distinguishable_colors()
• Add inline example swatches
• Add figures to explain the seed
• Update the PyPlot example with dropseed (PR Update PyPlot example #415)
  • It looks like the sample numbers are different between the actual plot and the script.

Named Colors

• Move the instructions and code examples to "Construction and Conversion" (PR Add cross-sectional charts and some examples to docs #406)

Advanced Functions (<-- Colorspaces)

Color matching (CIE Standard Observer)

Chromatic adaptation (white balance)

• Add the note for problem with whitepoint handling
• Add notes about CAMs and CATs

Simulation of color deficiency ("color blindness")

• Add inline figures showing the examples (PR Add example images of simulation of color deficiency #413)

Most saturated color (<-- Colorscales)

• Move the MSC document from "Colorscales" to "Advanced Functions" (PR Re-categorize docs #404)

References

Migrating from Color.jl (--> null)

• Eliminate the Color.jl migration page (PR Re-categorize docs #404)

[timholy]

This would be fantastic

[cormullion]

Good stuff.

You might be able to get a few useful snippets from one of my earlier attempts at improving the documentation here. 😂 The current docs were more of a basic “move it to Documenter format”.

You intend to do this after version 1 is released, I suppose?

[kimikage]

You intend to do this after version 1 is released, I suppose?

Some of the above are linked to source code changes, so I think we should start right away. In order to keep the commit log clean and to make the review easier, it is better to merge some units of changes to the master branch. However, I don't think that the timing needs to be synchronized with the releases.

One thing to watch out for is content movement, i.e. problems with dead links.

[kimikage]

Add inline figures showing the examples of 2-D cross sections

SVG + CSS (w/o script) 😝
https://jsfiddle.net/ycmd890n/5/

By using PNGs (in base64) for the bitmaps instead of the <path>s, I think it will be a little lighter.

[kimikage]

16x16 PNGs version (ImageMagick-free)

[cormullion]

They’re very pretty! But how big are they going to be, and can I use them on my iPad tablet?

[kimikage]

cf. kimikage/Colors.jl/tree/docs_crosssection

But how big are they going to be, and can I use them on my iPad tablet?

Does the "big" mean their display sizes? It should be about 1 inch per chart. Since there are nine charts now, they may be annoying on smartphones. In terms of data size, it is about 20KB per chart.

I do not have an iPad, but on my smartphone it worked. However, mouse hovering is not available on touch devices. Also, dragging is not supported. You need to touch the color bar.

[cormullion]

I'm thinking about accessibility... I think they should be larger. ¯\(ツ)/¯

[kimikage]

Scaling is easy because they are just SVG images. I guess that "page-wise" zooming with your browser may also be available.
I accept feedbacks on accessibility. However, keep in mind that this is not a color tool but a manual. 😄
I am writing this as doctests. TBH, I first learned that Luv produces false colors in the low L region due to out-of-gamut problems.

Edit:
Here is a preview.
kimikage.github.io/build/constructionandconversion.html

[cormullion]

I didn’t change anything- my phone is playing up with rain on the screen. 💦💦💦

[timholy]

For the color panes, what about always plotting something closest to intensity in the "colorbar" to the right? I'm noting the difference in immediate subjective impression that Lab and Luv have vs. LCHab and LCHuv. If you switched the latter two to the format of the first two (putting L* in the colorbar and using the x/y plot for a/b and u/v respectively), I suspect it would make it easier to understand the similarities/differences.

[kimikage]

Thank you for the report, @cormullion. I checked it on Chrome, Firefox, IE11 and (old) Edge but not on Safari, because I do not have the devices on which Safari runs.(I have MBP Mid 2009, though.)

TBH, I noticed that it didn't work on IE11 and Edge, but I didn't care about that because that is the usual characteristic of IE and Edge. 😅

Interestingly, the screenshot is similar to the IE11's result. Probably a trivial problem with the <image> elements.

[cormullion]

It might be OK for the docs to not work perfectly on all platforms, I suppose.... if there was a message about it not working it would be less confusing... And docs should never be confusing.😀

[johnnychen94]

FYI, safari 13.0.5 on my MBP (macOS Catalina) looks the same as on that of @cormullion (This might be the first time I use safari this year 😅)

[kimikage]

IE11 and Edge are supported now.

I added the extra HSV, HSL and HSI. (I did not add the LCHab and LCHuv charts. The implementation of crosssection() is a bit tricky, but it is simple to use, so you can easily try it in a local environment.)

Personally, I prefer my original version (i.e. ”H" is the z axis).

[johnnychen94]

safari works as well (and you're such a perfectionist!)

[timholy]

Personally, I prefer my original version (i.e. ”H" is the z axis).

To clarify, what I was pointing out that the version in #398 (comment) might make someone say, "wow, LCHab and LCHuv are really different from Lab and Luv! Why did they give them such similar names?" I'm not particularly choosy about which axis gets assigned to the color bar vs the 2d slice, just suggesting that we make them consistent where possible.

But in the end, if you're doing the work, I think you should choose.

[kimikage]

I implicitly assume that the person who compare the characteristics of color spaces understands the relationship between Lab and LCHab. That allows the person to compare HSV with LCHab instead of Lab.

In fact, this inconsistency is due to the particularity of the cylindrical (cyclic) color spaces. In that respect LCHab and LCHuv are really different from Lab and Luv.
These are for color "type" comparisons rather than color spaces.

I'm not particularly choosy about which axis gets assigned to the color bar, too. I'll add the extra LCHab and LCHuv charts with L* color bar temporarily.

https://kimikage.github.io/build/constructionandconversion.html
Firefox

Edit:
Another option is to create a new page with more charts. For example, many users do not need DIN color charts, so I will not list them in "Available Colorspace". But the additional charts are useful for testing. I think the YCbCr chart must be conspicuous, because I believe that the range of YCbCr should be normalized (cf. JuliaGraphics/ColorTypes.jl#10).

[kimikage]

I added some examples for range.
This is really off-topic, but I like the dynamic figure generation when building documentation. Why don't JuliaImages use the dynamic generation? (https://juliaimages.org/latest/conversions_views/#Using-colorview-to-make-color-overlays-1) 😄

Edit: You’ve probably noticed, but I just meant that the b was broken in JuliaImages/juliaimages.github.io#29

[timholy]

We probably should. I'm not sure Documenter initially offered such good support for behind-the-scenes code evaluation as it does now.

[cormullion]

Most of Luxor's docs' graphics are generated when the docs are built. Never done it for anything else, though.

[kimikage]

I've planned to clean up differences.jl, but one of the problems is the lack of tests.
The following charts are not suggestive, but I think it might be slightly helpful for the regression test.

("Summay"....:sweat:)

[kimikage]

FYI, DE_CMC is not metric but quasimetric. So, we cannot draw the triangle with DE_CMC.

64.6 + 38.9 < 105

I think it's kind if we have any additional notes.

[cormullion]

These are very cool! They could - dare I say again - do with being a little larger - they're quite cramped to my eyes.

[kimikage]

The cross-sectional chart (PR #406) should not be too large due to the page layout. On the other hand, there are less limitations on the sizes of the charts for colordiff. I tried to make them larger.
Of course, they are compatible with the dark theme.

[cormullion]

Do the differing sizes of the circles mean anything? Perhaps they don't need to scale...

[kimikage]

This is a tautology, but the difference in size represents the differences of scale. Paradoxically, the circle sizes are different because I did not scale the circles.
Edit: FYI, the radii are all the same "20".

[cormullion]

I think the different radii confused me, because I thought them significant - but they’re really symbolic so should be the same. My 2 cents. 😀

[kimikage]

The difference in scale means the difference in the return value of colordiff, so the "visual" difference is important as the "tests". It is easy to unify the apparent size of the circles, but we lose one dimension of visual information.

The problem is that we feel the "largeness" of a circle mainly by its area rather than its radius, so the differences are over-emphasized. However, it is convenient for testing, even though it confuses general users.:sweat_smile:

[cormullion]

Perhaps an explanatory note would be sufficient then.

[kimikage]

The difference in the size of circles in the charts above represents the difference in the scale. The radii of the circles are all 20 in their scale units, so larger circles mean that the metric returns smaller values. Therefore, we should not compare the color differences between different metrics.

too tedious?

[cormullion]

It's beginner friendly though! :)

[kimikage]

I will add the captions.

I wanted an image, which fits satisfies all the following conditions:

• no problem with copyright
• colorful
• including green, red and brown

However, there is no such image in TestImages.jl.:sweat_smile:

If you want to use the beads image for other purposes, I'll upload its FHD version under CC0. 😄

[timholy]

Oh dear, are there images in TestImages where we should be concerned about copyright? I thought we had been pretty careful about that.

[kimikage]

I'm sorry if I may have been unclear.
I don't think that the images in TestImages.jl have "practically" copyright problems. (However, strictly speaking, some images (e.g. "Peppers") do not have the clear source or copyright status. cf. http://sipi.usc.edu/database/copyright.php)

I think the images in TestImages.jl are not suitable for the simulation of color deficiency in terms of color. Scanned images of printed materials (e.g. "Peppers", including green and red) do not have "natural" colors.

In fact, I'm not satisfied with the result of "Peppers".

protanopic.(testimage("peppers"), 0.8)

BTW, I am concerned that the red is too dark than other tools, although I don't know the "correct" result. Note that changing the color deficiency simulation functions may break the color schemes using distinguishable_colors.

[kimikage]

BTW, Julia v1.0 is no longer used for the document generation, so we can use PNGFiles.jl.

[timholy]

Just a general note, it's unclear to me and perhaps others whether you're waiting on something from reviewers. The PR title says "RFC" but there has indeed been a great deal of comment, almost all of which is favorable and none of which seems like a deal-breaker.

I know you have a lot of unchecked boxes above, so maybe you're just waiting until you finish everything. But a PR doesn't have to solve all problems if it solves some. Feel free to just merge pieces of this and post the rest as an issue.

[kimikage]

I'm going to close this once and for all since I can no longer spend as much time on this as I did when I first opened it.

There were valuable discussions, and I certainly think the documentation has improved. 🎉

However, I also think this has a little too much context to continue. I'd like to make it a little easier for everyone to update the documentation.

Thanks!

[timholy]

Oh, shoot, I thought this was a PR. But sure, fine to close it. And indeed they have improved!