renoir.color.extraction

Color extraction functions for artwork analysis.

This module provides tools for extracting dominant colors from artworks using k-means clustering and other computational methods.

class renoir.color.extraction.ColorExtractor

Bases: object

Extract dominant colors and palettes from artwork images.

This class provides methods for extracting color information from digital images, designed for educational use in teaching computational color analysis to art and design students.

use_sklearn

Whether scikit-learn is available for k-means clustering

extract_dominant_colors(image, n_colors=5, method='kmeans', sample_size=10000, random_state=42, filter_extremes=True)

Extract dominant colors from an image using k-means clustering.

This method identifies the most prominent colors in an artwork by clustering pixel colors and finding cluster centers. Ideal for teaching students about color quantization and computational analysis.

Parameters:

• image (Union[Image, ndarray]) – PIL Image or numpy array of the artwork

• n_colors (int) – Number of dominant colors to extract (default: 5)

• method (str) – Extraction method - ‘kmeans’ or ‘frequency’ (default: ‘kmeans’)

• sample_size (Optional[int]) – Number of pixels to sample for faster processing None = use all pixels (default: 10000)

• random_state (int) – Random seed for reproducible pixel sampling and k-means clustering (default: 42)

• filter_extremes (bool) – Whether to remove pure black (0,0,0) and pure white (255,255,255) pixels before clustering. Set to False when analysing artworks where true black or white are meaningful (default: True)

Return type:

List[Tuple[int, int, int]]

Returns:

List of RGB tuples representing dominant colors, ordered by prominence

Raises:

• ValueError – If n_colors is invalid

• ValueError – If sample_size is invalid

• ValueError – If method is not recognized

• TypeError – If image is not PIL Image or numpy array

• ValueError – If image dimensions are invalid

Example

>>> extractor = ColorExtractor()
>>> from PIL import Image
>>> img = Image.open('artwork.jpg')
>>> colors = extractor.extract_dominant_colors(img, n_colors=5)
>>> print(colors)
[(120, 89, 143), (201, 178, 156), ...]

extract_palette_from_artwork(artwork_dict, n_colors=5)

Extract color palette from a WikiArt artwork dictionary.

Convenience method that works directly with renoir artwork data.

Parameters:

• artwork_dict (Dict) – Artwork dictionary from WikiArt dataset

• n_colors (int) – Number of colors to extract

Return type:

Dict

Returns:

Dictionary with ‘colors’ (RGB tuples) and ‘metadata’ (artwork info)

Example

>>> from renoir import ArtistAnalyzer
>>> analyzer = ArtistAnalyzer()
>>> works = analyzer.extract_artist_works('claude-monet')
>>> extractor = ColorExtractor()
>>> palette = extractor.extract_palette_from_artwork(works[0])

extract_average_color(image)

Calculate the average color of an image.

Simple method useful for teaching color concepts to beginners.

Parameters:

image (Union[Image, ndarray]) – PIL Image or numpy array

Return type:

Tuple[int, int, int]

Returns:

RGB tuple representing the average color

Example

>>> extractor = ColorExtractor()
>>> avg_color = extractor.extract_average_color(img)
>>> print(f"Average color: RGB{avg_color}")

rgb_to_hex(rgb)

Convert RGB tuple to hexadecimal color code.

Parameters:

rgb (Tuple[int, int, int]) – Tuple of (R, G, B) values (0-255)

Return type:

str

Returns:

Hexadecimal color string (e.g., ‘#FF5733’)

Example

>>> extractor = ColorExtractor()
>>> hex_color = extractor.rgb_to_hex((255, 87, 51))
>>> print(hex_color)  # '#FF5733'

hex_to_rgb(hex_color)

Convert hexadecimal color code to RGB tuple.

Parameters:

hex_color (str) – Hexadecimal color string (e.g., ‘#FF5733’ or ‘FF5733’)

Return type:

Tuple[int, int, int]

Returns:

Tuple of (R, G, B) values (0-255)

Example

>>> extractor = ColorExtractor()
>>> rgb = extractor.hex_to_rgb('#FF5733')
>>> print(rgb)  # (255, 87, 51)

palette_to_dict(colors, include_hex=True)

Convert color palette to a dictionary format.

Useful for exporting palettes or educational demonstrations.

Parameters:

• colors (List[Tuple[int, int, int]]) – List of RGB tuples

• include_hex (bool) – Whether to include hex codes (default: True)

Return type:

Dict

Returns:

Dictionary with palette information

Example

>>> colors = [(255, 87, 51), (100, 200, 150)]
>>> palette_dict = extractor.palette_to_dict(colors)

export_palette_css(colors, filename, prefix='color')

Export color palette as CSS variables.

Useful for design students to use extracted palettes in web projects.

Parameters:

• colors (List[Tuple[int, int, int]]) – List of RGB tuples

• filename (str) – Output CSS filename

• prefix (str) – Variable name prefix (default: ‘color’)

Return type:

None

Example

>>> colors = [(255, 87, 51), (100, 200, 150)]
>>> extractor.export_palette_css(colors, 'palette.css')

export_palette_json(colors, filename)

Export color palette as JSON.

Parameters:

• colors (List[Tuple[int, int, int]]) – List of RGB tuples

• filename (str) – Output JSON filename

Return type:

None

Example

>>> colors = [(255, 87, 51), (100, 200, 150)]
>>> extractor.export_palette_json(colors, 'palette.json')

renoir.color.extraction.check_color_extraction_support()

Check if color extraction dependencies are available.

Return type:

bool

Returns:

True if scikit-learn is available, False otherwise