Color Tools

A comprehensive Python library for color science operations, color space conversions, and color matching. This tool provides perceptually accurate color distance calculations, gamut checking, and extensive databases of CSS colors and 3D printing filament colors.

Note: The swatch images above are served by a personal demo deployment — not a public API. They may change or be unavailable without notice. See docs/Badges.md for details.

Changelog

📚 Documentation

📖 Full API Documentation - Complete API reference with examples

User Guides

✨ Features

• Multiple Color Spaces: RGB, HSL, LAB, LCH with accurate conversions
• Perceptual Color Distance: Delta E formulas (CIE76, CIE94, CIEDE2000, CMC, HyAB)
• Color Databases:
  • Complete CSS color names with hex/RGB/HSL/LAB/LCH values
  • Extensive 3D printing filament database (1,050 filaments) with manufacturer info
  • Unique semantic IDs for all filaments (e.g., "bambu-lab-pla-silk-red")
  • Alternative name support for regional variations and rebranding
  • Maker synonym support for flexible filament searches
  • Retro/Classic Palettes: CGA, EGA, VGA, and Web-safe color palettes
• Image Transformations (with [image] extra):
  • Color Vision Deficiency (CVD): Simulate and correct for colorblindness (protanopia, deuteranopia, tritanopia)
  • Palette Quantization: Convert images to retro palettes (CGA, EGA, VGA, Game Boy) with dithering support
  • Unified Architecture: All transformations leverage existing color science infrastructure
• Gamut Checking: Verify if colors are representable in sRGB
• Agent Integration (with [mcp] extra): Typed MCP tools for color analysis, conversion, perceptual comparison, palette search, filament matching, gamut mapping, and CVD transforms
• Thread-Safe: Configurable runtime settings per thread
• Color Science Integrity: Built-in verification of color constants

🎨 Demos

Color Vision Deficiency (CVD) Simulation & Correction

Animated: Original → Simulated (colorblind view) → Corrected, for all three deficiency types (protanopia, deuteranopia, tritanopia).

🚀 Quick Start

Installation

# Base package (zero dependencies)
pip install color-match-tools

# With image processing support
pip install color-match-tools[image]

# With interactive filament library manager
pip install color-match-tools[interactive]

# With colorized console logging (Rich)
pip install color-match-tools[logging]

# With the Color Tools MCP server for agents
pip install color-match-tools[mcp]

# With all optional features
pip install color-match-tools[all]

See Installation Guide for development setup and detailed options.

Creating and Exporting Custom Palettes

from color_tools import Palette, PaletteMetadata, export_palette

palette = Palette.from_rgb(
    [(255, 127, 80), (30, 144, 255), (50, 205, 50)],
    auto_name=True,
)
path = export_palette(
    palette,
    "gpl",
    "my_palette.gpl",
    metadata=PaletteMetadata(name="My Custom Palette", author="Dave", columns=3),
)

By default, colors are named Color 1, Color 2, etc. Set auto_name=True to use built-in CSS/descriptive names, or pass names=["Accent", "Background", ...] to supply explicit names (these override auto-naming and must match the color count). Use Palette.from_hex(["#f00", "00ff00"]) for hex inputs, or ColorRecord.from_rgb() / ColorRecord.from_hex() for individual records. RGB requires exactly three integers from 0 to 255; hex accepts three or six hexadecimal digits with an optional #. Invalid values raise ValueError. Factories preserve order and duplicate colors; auto-generated names may repeat.

Choose a format explicitly using identifiers from list_export_formats("colors"); use the matching filename extension. Exporters that do not support palette metadata still export the colors. Pass exporter-specific options when needed, or use PaletteExportData with embedded metadata instead of a searchable Palette. Omitting the output path lets the exporter generate a filename.

Aseprite Native Palettes

export_palette(
    palette,
    "aseprite",
    "my_palette.aseprite",
    metadata=PaletteMetadata(name="My Palette", columns=16),
)

The dependency-free aseprite exporter writes a single-frame swatch document with an sRGB palette, color names, and compressed pixels. Use .aseprite: the existing ase / .ase exporter remains Adobe Swatch Exchange. Aseprite export rejects filenames with other extensions.

By default, a named transparent-black entry is prepended at index zero for editing. All supplied colors remain opaque and shift by one index; input records are not modified. To omit that entry:

from color_tools.exporters import AsepriteExportOptions

export_palette(
    palette, "aseprite", "opaque_palette.aseprite",
    options=AsepriteExportOptions(include_transparent=False),
)

Order and duplicates are preserved. Up to 256 total entries use indexed pixels; larger palettes use RGBA. The supported input size is 1-65,534 colors with transparency enabled, or 1-65,535 with it disabled. Positive columns selects the grid width (capped at the color count); zero or None produces a horizontal strip. Layout includes the transparent slot. Unused grid cells repeat entry zero. The palette name becomes the background layer name, not a native palette-title field. Author, description, tags, and arbitrary properties are not preserved. Names must fit within 65,535 UTF-8 bytes.

CLI Usage

# Interactive wizard — guided prompts for color, filament, and convert
# (requires: pip install color-match-tools[interactive])
color-tools
color-tools --interactive

# Find a CSS color by name
color-tools color --name coral

# Find nearest CSS color to an RGB value
color-tools color --nearest --value 255 128 64 --space rgb

# Generate a calm, dark triadic harmony
color-tools harmony --type triadic --hex "#E0006B" --mood calm --tone dark

# Find matching 3D printing filaments
color-tools filament --nearest --value 255 128 64

# Convert between color spaces
color-tools convert --from rgb --to lab --value 255 128 64
color-tools convert --from rgb --to cmyk --value 255 128 64
color-tools convert --from cmyk --to rgb --value 0 50 75 0

# Simulate colorblindness on an image
color-tools image --file photo.jpg --cvd-simulate deuteranopia

# Convert image to retro CGA palette
color-tools image --file photo.jpg --quantize-palette cga4 --dither

Library Usage

from color_tools import (
    FilamentCollections,
    FilamentPalette,
    Palette,
    delta_e_2000,
    rgb_to_lab,
)

# Convert RGB to LAB
lab = rgb_to_lab((255, 128, 64))
print(f"LAB: {lab}")

# Find nearest CSS color
palette = Palette.load_default()
nearest, distance = palette.nearest_color(lab, space="lab")
print(f"Nearest: {nearest.name} (ΔE: {distance:.2f})")

# Find matching filaments
filament_palette = FilamentPalette.load_default()
filament, distance = filament_palette.nearest_filament((255, 128, 64))
print(f"Filament: {filament.maker} {filament.color}")

# Use a predefined, immutable filament collection
for filament in FilamentCollections.BAMBU_PLA_BASIC:
    print(filament.color, filament.hex)

See Usage Guide for complete API reference and CLI documentation.

Color Harmonies

Generate perceptual color harmonies in CIE LCH space from an RGB base color:

from color_tools import generate_harmony

palette = generate_harmony(
  (224, 0, 107),
  "triadic",
  mood="calm",
  tone="dark",
)

print([color.hex for color in palette.colors])

Harmony schemes include analogous, complementary, split-complementary, triadic, square, tetradic, monochromatic, and six-color rainbow/full-spectrum. Optional warm, cool, happy, calm, intense, sad, and energetic mood presets adjust palette lightness and chroma without changing the harmony's hue relationships. Independent dark and light tones can be composed with any mood.

Mood presets are opinionated design heuristics rather than universal psychological rules. The base color remains unchanged by default; pass grade_base=True to style it with the generated colors.

MCP Server

The optional MCP server exposes Color Tools to GitHub Copilot and other MCP-compatible agents as typed, structured tools:

pip install "color-match-tools[mcp]"
color-tools-mcp

MCP clients normally launch the stdio server automatically with python -m color_tools.mcp. See the MCP server guide for the tool catalog and client configuration.

🎨 Color Spaces

Use LAB or LCH for color matching - they're designed to match human perception. Use CMYK for print workflows - the K channel produces richer blacks than CMY alone.

📏 Distance Metrics

See FAQ for detailed explanations of when to use each metric.

📦 Data Files

The library includes extensive color databases:

• CSS Colors: 147 named colors with full color space representations
• 3D Printing Filaments: 1,050 filaments from major manufacturers
• Retro Palettes: 20 official palettes including CGA, EGA, VGA, Game Boy, Commodore 64, PICO-8, and more

Extend with your own data using User Data Files.

Track your owned filaments for personalized color matching - create an owned-filaments.json file to automatically filter searches to filaments you already have. See Owned Filaments in the Customization Guide.

🔧 Export & Integration

Export colors and filaments to various formats for use with external tools:

Available Formats

list_export_formats() returns only formats whose optional dependencies are installed by default. Pass available_only=False to include unavailable formats. Install color-match-tools[image] for ASE and presentation swatch images.

Export Examples

from color_tools import Palette, FilamentPalette
from color_tools.exporters import get_exporter, list_export_formats
from color_tools.exporters.palette_export_data import PaletteExportData
from color_tools.exporters.palette_metadata import PaletteMetadata
from color_tools.exporters.swatch_image_exporter import SwatchImageOptions

# List available formats for colors
formats = list_export_formats("colors")

# Export raw color records
palette = Palette.load_default()
get_exporter("gpl").export_colors(palette.records[:20], "colors.gpl")
get_exporter("jasc_pal").export_colors(palette.records[:20], "colors.pal")

# Preserve palette-level metadata when the format supports it
palette_data = PaletteExportData(
  colors=palette.records[:8],
  metadata=PaletteMetadata(
    name="Sample Palette",
    author="Color Tools",
    description="Eight colors exported with palette metadata.",
    columns=4,
  ),
)
get_exporter("json").export_palette(palette_data, "palette.json")

# Supply strongly typed, per-export options to configurable exporters
get_exporter("swatch_image").export_palette(
  palette_data,
  "palette.png",
  options=SwatchImageOptions(show_rgb=True, show_lab=True),
)

# Export filament records
filaments = FilamentPalette.load_default()
bambu_pla = filaments.filter(maker="Bambu Lab", type_name="PLA")
get_exporter("autoforge").export_filaments(bambu_pla, "bambu_pla.csv")

The functions in color_tools.export, including export_colors() and export_filaments(), remain available as backward-compatible facades. New integrations should use the exporter registry when they need capability metadata, palette metadata, optional dependency checks, or typed options.

Plugin Architecture

The exporter system uses a plugin architecture - new formats can be added without modifying existing code:

from color_tools.exporters import register_exporter
from color_tools.exporters.base import PaletteExporter, ExporterMetadata

@register_exporter
class MyExporter(PaletteExporter):
    @property
  def metadata(self) -> ExporterMetadata:
        return ExporterMetadata(
      name="myformat",
      description="My custom format",
      file_extension="txt",
            supports_colors=True,
            supports_filaments=False,
        )

  def _export_colors_impl(self, colors, output_path) -> str:
    # Write the file and return its path.
    return str(output_path)

See exporters/gpl_exporter.py for a complete example.

📋 Logging

The library ships with a structured logging system that fans out to console and an optional rotating file — one call, both destinations:

from pathlib import Path
import logging
from color_tools import setup_logging, get_logger, log_info

# Console-only (INFO+ by default)
setup_logging()

# Console + rotating file (DEBUG+ to file, INFO+ to console)
setup_logging(log_file=Path("color_tools.log"), console_level=logging.DEBUG)

# Module-level logger (use __name__ to get "color_tools.mymodule")
logger = get_logger(__name__)
logger.info("Loaded %d colors", count)

# Convenience shortcuts on the library root logger
log_info("Processing %d filaments", n)

For colorized console output install the [logging] extra:

pip install color-match-tools[logging]   # adds Rich

The library registers a NullHandler at import time (Python library best practice), so no output is produced until setup_logging() is explicitly called.

CLI file logging — write logs while using the command line:

color-tools --log-file color_tools.log color --nearest --hex "#FF8040"
color-tools --log-file debug.log --log-level DEBUG filament --nearest --hex "#FF0000"

See Usage Guide for the full API reference.

�🔒 Data Integrity

All core data files are protected with SHA-256 hashes:

python -m color_tools --verify-all

See Troubleshooting for verification details.

🤝 Contributing

CRITICAL: Color science constants should NEVER be modified. They represent fundamental values from international standards.

See FAQ for contribution guidelines.

📄 License

MIT License - see LICENSE for details.