renoir.color.visualization

Visualization functions for color analysis.

This module provides tools for creating educational visualizations of color data, palettes, and distributions.

class renoir.color.visualization.ColorVisualizer[source]

Bases: object

Create visualizations for color analysis and education.

This class provides methods for visualizing color palettes, distributions, and relationships. Designed for teaching color theory and computational analysis to art and design students.

plot_palette(colors, title='Color Palette', figsize=(12, 2), save_path=None, show_hex=True, show_names=False, vocabulary='artist', show=True)[source]

Visualize a color palette as horizontal color swatches.

Educational method for displaying extracted colors clearly.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size (width, height)

  • save_path (Optional[str]) – Optional path to save the figure

  • show_hex (bool) – Whether to show hex codes below colors

  • show_names (bool) – Whether to show evocative color names (default: False)

  • vocabulary (str) – Color naming vocabulary to use when show_names=True Options: ‘artist’, ‘resene’, ‘natural’, ‘xkcd’

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

Example

>>> from renoir.color import ColorExtractor, ColorVisualizer
>>> extractor = ColorExtractor()
>>> visualizer = ColorVisualizer()
>>> colors = [(255, 87, 51), (100, 200, 150), (50, 100, 200)]
>>> visualizer.plot_palette(colors, title="My Palette")
>>> # With color names
>>> visualizer.plot_palette(colors, show_names=True, vocabulary="artist")
plot_named_palette(colors, vocabulary='artist', title=None, figsize=(12, 4), save_path=None, show_metadata=False, show=True)[source]

Visualize a color palette with evocative color names.

Creates a rich visualization showing color swatches with their evocative names and optional metadata like Color Index names.

Parameters:

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

  • vocabulary (str) – Color naming vocabulary (‘artist’, ‘resene’, ‘natural’, ‘xkcd’)

  • title (Optional[str]) – Plot title (auto-generated if None)

  • figsize (Tuple[int, int]) – Figure size (width, height)

  • save_path (Optional[str]) – Optional path to save the figure

  • show_metadata (bool) – Whether to show additional metadata like CI names

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

Example

>>> from renoir.color import ColorExtractor, ColorVisualizer
>>> visualizer = ColorVisualizer()
>>> colors = [(255, 87, 51), (100, 200, 150), (50, 100, 200)]
>>> visualizer.plot_named_palette(colors, vocabulary="artist")
plot_color_wheel(colors, title='Color Wheel Distribution', figsize=(8, 8), save_path=None, show=True)[source]

Plot colors on a color wheel to show hue distribution.

Educational visualization showing where colors fall on the spectrum.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

Example

>>> visualizer = ColorVisualizer()
>>> colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255)]
>>> fig = visualizer.plot_color_wheel(colors)
plot_rgb_distribution(colors, title='RGB Distribution', figsize=(12, 4), save_path=None, show=True)[source]

Plot RGB channel distributions as histograms.

Educational visualization for understanding color composition.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

plot_hsv_distribution(colors, title='HSV Distribution', figsize=(14, 4), save_path=None, show=True)[source]

Plot HSV (Hue, Saturation, Value) distributions.

Educational visualization for understanding color in HSV space.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

plot_3d_rgb_space(colors, title='RGB Color Space (3D)', figsize=(10, 8), save_path=None, show=True)[source]

Plot colors in 3D RGB space.

Advanced educational visualization showing spatial relationships.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

compare_palettes(palette1, palette2, labels=('Palette 1', 'Palette 2'), figsize=(12, 6), save_path=None, show=True)[source]

Compare two color palettes side by side.

Educational visualization for comparing artistic color choices.

Parameters:

  • palette1 (List[Tuple[int, int, int]]) – First list of RGB tuples

  • palette2 (List[Tuple[int, int, int]]) – Second list of RGB tuples

  • labels (Tuple[str, str]) – Tuple of labels for the two palettes

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

plot_temperature_distribution(colors, title='Color Temperature Distribution', figsize=(10, 6), save_path=None, show=True)[source]

Visualize warm vs. cool color distribution.

Educational visualization for color temperature analysis.

Parameters:

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

  • title (str) – Plot title

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

create_artist_color_report(colors, artist_name, figsize=(16, 12), save_path=None, show=True)[source]

Create a comprehensive color analysis report for an artist.

Combines multiple visualizations into a single figure. Educational method for comprehensive color analysis.

Parameters:

  • colors (List[Tuple[int, int, int]]) – List of RGB tuples from the artist’s works

  • artist_name (str) – Name of the artist

  • figsize (Tuple[int, int]) – Figure size

  • save_path (Optional[str]) – Optional path to save the figure

  • show (bool) – If True, display the figure with plt.show()

Return type:

Figure

plot_historical_pigment_probability(color, year, results=None, top_k=5, figsize=(10.0, 4.5), save_path=None, show=True)[source]

Visualize Historical Pigment Probability (HPP) output for one color.

Shows the input color alongside the ranked candidate pigments returned by historical_pigment_probability(), with swatch, Color Index name, year of introduction, probability bar, and availability flag for each candidate.

Parameters:

  • color (Tuple[int, int, int]) – Input RGB color tuple, e.g. (28, 62, 145).

  • year (int) – Historical year against which availability is assessed.

  • results (Optional[List[Dict]]) – Pre-computed HPP output (list of dicts). If None the method calls ColorNamer internally.

  • top_k (int) – Number of candidate pigments to display (default 5).

  • figsize (Tuple[float, float]) – Figure dimensions (width, height) in inches.

  • save_path (Optional[str]) – File path for saving (PNG at 300 dpi or PDF).

  • show (bool) – If True, display the figure with plt.show().

Return type:

Figure

plot_pemd_comparison(pairs, labels=None, pemd_values=None, figsize=(9.0, 4.0), save_path=None, show=True)[source]

Visualize Palette Earth Mover’s Distance (PEMD) for one or more palette pairs.

Each pair is shown as two proportional color strips with the PEMD value annotated between them. Accepts pre-computed PEMD values or computes them internally.

Parameters:

  • pairs (List[Tuple[List, List]]) – List of (palette1, palette2) tuples. Each palette is a list of ((R, G, B), proportion) tuples.

  • labels (Optional[List[Tuple[str, str]]]) – List of (label1, label2) strings for each pair.

  • pemd_values (Optional[List[float]]) – Pre-computed PEMD floats, one per pair. If None values are computed internally (requires scipy).

  • figsize (Tuple[float, float]) – Figure dimensions (width, height) in inches.

  • save_path (Optional[str]) – File path for saving (PNG at 300 dpi or PDF).

  • show (bool) – If True, display the figure with plt.show().

Return type:

Figure

plot_cross_vocabulary_naming(colors, vocabulary_labels=None, figsize=None, save_path=None, show=True)[source]

Visualize how a palette is named across all four color vocabularies.

Creates a grid with vocabularies in rows and colors in columns. Each cell shows the matched color swatch and the name from that vocabulary (CIEDE2000 nearest-neighbor match).

Parameters:

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

  • vocabulary_labels (Optional[Dict[str, str]]) – Optional mapping of vocabulary key to display label. Defaults to standard vocabulary names.

  • figsize (Optional[Tuple[float, float]]) – Figure dimensions (width, height) in inches. Auto-sized when None.

  • save_path (Optional[str]) – File path for saving (PNG at 300 dpi or PDF).

  • show (bool) – If True, display the figure with plt.show().

Return type:

Figure

renoir.color.visualization.check_visualization_support()[source]

Check if visualization dependencies are available.

Return type:

bool

Returns:

True if matplotlib is available, False otherwise