chromaspec 1.0.0

Python CLI tool for color palette analysis. Extract colors from images and SVG files, generate professional PDF swatches with HEX/RGB/CMYK values, frequency stats, pie charts, color harmonies, and WCAG accessibility ratings.

ChromaSpec

A Python tool for color palette analysis that extracts colors from SVG or image files (PNG, JPG, etc.) and generates a professional PDF color swatch document with designer-friendly visualizations organized by Red, Green, and Blue sections.

Features

Color Extraction

• Extracts colors from SVG files (via regex) and image files (via pixel analysis)
• Organizes colors into Red, Green, and Blue sections
• Displays HEX, RGB, and CMYK color values
• Shows frequency percentage for each color
• Supports both 3-digit (#ABC) and 6-digit (#AABBCC) HEX formats
• Supports multiple image formats: PNG, JPG, JPEG, GIF, BMP, TIFF, WebP

Designer Visualizations

• Color Distribution - Pie chart and bar chart showing RGB breakdown
• Top Colors & Harmonies - Shows the 5 most used colors with:
  • HSL (Hue, Saturation, Lightness) values
  • Complementary color (opposite on color wheel)
  • Analogous colors (adjacent ±30° on color wheel)
• Accessibility & Contrast - WCAG 2.1 compliance checker:
  • Contrast ratios against white and black backgrounds
  • AAA/AA/AA Large/Fail ratings
  • Recommendations for dark or light backgrounds

PDF Features

• Cover page with image preview and color summary
• Headers and footers on all pages with page numbers
• Colors sorted by frequency (most common first)
• Clean monospaced Courier font for consistent alignment
• Command-line interface with flexible options

Installation

1. Clone the repository:

git clone https://github.com/MichailSemoglou/chromaspec.git
cd chromaspec

2. Create a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

3. Install dependencies:

pip install -r requirements.txt

Usage

Basic Usage

# From SVG file
python chromaspec.py input.svg

# From image file
python chromaspec.py photo.png
python chromaspec.py image.jpg

This will create <input_name>_colors.pdf in the same directory.

Custom Output Path

python chromaspec.py input.png custom_output.pdf

Help

python chromaspec.py --help

Supported Formats

Format	Extension
SVG	.svg
PNG	.png
JPEG	.jpg, .jpeg
GIF	.gif
BMP	.bmp
TIFF	.tiff
WebP	.webp

Example Output

The generated PDF contains:

1. Cover page with:

   • Title and input filename
   • Image preview (for image files)
   • Color summary (count of Red, Green, Blue colors)

2. Color Distribution page with:

   • Pie chart showing RGB distribution
   • Bar chart comparing color counts
   • Percentage breakdown

3. Top Colors & Harmonies page with:

   • The 5 most frequently used colors
   • HSL values for each color
   • Complementary and analogous color suggestions

4. Accessibility & Contrast page with:

   • WCAG contrast ratios vs white and black
   • AAA/AA/Fail ratings for each color
   • Background usage recommendations

5. Color swatch pages with:

   • Section headers for Red, Green, and Blue
   • Color rectangles with no borders
   • Full color information: #FF8040 RGB(255,128, 64) CMYK( 0, 50, 75, 0) 0.153%

• Headers and footers on all pages

Requirements

• Python 3.8+
• reportlab >= 4.0.0
• Pillow >= 10.0.0 (for image file support)

How It Works

1. Extract:
   • For SVG files: Parses and finds all HEX color codes using regex
   • For images: Analyzes pixel data to extract dominant colors with frequencies
2. Categorize: Groups colors into Red, Green, and Blue based on dominant RGB component
3. Convert: Calculates RGB and CMYK values for each color
4. Generate: Creates a professional PDF document with cover page and organized color swatch sections

Color Classification

A color is classified based on its dominant RGB component:

• Red: Red component > Green and Blue
• Green: Green component > Red and Blue
• Blue: Blue component > Red and Green

License

MIT License - see LICENSE for details.

Citation

If you use ChromaSpec in your research, please cite it:

@software{semoglou_chromaspec_2025,
  author       = {Semoglou, Michail},
  title        = {ChromaSpec: Color Palette Analyzer},
  year         = {2025},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.17864788},
  url          = {https://doi.org/10.5281/zenodo.17864788}
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.