color_tools.image

Image processing module for color_tools.

This module provides image color analysis and manipulation tools: - Format Conversion: Convert between PNG, JPEG, WebP, HEIC, AVIF, etc. (conversion.py) - Watermarking: Add text, image, or SVG watermarks (watermark.py) - Color Analysis: Extract dominant colors with K-means clustering (analysis.py) - HueForge 3D printing: Luminance redistribution for multi-color printing (analysis.py) - CVD Operations: Simulate/correct color vision deficiencies (basic.py) - Palette Quantization: Convert to retro palettes with dithering (basic.py) - General Analysis: Count colors, brightness, contrast, noise (basic.py)

Requires Pillow: pip install color-match-tools[image]

Example:

>>> from color_tools.image import (
...     convert_image, add_watermark,
...     count_unique_colors, analyze_brightness,
...     simulate_cvd_image, quantize_image_to_palette
... )
>>>
>>> # Convert image formats (auto-generates output filename)
>>> convert_image("photo.webp", output_format="png")  # Creates photo.png
>>> convert_image("photo.jpg", output_format="webp", lossless=True)
PosixPath('photo.webp')
>>>
>>> # Add watermark
>>> add_text_watermark(
...     "photo.jpg",
...     text="© 2025 MyBrand",
...     position="bottom-right",
...     output_path="watermarked.jpg"
... )
PosixPath('watermarked.jpg')
>>>
>>> # Count colors in an image
>>> total = count_unique_colors("photo.jpg")
>>> print(f"Found {total} unique colors")
Found 42387 unique colors
>>>
>>> # Analyze image quality
>>> brightness = analyze_brightness("photo.jpg")
>>> print(f"Brightness: {brightness['mean_brightness']:.1f} ({brightness['assessment']})")
Brightness: 127.3 (normal)
>>>
>>> # Test accessibility with CVD simulation
>>> sim_image = simulate_cvd_image("chart.png", "deuteranopia")
>>> sim_image.save("chart_colorblind_view.png")
>>>
>>> # Create retro-style artwork
>>> retro = quantize_image_to_palette("photo.jpg", "cga4", dither=True)
>>> retro.save("retro_cga.png")
>>>
>>> # Extract dominant colors for Hueforge
>>> from color_tools.image import extract_color_clusters, redistribute_luminance
>>>
>>> # Extract 10 dominant colors from image
>>> clusters = extract_color_clusters("photo.jpg", n_colors=10)
>>>
>>> # Redistribute luminance for Hueforge
>>> colors = [c.centroid_rgb for c in clusters]
>>> changes = redistribute_luminance(colors)
>>>
>>> # Show layer assignments
>>> for change in changes:
...     print(f"Layer {change.hueforge_layer}: RGB{change.new_rgb}")

class color_tools.image.ColorCluster

Bases: object

class color_tools.image.ColorChange

Bases: object

color_tools.image.extract_unique_colors(*args, **kwargs)

color_tools.image.extract_color_clusters(*args, **kwargs)

color_tools.image.redistribute_luminance(*args, **kwargs)

color_tools.image.format_color_change_report(*args, **kwargs)

color_tools.image.l_value_to_hueforge_layer(*args, **kwargs)

color_tools.image.count_unique_colors(*args, **kwargs)

color_tools.image.get_color_histogram(*args, **kwargs)

color_tools.image.get_dominant_color(*args, **kwargs)

color_tools.image.is_indexed_mode(*args, **kwargs)

color_tools.image.analyze_brightness(*args, **kwargs)

color_tools.image.analyze_contrast(*args, **kwargs)

color_tools.image.analyze_noise_level(*args, **kwargs)

color_tools.image.analyze_dynamic_range(*args, **kwargs)

color_tools.image.transform_image(*args, **kwargs)

color_tools.image.simulate_cvd_image(*args, **kwargs)

color_tools.image.correct_cvd_image(*args, **kwargs)

color_tools.image.quantize_image_to_palette(*args, **kwargs)

color_tools.image.add_text_watermark(*args, **kwargs)

color_tools.image.add_image_watermark(*args, **kwargs)

color_tools.image.add_svg_watermark(*args, **kwargs)

color_tools.image.convert_image(*args, **kwargs)

color_tools.image.get_supported_formats(*args, **kwargs)