search

JuliaGraphics / Colors.jl

Color manipulation utilities for Julia
Other
202 stars 47 forks source link

Improvement of documents (phase 1) #398

Closed kimikage closed 3 years ago

kimikage commented 4 years ago

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

Construction and Conversion (<-- Colorspaces)

Available colorspaces

Color Differences (<-- Colorspaces)

Colormaps and Colorscales (<-- Colormaps, Colorscales)

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

Colormaps

Predefined sequential and diverging colormaps

Sequential and diverging color palettes

Generating distinguishable colors

Named Colors

Advanced Functions (<-- Colorspaces)

Color matching (CIE Standard Observer)

Chromatic adaptation (white balance)

References

Migrating from Color.jl (--> null)

timholy commented 4 years ago

This would be fantastic

cormullion commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

SVG + CSS (w/o script) :stuck_out_tongue_closed_eyes: 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 commented 4 years ago

16x16 PNGs version (ImageMagick-free) colorspaces

cormullion commented 4 years ago

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

kimikage commented 4 years ago

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 commented 4 years ago

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

kimikage commented 4 years ago

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. :smile: 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 commented 4 years ago

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

timholy commented 4 years ago

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.

cormullion commented 4 years ago

On my phone

kimikage commented 4 years ago

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. :sweat_smile:

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

cormullion commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

IE11 and Edge are supported now. ie11

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 commented 4 years ago

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

timholy commented 4 years ago

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

To clarify, what I was pointing out that the version in https://github.com/JuliaGraphics/Colors.jl/issues/398#issuecomment-588270497 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 commented 4 years ago

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 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. https://github.com/JuliaGraphics/ColorTypes.jl/issues/10).

kimikage commented 4 years ago

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) :smile:

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

timholy commented 4 years ago

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

cormullion commented 4 years ago

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

kimikage commented 4 years ago

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. colordiff ("Summay"....:sweat:)

kimikage commented 4 years ago

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 commented 4 years ago

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

kimikage commented 4 years ago

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. colordiff2

cormullion commented 4 years ago

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

kimikage commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

Perhaps an explanatory note would be sufficient then.

kimikage commented 4 years ago

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 commented 4 years ago

It's beginner friendly though! :)

kimikage commented 4 years ago

I will add the captions. dificiency

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

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. :smile:

timholy commented 4 years ago

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

kimikage commented 4 years ago

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)

peppers 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 commented 3 years ago

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

timholy commented 3 years ago

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 commented 3 years ago

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. :tada:

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 commented 3 years ago

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