Colors#

The cmap.Color type represents an individual color.

from cmap import Color

# argument can be any "ColorLike".  See rules below
red   = Color('red')
red2  = Color('#FF0000')
red3  = Color('rgb(255, 0, 0)')
red4  = Color('hsl(0, 100%, 50%)')
red5  = Color((255, 0, 0))
red6  = Color((1.0, 0.0, 0.0))
red7  = Color([1.0, 0.0, 0.0])
red8  = Color(np.array([1.0, 0.0, 0.0]))
red9  = Color(0xFF0000)
red10 = Color(16711680)

ColorLike objects#

The following objects can be interpreted as a color, and used as the first argument to the Color constructor; cmap refers to these objects collectively as "ColorLike".

Briefly, valid arguments are of type:

• str
• tuple[float | int, float | int, float | int]
• tuple[float | int, float | int, float | int, float]
• Sequence[int | float]
• numpy.ndarray
• None
• int
• cmap.Color
• pydantic_extra_types.color.Color
• colour.Color

In detail:

1. A string containing a color name. All CSS color names are supported, case is ignored along with spaces, underscores and dashes (see complete list below.)

   • 'red'
   • 'slategray'

2. A string containing a 3, 6, or 8-digit hexadecimal color code:

   • '#0F5' (RGB)
   • '#00FF55' (RRGGBB)
   • '#00FF55FF' (RRGGBBAA)

3. A string containing a valid css rgb(a) or hsl(a) color:

   • 'rgb(255, 0, 0)'
   • 'rgb(100%, 0%, 0%)'
   • 'rgba(255, 0, 0, 0.5)'
   • 'rgba(255, 0, 0)' (it's ok to use rgba without an alpha value)
   • 'rgba(100%, 0%, 0%, 0.5)'
   • 'hsl(180, 100%, 50%)'
   • 'hsla(180, 100%, 50%, 0.5)'
   • 'hsla(180, 100%, 50%)' (it's ok to use hsla without an alpha value)

4. A tuple containing 3 int values between 0-255 (for RGB), or 3 int values and a float alpha value from 0-1 (for RGBA). (Note: the alpha value is always a float between 0-1).

   • (0, 128, 255)
   • (0, 128, 255, 0.5)

5. A tuple containing 3 or 4 float values (see note on ambiguity below):

   • (0.0, 0.5, 1.0)
   • (0.0, 0.5, 1.0, 0.5)

   Ambiguities with tuples of 0 and 1

   While it's nice to support both the 8-bit and float inputs, there is ambiguity in the case of a tuple of integers containing only zeros and ones (e.g. (0, 0, 1)). The convention in cmap is to treat a tuple of all integers as 8-bit RGB values, and a tuple with any floats (excepting the 4th alpha value) as float RGB values, so

   • (0, 0, 1) == (0, 0, 1/255) == '#000001'
   • (0, 0, 1.) == (0, 0, 255) == '#0000FF'

   To avoid ambiguity, it's best to use float values.

   Overflow

   In all cases, numeric values are clipped to their valid range, so (0, 300, 0, 2.0) is equivalent to (0, 255, 0, 1.0), and (0.0, 1.5, 0.0, -0.5) is equivalent to (0.0, 1.0, 0.0, 0).

6. A numpy.ndarray with shape (3,) or (4,): where integer dtypes are interpreted as 8-bit color values (from 0-255) and float dtypes are interpreted as float color values (from 0-1). For colors with alpha, you must use a float dtype.

   • np.array([0, 128, 255]) (8-bit RGB)
   • np.array([0.0, 0.5, 1.0]) (float RGB)
   • np.array([0.0, 0.5, 1.0, 0.5]) (float RGBA)
   • NOT: np.array([0, 128, 255, 0.5]) (the 0.5 makes this evaluated as a float color, which will be clipped to (0, 1., 1., 0.5))

7. The literal None, interpreted as transparent black (i.e. (0, 0, 0, 0))

8. A single integer value: interpreted as a 24-bit integer RGB color value, where the first 8 bits are the red channel, the next 8 bits are the green channel, the last 8 bits are the blue channel (alpha values other than 1 aren't supported in this mode). This is most convenient when expressing integers in base-16.

   • 0xFF0000 (red, in base 16 integer form)
   • 16711680 (also red, but in the default base 10 integer form)
   • 0xFF00FF (magenta, in base 16 integer form)
   • 16711935 (also magenta, but in the default base 10 integer form)

   Note

   Base-16 integers look the same as their hexadecimal color string representation, but lack the quotes, and are preceded by 0x instead of #.

9. An instance of cmap.Color itself: which is returned unchanged

   • Color(Color('red')) is Color('red')

10. (Third-party object): An instance of pydantic_extra_types.color.Color.

11. (Third-party object): An instance of colour.Color

Usage#

See Color class API for complete details, highlights are listed here:

from cmap import Color

trq = Color("turquoise")

Useful properties#

Convert to a variety of forms:

trq.hex          # '#40E0D0'
trq.rgba         # RGBA(r=0.2510, g=0.8784, b=0.8157, a=1)
trq.hsl          # HSLA(h=0.4833, s=0.7207, l=0.5647, a=1)
trq.hsv          # HSVA(h=0.4833, s=0.7143, v=0.8784, a=1)
trq.rgba8        # RGBA8(r=64, g=224, b=208, a=1)
trq.rgba_string  # 'rgb(64, 224, 208)'
trq.name         # 'turquoise'

Useful magic methods#

Comparing a color to anything will attempt to cast the other object:

trq == "turquoise"  # True
# colors are cached, so equal colors are the same object
trq is Color((64, 224, 208))  # True

Color implements __array__ so it behaves as an ArrayLike object:

np.asarray(trq)  # array([0.25098039, 0.87843137, 0.81568627, 1.])

You can iterate it

list(trq)  #  [0.25098039, 0.87843137, 0.81568627, 1]

.. or index it:

trq[:2]  # (0.25098039215686274, 0.8784313725490196)

Object Caching#

Note that Color objects are cached after creation and the same object instance is returned for equivalent inputs. This means that you can use is to compare colors, and that you can use Color objects as dictionary keys.

assert Color("red") is Color((255, 0, 0))

Immutability#

All colors are immutable and cannot be modified after instantiation.

trq.name = "foo"  # AttributeError: Color is immutable

Usage with pydantic#

Color can be used as a field type in pydantic models. Fields accept any ColorLike value, and serialize to a color string:

from pydantic import BaseModel
from cmap import Color


class Foo(BaseModel):
    color: Color


foo = Foo(color="red")
foo.color is Color("red")  # True

Foo(color=(0, 11, 23)).model_dump_json()  # '{"color":"#000B17"}'

This also works in psygnal.EventedModel.

class Foo(BaseModel):
    color: Color

    class Config:
        json_encoders = {Color: str}

Rich repr#

If you use rich pretty printing, Color objects have a nice repr that shows the color in the terminal

from rich import pretty

pretty.install()

Recognized Color Names#

The following names may be used as string inputs to the Color constructor.

(case insensitive; spaces, dashes, and underscores are ignored)