documentation gap: named colors

[villares]

I think I found a documentation gap!

The fill(), stroke() and color() pages are awesome, but they don't mention passing a string like 'blue' as an option.

I remember something about having matplotlib installed, it would let you use its color names, I do have matplotlib, but I don't know if it is these are the only color names, if there is a basic name set without matplotlib?

I guess we need to document all of this, and maybe have a list of named colors (maybe with swaches?).

[hx2A]

I agree, this can be improved. I'll add something to the documentation for this.

In addition, I'd like to make an enhancement related to this. I can't remember more than 5 colors and I don't always feel like going to the matplotlib documentation to look them up. It would be better if the color names were in py5 somehow, and I could use code completion to get the list. Something like py5.mpl_colors.brown, etc, where py5.mpl_colors was a submodule or object with attributes mapping each color name to the color values. Getting this right would take some thinking (it should work correctly regardless of the color mode) but should be achievable.

[villares]

scale_factor = 1.78
line_height = 16

import py5
import matplotlib.colors as mcolors

named_palettes = (
    'CSS4_COLORS',
    'BASE_COLORS',
    'TABLEAU_COLORS',
    'XKCD_COLORS',
    )

def setup():
    py5.size(1024, 1024)
    svg = py5.create_graphics(int(py5.width * scale_factor),
                              int(py5.height * scale_factor),
                              py5.SVG, 'out.svg')
    py5.scale(1 / scale_factor) # smallor on screen than on SVG file
    py5.begin_record(svg)
    py5.background(255)
    py5.text_align(py5.LEFT, py5.CENTER)
    x = y = line_height / 2
    for name in named_palettes:
        palette_dict = getattr(mcolors, name)
        color_names = sorted(palette_dict, key=lambda c: tuple(mcolors.rgb_to_hsv(mcolors.to_rgb(c))))
        py5.fill(0)
        py5.text(name, x, y)
        y += line_height
        for color_name in color_names:
            hex_color_str = palette_dict[color_name]
            py5.fill(color_name)
            py5.rect(x, y, 40, 12)
            py5.fill(0)
            py5.text(color_name, x + 45, y + 6)
            y += line_height
            if y > py5.height * scale_factor - line_height:
                y = line_height / 2   # back to top
                x += 180                   # next collumn
        y += line_height # adds vertical space before next palette 

    py5.end_record() 
        
py5.run_sketch()

[hx2A]

Wow, this is seriously impressive! And you even sorted by palette group and color hue as well. That was a nice touch.

After this upcoming release I would like to expand py5's matplotlib features. These color palettes will be a part of that.

[hx2A]

Coming back to this...the matplotlib named colors support will be expanded as explained in this comment in 348. The feature should also be mentioned in the reference documentation for the methods that support it...there are ~48 of them, spread across multiple classes. In addition, there should be new method signatures added to those reference pages.

Adding the signatures will require some upgrades to py5's metaprogramming code. I did some investigation and I see (this is really notes for myself for when I actually do the work) the correct way to do this is to add it to method_data returned by javap in CodeBuilder. The structure of that data looks like this:

In [21]: method_data['fill']
Out[21]:
{'int': {'static': False, 'rettype': 'void', 'paramnames': ['rgb']},
 'int,float': {'static': False,
  'rettype': 'void',
  'paramnames': ['rgb', 'alpha']},
 'float': {'static': False, 'rettype': 'void', 'paramnames': ['gray']},
 'float,float': {'static': False,
  'rettype': 'void',
  'paramnames': ['gray', 'alpha']},
 'float,float,float': {'static': False,
  'rettype': 'void',
  'paramnames': ['v1', 'v2', 'v3']},
 'float,float,float,float': {'static': False,
  'rettype': 'void',
  'paramnames': ['v1', 'v2', 'v3', 'alpha']}}

In [22]: method_data['fill'].keys()
Out[22]: dict_keys(['int', 'int,float', 'float', 'float,float', 'float,float,float', 'float,float,float,float'])

In [23]: method_data['fill']['int']
Out[23]: {'static': False, 'rettype': 'void', 'paramnames': ['rgb']}

Adding it to EXTRA_METHOD_SIGNATURES in reference.py would also get the new signatures into the reference documentation but would not add the signatures in a way that VSCode would pick up on.

In addition, I was thinking of adding a new "Integrations" section to the py5coding website to highlight the matplotlib and colour library support as well as the upcoming shapely and trimesh features.

[villares]

More documentation notes from #348 (comment):

Note availability of CMAP, or a link to somewhere explaining it, at the Sketch.color_mode(), Py5Graphics.color_mode() and Py5Shape.color_mode() documentation pages!

[hx2A]

Note availability of CMAP, or a link to somewhere explaining it, at the Sketch.color_mode(), Py5Graphics.color_mode() and Py5Shape.color_mode() documentation pages!

Yes! Although the CMAP feature will only work for Sketch.color_mode(), not the other two. This will be in the reference documentation and there will be separate page that outlines all of the color-related integrations (colour library, hex codes, color maps, etc).

[villares]

Yeah, by explaining/documenting availability I meant telling about where it is available or not available 🤣

[hx2A]

So I now have COVID and rather than sulk I am distracting myself by finishing up the py5 documentation changes for the next release.

The updated documentation has been pushed to the dev website. There are now links to the "All About Colors" Tutorial on all of the methods that have the extra functionality. For example:

http://dev.py5coding.org/reference/sketch_fill.html

[villares]

Thanks for all the wonderfully colorful improvements on py5! Merry Christmas, @hx2A!

Man, COVID sucks, I hope it doesn't bring you any further trouble.

I'm going to post the "sampler" code on discussions so that it remains more accessible...

[hx2A]

Thanks for all the wonderfully colorful improvements on py5! Merry Christmas, @hx2A!

You are welcome, @villares ! Merry Christmas to you as well.

Man, COVID sucks, I hope it doesn't bring you any further trouble.

The first 12 hours were horrible but I am not suffering now. It seems the worst is behind me.

I'm going to post the "sampler" code on discussions so that it remains more accessible...

Good idea! That should not get lost.