SWATCH IFY

Extract Dominant Colors From Images

◆ REST API ◆ GO LIBRARY ◆ CLI TOOL ◆ K-MEANS CLUSTERING ◆ JSON OUTPUT ◆ PALETTE PNG ◆ CROSS-PLATFORM ◆ OPEN SOURCE ◆ ◆ REST API ◆ GO LIBRARY ◆ CLI TOOL ◆ K-MEANS CLUSTERING ◆ JSON OUTPUT ◆ PALETTE PNG ◆ CROSS-PLATFORM ◆ OPEN SOURCE ◆

GET IT NOW

Go Install

go install github.com/james-see/swatchify@latest

Homebrew

brew install james-see/tap/swatchify

Download Binary

→ github.com/james-see/swatchify/releases
★ GITHUB DOWNLOAD

HOW IT WORKS

$ swatchify photo.jpg
#131014
#7673AD
#73500A
#B68296
#44353B

$ swatchify logo.png -n 8 --json
{
  "image": "logo.png",
  "colors": [
    {"hex": "#FF0000", "percentage": 34.5},
    {"hex": "#00FF00", "percentage": 21.0},
    ...
  ]
}

$ swatchify brand.png --png palette.png --show
→ Opens palette image with hex labels

EXAMPLE PALETTE OUTPUT:

#131014
#7673AD
#73500A
#B68296
#44353B

FEATURES

🌐

REST API SERVER

Run as HTTP server. POST images, get JSON colors back. CORS enabled.

📦

GO LIBRARY

Import as a package. ExtractFromFile(), ExtractFromImage(), GeneratePalette().

⚡

BLAZING FAST

Sub-300ms processing. Automatic image downscaling for speed.

🎯

K-MEANS++

Advanced clustering algorithm for accurate dominant color extraction.

📊

JSON OUTPUT

Machine-readable output with hex values and percentage weights.

🎨

PALETTE PNG

Generate visual palettes with proportional color blocks and hex labels.

🔧

FILTERS

Exclude white, black, or similar colors. Control minimum contrast.

💻

CROSS-PLATFORM

Single binary for macOS, Linux, and Windows. ARM64 supported.

SUPPORTED FORMATS

JPEG PNG WebP GIF BMP TIFF

API SERVER

$ swatchify serve --port 8080
🎨 Swatchify server starting on http://localhost:8080

$ curl -X POST -F "image=@photo.jpg" localhost:8080/extract
{
  "success": true,
  "colors": [
    {"hex": "#FF0000", "percentage": 34.5},
    {"hex": "#00FF00", "percentage": 21.0}
  ]
}

$ curl -X POST -F "image=@photo.jpg" -F "colors=8" \
     -F "exclude_white=true" localhost:8080/extract

GO LIBRARY

import "github.com/james-see/swatchify/pkg/swatchify"

// Extract colors from file
colors, err := swatchify.ExtractFromFile("photo.jpg", nil)

// With options
opts := &swatchify.Options{
    NumColors:    8,
    ExcludeWhite: true,
}
colors, _ := swatchify.ExtractFromFile("photo.jpg", opts)

// Generate palette
swatchify.GeneratePalette(colors, "palette.png", nil)

CLI FLAGS

-n, --colors     Number of colors (default: 5)
--json           Output as JSON
--png            Generate palette PNG
--exclude-white  Skip near-white colors
--exclude-black  Skip near-black colors
--min-contrast   Min distance between colors
--show           Open palette after creation
--quality        0-100, accuracy vs speed
--width          Palette width (default: 1000)
--height         Palette height (default: 200)

serve --port     Start API server on port