0
# Color Utilities
1

2
Comprehensive color conversion and name resolution utilities for handling CSS-style color strings, named colors, and conversion between different color formats and image modes.
3

4
## Capabilities
5

6
### Color String Parsing
7

8
Convert color strings in various formats to RGB/RGBA tuples.
9

10
```python { .api }
11
def getrgb(color: str) -> tuple[int, int, int] | tuple[int, int, int, int]:
12
    """
13
    Convert a color string to an RGB or RGBA tuple.
14

15
    Parameters:
16
    - color (str): Color string in various formats:
17
        - Named colors: "red", "blue", "lightblue", etc.
18
        - Hex: "#RGB", "#RGBA", "#RRGGBB", "#RRGGBBAA"
19
        - CSS RGB: "rgb(255, 0, 0)", "rgb(100%, 0%, 0%)"
20
        - CSS RGBA: "rgba(255, 0, 0, 255)"
21
        - CSS HSL: "hsl(120, 100%, 50%)"
22
        - CSS HSV/HSB: "hsv(120, 100%, 100%)"
23

24
    Returns:
25
    tuple: RGB tuple (r, g, b) or RGBA tuple (r, g, b, a)
26

27
    Raises:
28
    ValueError: If the color string cannot be parsed
29
    """
30
```
31

32
### Mode-Specific Color Conversion
33

34
Convert color strings to values appropriate for specific image modes.
35

36
```python { .api }
37
def getcolor(color: str, mode: str) -> int | tuple[int, ...]:
38
    """
39
    Convert a color string to a value suitable for the given image mode.
40

41
    Parameters:
42
    - color (str): Color string (same formats as getrgb)
43
    - mode (str): Target image mode ("RGB", "RGBA", "L", "LA", "HSV", etc.)
44

45
    Returns:
46
    int | tuple: Color value appropriate for the mode:
47
        - "L": grayscale integer
48
        - "LA": (grayscale, alpha) tuple
49
        - "RGB": (red, green, blue) tuple
50
        - "RGBA": (red, green, blue, alpha) tuple
51
        - "HSV": (hue, saturation, value) tuple
52
        - Other modes: converted appropriately
53

54
    Raises:
55
    ValueError: If the color string cannot be parsed
56
    """
57
```
58

59
### Named Color Support
60

61
The module includes a comprehensive colormap with 140+ named colors from the CSS4 specification, including:
62

63
- **Basic Colors**: "red", "green", "blue", "black", "white"
64
- **Extended Colors**: "aliceblue", "antiquewhite", "aquamarine", etc.
65
- **Gray Variants**: Both "gray" and "grey" spellings supported
66
- **CSS Colors**: Full CSS4 named color support
67

68
### Usage Examples
69

70
```python
71
from PIL import ImageColor
72

73
# Parse different color formats
74
rgb = ImageColor.getrgb("red")                    # (255, 0, 0)
75
rgb = ImageColor.getrgb("#ff0000")               # (255, 0, 0)
76
rgb = ImageColor.getrgb("#f00")                  # (255, 0, 0)
77
rgba = ImageColor.getrgb("#ff000080")            # (255, 0, 0, 128)
78
rgb = ImageColor.getrgb("rgb(255, 0, 0)")        # (255, 0, 0)
79
rgb = ImageColor.getrgb("rgb(100%, 0%, 0%)")     # (255, 0, 0)
80
rgba = ImageColor.getrgb("rgba(255, 0, 0, 128)") # (255, 0, 0, 128)
81
rgb = ImageColor.getrgb("hsl(0, 100%, 50%)")     # (255, 0, 0)
82
rgb = ImageColor.getrgb("hsv(0, 100%, 100%)")    # (255, 0, 0)
83

84
# Convert for specific modes
85
gray = ImageColor.getcolor("red", "L")           # 76 (grayscale)
86
gray_alpha = ImageColor.getcolor("red", "LA")    # (76, 255)
87
rgb = ImageColor.getcolor("red", "RGB")          # (255, 0, 0)
88
rgba = ImageColor.getcolor("red", "RGBA")        # (255, 0, 0, 255)
89
hsv = ImageColor.getcolor("red", "HSV")          # (0, 255, 255)
90

91
# Use with image creation
92
from PIL import Image
93
img = Image.new("RGB", (100, 100), ImageColor.getcolor("lightblue", "RGB"))
94
```