Closed kimikage closed 3 years ago
This would be fantastic
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?
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.
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.
16x16 PNGs version (ImageMagick-free)
They’re very pretty! But how big are they going to be, and can I use them on my iPad tablet?
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.
I'm thinking about accessibility... I think they should be larger. ¯\(ツ)/¯
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~
I didn’t change anything- my phone is playing up with rain on the screen. 💦💦💦
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.
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.
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.😀
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 😅)
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).
safari works as well (and you're such a perfectionist!)
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.
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. https://github.com/JuliaGraphics/ColorTypes.jl/issues/10).
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
We probably should. I'm not sure Documenter initially offered such good support for behind-the-scenes code evaluation as it does now.
Most of Luxor's docs' graphics are generated when the docs are built. Never done it for anything else, though.
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:)
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.
These are very cool! They could - dare I say again - do with being a little larger - they're quite cramped to my eyes.
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.
Do the differing sizes of the circles mean anything? Perhaps they don't need to scale...
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".
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. 😀
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:
Perhaps an explanatory note would be sufficient then.
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?
It's beginner friendly though! :)
I will add the captions.
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:
Oh dear, are there images in TestImages where we should be concerned about copyright? I thought we had been pretty careful about that.
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
.
BTW, Julia v1.0 is no longer used for the document generation, so we can use PNGFiles.jl.
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.
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!
Oh, shoot, I thought this was a PR. But sure, fine to close it. And indeed they have improved!
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
]add Colors
(PR #406)Construction and Conversion (<-- Colorspaces)
Available colorspaces
:new: Constructors
RGB
,RGB{Float64}
,RGBA
,ARGB32
)Normed
:new: Generating random colors
RGB24
colors without replacementColor parsing
hex
(PR #406)Color conversion
alpha
,wp
):new: Displaying colors
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
sequential_palette()
/diverging_palette
Generating distinguishable colors
distinguishable_colors()
seed
PyPlot
example withdropseed
(PR #415)Named Colors
Advanced Functions (<-- Colorspaces)
Color matching (CIE Standard Observer)
Chromatic adaptation (white balance)
Simulation of color deficiency ("color blindness")
Most saturated color (<-- Colorscales)
References
Migrating from Color.jl (--> null)