Color Tools API Reference

Version: 6.5.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:

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

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.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.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 plugin system.
`color_tools.exporters.base`	Base classes and metadata for palette exporters.
`color_tools.exporters.csv_exporter`	Generic CSV exporter for colors and filaments.
`color_tools.exporters.json_exporter`	JSON format exporter for colors and filaments.
`color_tools.exporters.gpl_exporter`	GIMP Palette (.gpl) format exporter.
`color_tools.exporters.hex_exporter`	Hex format exporter.
`color_tools.exporters.jascpal_exporter`	JASC-PAL format exporter.
`color_tools.exporters.autoforge_exporter`	AutoForge filament library CSV exporter.
`color_tools.exporters.lospec_exporter`	Lospec JSON palette format exporter.
`color_tools.exporters.paintnet_exporter`	PAINT.NET palette format exporter.

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.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.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.

Optional Features

color_tools.interactive_manager

Interactive filament library manager using prompt_toolkit TUI.