Improvement of named color charts

[kimikage]

It has been on my mind for a while, but the order of colors in the named color charts is perceptually strange. For example, "hotpink4" is darker than "deeppink2".

Of course, I think it is not significant, too, because the charts are only quick-reference/pretty handouts.

Aside from that, I have a suggestion. What about embedding inline SVGs in the HTML document? Although the letters in the current charts are outlined, some browsers allow you to copy and search the embedded SVG texts. Some condensed fonts are available as web fonts.
When we embed the charts, the interactive code technique may be helpful.
https://juliadocs.github.io/Documenter.jl/dev/showcase/#Running-interactive-code-1
Although

This showcase page is included in Documenter version 0.24.0 and above

AFAIK, the technique is available on the stable version.

---

FYI, the cause of the strange order is incorrect scaling /255.

Colors.jl/docs/src/assets/figures/generate-named-color-charts.jl

Lines 3 to 8 in 43d93ff

	function compare_colors(color_a, color_b)
	# compare two colors, looking just at their LUV luminance values
	luv1 = convert(Luv, RGB(color_a[1]/255, color_a[2]/255, color_a[3]/255))
	luv2 = convert(Luv, RGB(color_b[1]/255, color_b[2]/255, color_b[3]/255))
	luv1.l > luv2.l
	end

Colors.jl/docs/src/assets/figures/generate-named-color-charts.jl

Lines 58 to 60 in 43d93ff

	sort!(vals, lt = (color1, color2) ->
	compare_colors(Colors.color_names[color1] ./ 255,
	Colors.color_names[color2] ./ 255))

[kimikage]

Experimentally I tried embedding the colormaps into document as SVGs using Documenter.jl v0.23.3.

"Blues" and "Purples" seem to have changed somewhere from ebaf8bf to v0.9.6. In order to find such changes, I think it is useful to generate figures dynamically.

However, embedding SVGs is not compatible with the table or list layout of Markdown. In the case of named color charts, it does not matter, though. Of course, it is also OK to embed dynamically generated figures with ![](path).

[kimikage]

I made some non-essential changes.

• Re-categorization
  • To omit unique, I removed the pre-categorized colors.
  • I considered the hue more important than the name, although the categorization is still based on the names.
    • If we add colors in the future, the k-means or SOM clustering may be more useful than the ad-hoc pattern matchings.
• Overlaid RGB values to save spaces
• RGB value separators (i.e. commas) to be suitable for the word selection
• Line breaks in long color names
• Web font (Google Fonts) instead of outlined font
• currentColor texts and no white background
  

I found some problems with embedding SVGs.

• Documenter.jl redirect the stdout and stderr streams to the results block when evaluating @example blocks.
  • Hiding source code, we cannot use @show and @warn.
• Documenter.jl catches the errors occurred in @example blocks, and shows warnings.
  • For the current documents, Documenter.jl warns "docstrings missing". So, we should fix them.
• IE9/10/11 have a problem with SVG scaling, which hinders the responsive layout.

[cormullion]

Good to see your enthusiasm - I was keen to add some kind of chart to the fledgling docs, but there’s obviously many ways to make them better, particularly if you have the spare time! Also, the theory of sorting colors is above my pay grade... 😂

[kimikage]

There are a few concerns about generating the charts dynamically. It is a tautology, but when the generation fails, the charts will be lost. In that case, the committer (e.g. someone who just adds named colors to the list) will need to fix the generation script. To do it, the committer will need to study Documenter.jl first and read the ad-hoc generation script. Of course, we can introduce a fallback mechanism. However, it will make the scripts more difficult to understand, since the document generation itself is done inside Documenter.jl.

My real aim is to add more doctests. Do you have any thoughts?

[cormullion]

I support your endeavours, of course! But, since these named colors aren't Julia-specific, and don't change very often, I don't see much benefit in spending time engineering sample charts. To be honest, they could even be removed altogether without adversely affecting the user base, who are rarely going to be away from a computer when doing work with colors (and the color swatches display well in Juno and Jupyter, etc...).

Perhaps being able to search for named colors from Julia would be an idea worth exploring:

julia> findcolor("pink")
      Name         Red     Green      Blue          
lightpink4       0.545     0.373     0.396          
 deeppink4       0.545     0.039     0.314          
lightpink1         1.0     0.682     0.725          
  hotpink4       0.545     0.227     0.384          
  deeppink         1.0     0.078     0.576          
     pink4       0.545     0.388     0.424          
lightpink2       0.933     0.635     0.678          
      pink         1.0     0.753     0.796          
     pink3       0.804     0.569      0.62          
 lightpink         1.0     0.714     0.757          
  hotpink1         1.0     0.431     0.706          
  hotpink2       0.933     0.416     0.655          
     pink1         1.0      0.71     0.773          
 deeppink3       0.804     0.063     0.463          
 deeppink1         1.0     0.078     0.576          
lightpink3       0.804     0.549     0.584          
     pink2       0.933     0.663     0.722          
  hotpink3       0.804     0.376     0.565          
   hotpink         1.0     0.412     0.706   
julia>

[kimikage]

I don't see much benefit in spending time engineering sample charts.

I agree, but if someone can remove the charts without any troubles or hesitation in the future, I also think we don't have to delete them now.
As I mentioned above, my real aim is to add more doctests. Although it is not easy to test the color charts formally, we can informally do visual check. Even if the color_names has not changed, the charts may change due to external factors. In fact, colormaps have changed in appearance, even though the preset parameters have not changed, and I have just changed them slightly (#350). I was worried about the strange order of swatches because it could be due to broken color conversion or parsing. I don't really care about the order itself. This issue may seem abrupt, but the issues I recently reported are loosely related. My modified chart generation script calls parse() and hex() on purpose.
Of course, I want to make changes that are beneficial not only to developers but also to users.

I think your findcolor is very good when used with data structures like NamedArray. However, I don't think it is really good to increase the package dependency just to realize this function or generate the color charts.
Of course, we can define some data structures for this in Colors.jl. In fact, my charts shown above are the objects of type NemedColorChart which I defined in /docs. I think it is also not good to define such an ad-hoc type in /src and export it.

Anyway, I'll send my current source codes as a WIP PR for a more thorough discussion.

[kimikage]

I'm sorry, but my recent interest has been fixed in FixedPointNumbers.
BTW, the new Documenter pages are nice! 👍

[timholy]

No worries, that's a good place for them. There are some interesting challenges with getting good performance and high accuracy, and I'm grateful for your attention to those matters!

[kimikage]

The charts were changed by #374. Let's discuss new APIs like findcolor separately.