Color Tools API Reference

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:

As a library: from color_tools import rgb_to_lab
As a CLI tool: python -m color_tools color --name coral
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

All Modules

`color_tools.conversions`	Color space conversion functions.
`color_tools.distance`	Color distance metrics for measuring perceptual color differences.
`color_tools.palette`	Color and filament palette management with fast lookup.
`color_tools.gamut`	Gamut checking and mapping for sRGB color space.
`color_tools.validation`	Color validation functions to check if a hex code matches a color name.
`color_tools.naming`	Color naming utilities for generating descriptive names from RGB values.
`color_tools.color_deficiency`	Color vision deficiency simulation and correction.
`color_tools.export`	Export system for filaments and colors.
`color_tools.config`	Thread-safe runtime configuration for color processing behavior.
`color_tools.constants`	Immutable color science constants from international standards.
`color_tools.matrices`	Color transformation matrices for various operations.
`color_tools.image`	Image processing module for color_tools.