principal_colors is an intuitive command-line tool that simplifies the process of extracting a vibrant and distinct color palette from images. This tool caters to users seeking a straightforward solution for color extraction, enabling them to easily obtain color palettes directly from their images using a simple command:

principal-colors path/to/image.jpg

Upon execution, the palette is printed in hex format to the terminal and a corresponding JSON file, image.palette.json, is created alongside the original image.

Key Features

• User-Friendly CLI: Designed for ease of use, employing standard command-line flags and a positional image path for straightforward operation.
• Efficient Color Extraction: Utilizes modern OKLab distances with optional considerations for color-vision deficiencies, ensuring accurate color representation.
• Minimal Dependencies: Built with just NumPy and Pillow, maintaining a lightweight footprint.
• Customizable Outputs: Supports various output formats, including JSON, SVG, PNG, and more, catering to different user needs without compromising the core experience.

Usage Examples

Basic Command

To extract a color palette:

principal-colors image.jpg

Customize Palette

For customized palettes, options such as number of colors or output formats can be specified:

principal-colors image.jpg --colors 10
principal-colors image.jpg --stdout-only
principal-colors image.jpg --output my_palette.json

Advanced Usage

Leverage advanced options for more detailed output:

principal-colors image.jpg --cb-mode all
principal-colors image.jpg --save-formats json,svg,png --output-prefix out/palette
principal-colors image.jpg --print-format rgb

Python API Integration

The tool also provides a comprehensive Python API for developers who prefer programmatic access:

from principal_colors import extract_palette

colors = extract_palette("image.jpg")
print(colors)

For further control and detailed results, users can access:

from principal_colors import extract_palette_result

result = extract_palette_result("image.jpg", num_colors=10)
print(result.hex_colors)
result.save()  # Writes image.palette.json

Output Formats

The extracted palettes can be saved in multiple formats, including:

• JSON
• SVG
• PNG Swatches
• CSS Variables
• Tailwind JSON

The default save format is JSON for easy machine-readability.

For more detailed documentation, refer to the API reference located in docs/API.md.

principal_colors stands out as a powerful yet simple tool for artists, designers, and developers looking to harness the beauty of color in their projects.