Color Tools API Reference

Version: 6.12.0

Welcome to the Color Tools API documentation! This library provides comprehensive color science tools for accurate color space conversions, perceptual color distance metrics, and color matching.

🎨 Three Ways to Use Color Tools:

1. As a library: from color_tools import rgb_to_lab

2. As a CLI tool: python -m color_tools color --name coral

3. As installed command: color_tools filament --list-makers (needs pip install)

Quick Start

from color_tools import rgb_to_lab, delta_e_2000, Palette

# Convert RGB to LAB
lab = rgb_to_lab((255, 128, 64))

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

Documentation

For comprehensive guides and CLI usage:

• 📖 Usage Guide - Library and CLI usage examples

• ⚙️ Installation - Installation instructions

• 🎨 Customization - User overrides and custom palettes

• ❓ FAQ - Frequently asked questions

• 📋 Quick Reference - Command cheat sheet

• 🔧 Troubleshooting - Common issues and solutions

CLI Commands

The CLI provides six main commands:

• color - Search CSS colors by name or find nearest color

• filament - Search 3D printing filaments with filtering (maker, type, finish)

• convert - Convert between color spaces and check gamut

• name - Generate descriptive names for RGB colors

• validate - Validate if hex codes match color names (fuzzy matching + Delta E)

  • Optional: Install [fuzzy] extra for improved fuzzy matching: pip install color-match-tools[fuzzy]

• cvd - Color vision deficiency simulation and correction

• image - Image color analysis and manipulation

  • Requires: Install [image] extra: pip install color-match-tools[image]

See the Usage Guide for detailed CLI examples.

Data Classes

The library uses immutable dataclasses (frozen) to represent colors, filaments, and results:

• ColorRecord - CSS colors with precomputed values in all color spaces

• FilamentRecord - 3D printing filaments with intelligent dual-color handling

• ColorValidationRecord - Color name/hex validation results with fuzzy matching

• ColorCluster - Image color clusters from k-means analysis (requires [image] extra)

• ColorChange - Luminance redistribution results for HueForge (requires [image] extra)

All data classes have comprehensive docstrings with attribute descriptions and examples. See the Usage Guide for a quick reference table.

Core API Reference

Color Science

color_tools.conversions	Color space conversion functions.
color_tools.distance	Color distance metrics for measuring perceptual color differences.
color_tools.gamut	Gamut checking and mapping for sRGB color space.
color_tools.harmony	Generate color harmonies in CIE LCH space.
color_tools.constants	Immutable color science constants from international standards.
color_tools.matrices	Color transformation matrices for various operations.
color_tools.config	Thread-safe runtime configuration for color processing behavior.

Color & Filament Data

color_tools.palette	Color palette management with fast lookup.
color_tools.filament_palette	Filament palette management for 3D printing color matching.
color_tools.filament_collections	Predefined, lazily loaded filament collections.
color_tools.naming	Color naming utilities for generating descriptive names from RGB values.
color_tools.validation	Color validation functions to check if a hex code matches a color name.
color_tools.color_deficiency	Color vision deficiency simulation and correction.

Export System

color_tools.export	Export system for filaments and colors.
color_tools.exporters	Palette exporter package.
color_tools.exporters.base	Base classes, metadata, and dependency handling for palette exporters.
color_tools.exporters.export_options_base	Base class for exporter-specific options.
color_tools.exporters.palette_export_data	Palette export data model.
color_tools.exporters.palette_metadata	Palette-level metadata.
color_tools.exporters.registry	Exporter registry and discovery utilities.
color_tools.exporters.ase_exporter	Adobe Swatch Exchange (ASE) palette exporter.
color_tools.exporters.autoforge_exporter	AutoForge filament library CSV exporter.
color_tools.exporters.css_exporter	CSS custom-properties palette exporter.
color_tools.exporters.csv_exporter	Generic CSV exporter for colors and filaments.
color_tools.exporters.gpl_exporter	GIMP Palette (.gpl) exporter.
color_tools.exporters.hex_exporter	HEX palette exporter.
color_tools.exporters.jascpal_exporter	JASC-PAL palette exporter.
color_tools.exporters.json_exporter	Generic JSON exporter for colors and filaments.
color_tools.exporters.kpl_exporter	Krita Palette (.kpl) exporter.
color_tools.exporters.lospec_exporter	Lospec JSON palette exporter.
color_tools.exporters.paintnet_exporter	PAINT.NET palette format exporter.
color_tools.exporters.palette_lut_exporter	Palette LUT PNG exporter.
color_tools.exporters.python_exporter	Python source-code palette exporter.
color_tools.exporters.riffpal_exporter	Microsoft RIFF PAL palette exporter.
color_tools.exporters.scribus_exporter	Scribus XML palette exporter.
color_tools.exporters.sketchpalette_exporter	SketchPalette exporter.
color_tools.exporters.soc_exporter	LibreOffice/OpenOffice SOC palette exporter.
color_tools.exporters.swatch_image_exporter	Palette swatch image exporter.

Import System

color_tools.importers	Palette importer system.
color_tools.importers.base	Base classes, metadata, dependency handling, and shared color construction for palette importers.
color_tools.importers.registry	Palette importer registry.
color_tools.importers.gpl_importer	GIMP Palette (GPL) importer.
color_tools.importers.hex_importer	HEX palette importer.
color_tools.importers.jascpal_importer	JASC PAL palette importer.
color_tools.importers.riffpal_importer	RIFF PAL palette importer.

Image Processing (requires [image] extra)

color_tools.image	Image processing module for color_tools.
color_tools.image.analysis	Image analysis functions for color extraction and manipulation.
color_tools.image.basic	Basic image analysis functions for color_tools.
color_tools.image.blend	Photoshop-compatible blend mode operations for image layers.
color_tools.image.conversion	Image format conversion utilities.
color_tools.image.dominance	Perceptual dominant-color analysis for images.
color_tools.image.watermark	Watermarking functionality for images.

Command Line Interface

color_tools.cli	Command-line interface for color_tools.
color_tools.cli_commands	CLI package for color_tools.
color_tools.cli_commands.utils	Utility functions for CLI argument parsing and validation.
color_tools.cli_commands.reporting	Reporting and diagnostic utilities for user data and overrides.
color_tools.cli_commands.handlers	Command handlers for color_tools CLI.
color_tools.cli_commands.handlers.color	Color command handler - Search and query CSS colors.
color_tools.cli_commands.handlers.convert	Convert command handler - Convert between color spaces and check gamut.
color_tools.cli_commands.handlers.cvd	CVD command handler - Color vision deficiency simulation and correction.
color_tools.cli_commands.handlers.harmony	Harmony command handler - Generate styled LCH color harmonies.
color_tools.cli_commands.handlers.filament	Filament command handler - Search and query 3D printing filaments.
color_tools.cli_commands.handlers.image	Image processing command handler.
color_tools.cli_commands.handlers.name	Name command handler - Generate descriptive color names from RGB values.
color_tools.cli_commands.handlers.validate	Validate command handler - Verify color name/hex pairings.

Logging (optional [logging] extra for colorized output)

color_tools.logging_config

Centralized logging configuration for color_tools.

Optional Features

color_tools.interactive_manager	Interactive filament library manager using prompt_toolkit TUI.
color_tools.interactive_wizard	Interactive wizard for color-tools.

Indices and tables

• Index

• Module Index

• Search Page