Image Color Palette Extractor (cpp, written by Claude Code)

Claude Code wrote this cpp project from the task below. It does not run on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: Image Color Palette Extractor

Write a program that extracts the dominant color palette from images using color quantization algorithms, outputting the palette in multiple formats with percentage breakdowns.

FUNCTIONAL REQUIREMENTS:
- Accept an image file path as a command-line argument
- Extract a configurable number of dominant colors via --colors flag (default: 8, range 2-32)
- Use k-means clustering or median cut algorithm for color quantization (selectable via --algorithm flag)
- Output each color in multiple formats: hex (#RRGGBB), RGB (r,g,b), and HSL (h,s%,l%)
- Report the percentage of the image each dominant color represents
- Support color name mapping: find the closest named CSS/HTML color for each extracted color
- Generate a color palette visualization as a PNG image showing color swatches with hex labels via --visual flag
- Support extracting palette from a specific region of the image via --crop flag (x,y,width,height)
- Support color space analysis: report if the image is primarily warm-toned, cool-toned, or neutral based on the palette hue distribution
- Compare palettes between two images via --compare flag, showing common colors and unique colors with delta-E color difference scores
- Print the palette to console as a formatted table with color swatches represented by ANSI colored blocks
- Save the palette data as JSON with --output flag (default: palette.json)
- Support batch extraction from a directory of images via --batch flag with a summary showing all palettes
- If no input is given, generate three sample images (a sunset scene using warm gradients, an ocean scene using cool gradients, a forest scene using green tones), extract palettes from each, and display comparative results
- Handle errors: unsupported formats, very small images, images with very few unique colors

Create a complete C++ project for a clean Ubuntu 22.04 machine with only G++ 12+ and CMake 3.22+ installed. Include:
- Source code
- CMakeLists.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

cmake_minimum_required(VERSION 3.14)
project(palette_extractor VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# ---------------------------------------------------------------------------
# Dependencies
# ---------------------------------------------------------------------------
# OpenCV 4.9.0 — Image loading, color conversion, k-means clustering
# nlohmann/json 3.11.3 — Modern JSON for C++
# ---------------------------------------------------------------------------

# OpenCV (must be installed on the system)
find_package(OpenCV 4.9.0 REQUIRED COMPONENTS core imgcodecs imgproc)

# nlohmann/json via FetchContent
include(FetchContent)

FetchContent_Declare(
    nlohmann_json
    GIT_REPOSITORY https://github.com/nlohmann/json.git
    GIT_TAG        v3.11.3
    GIT_SHALLOW    TRUE
)

set(JSON_BuildTests OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(nlohmann_json)

# ---------------------------------------------------------------------------
# Executable
# ---------------------------------------------------------------------------

add_executable(palette_extractor main.cpp)

target_link_libraries(palette_extractor PRIVATE
    ${OpenCV_LIBS}
    nlohmann_json::nlohmann_json
)

target_include_directories(palette_extractor PRIVATE
    ${OpenCV_INCLUDE_DIRS}
)

if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    target_compile_options(palette_extractor PRIVATE -Wall -Wextra -Wpedantic)
endif()

/**
 * Image Color Palette Extractor
 *
 * Extracts dominant colors from images using k-means clustering and median-cut
 * quantization. Provides color naming and palette comparison functionality.
 *
 * Dependencies:
 *   - OpenCV 4.9.0
 *   - nlohmann/json 3.11.3
 */

#include <algorithm>
#include <cmath>
#include <cstdlib>
#include <fstream>
#include <iostream>
#include <limits>
#include <map>
#include <numeric>
#include <sstream>
#include <string>
#include <vector>

#include <opencv2/opencv.hpp>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

// Named CSS3 colors
struct NamedColor {
    std::string name;
    int r, g, b;
};

static const std::vector<NamedColor> CSS3_COLORS = {
    {"black", 0, 0, 0}, {"white", 255, 255, 255}, {"red", 255, 0, 0},
    {"lime", 0, 255, 0}, {"blue", 0, 0, 255}, {"yellow", 255, 255, 0},
    {"cyan", 0, 255, 255}, {"magenta", 255, 0, 255}, {"silver", 192, 192, 192},
    {"gray", 128, 128, 128}, {"maroon", 128, 0, 0}, {"olive", 128, 128, 0},
    {"green", 0, 128, 0}, {"purple", 128, 0, 128}, {"teal", 0, 128, 128},
    {"navy", 0, 0, 128}, {"orange", 255, 165, 0}, {"pink", 255, 192, 203},
    {"coral", 255, 127, 80}, {"salmon", 250, 128, 114}, {"gold", 255, 215, 0},
    {"khaki", 240, 230, 140}, {"violet", 238, 130, 238}, {"indigo", 75, 0, 130},
    {"turquoise", 64, 224, 208}, {"chocolate", 210, 105, 30},
    {"crimson", 220, 20, 60}, {"tomato", 255, 99, 71},
    {"steelblue", 70, 130, 180}, {"skyblue", 135, 206, 235},
    {"darkgreen", 0, 100, 0}, {"darkred", 139, 0, 0},
    {"beige", 245, 245, 220}, {"lavender", 230, 230, 250},
    {"peru", 205, 133, 63}, {"firebrick", 178, 34, 34},
    {"deeppink", 255, 20, 147}, {"limegreen", 50, 205, 50},
    {"midnightblue", 25, 25, 112}, {"wheat", 245, 222, 179},
    {"snow", 255, 250, 250},
};

struct ColorEntry {
    int rgb[3];
    std::string hex;
    double proportion;
    std::string name;
};

struct ComparisonResult {
    double avg_distance_a_to_b;
    double avg_distance_b_to_a;
    double symmetric_distance;
    double similarity;
    std::vector<std::string> common_color_names;
    int palette_a_size;
    int palette_b_size;
};

double colorDistance(const int* c1, const int* c2) {
    return std::sqrt(
        std::pow(c1[0] - c2[0], 2) +
        std::pow(c1[1] - c2[1], 2) +
        std::pow(c1[2] - c2[2], 2)
    );
}

std::string rgbToHex(int r, int g, int b) {
    char buf[8];
    std::snprintf(buf, sizeof(buf), "#%02x%02x%02x",
        std::max(0, std::min(255, r)),
        std::max(0, std::min(255, g)),
        std::max(0, std::min(255, b)));
    return std::string(buf);
}

std::string nameColor(int r, int g, int b) {
    std::string bestName = "unknown";
    double bestDist = std::numeric_limits<double>::max();
    int c1[3] = {r, g, b};
    for (const auto& nc : CSS3_COLORS) {
        int c2[3] = {nc.r, nc.g, nc.b};
        double d = colorDistance(c1, c2);
        if (d < bestDist) {
            bestDist = d;
            bestName = nc.name;
        }
    }
    return bestName;
}

/**
 * Load image pixels using OpenCV, resizing if needed.
 */
cv::Mat loadPixels(const std::string& path, int maxPixels = 100000) {
    cv::Mat img = cv::imread(path, cv::IMREAD_COLOR);
    if (img.empty()) {
        std::cerr << "Error: Could not read image: " << path << std::endl;
        exit(1);
    }

    int total = img.rows * img.cols;
    if (total > maxPixels) {
        double scale = std::sqrt(static_cast<double>(maxPixels) / total);
        int newW = std::max(1, static_cast<int>(img.cols * scale));
        int newH = std::max(1, static_cast<int>(img.rows * scale));
        cv::resize(img, img, cv::Size(newW, newH), 0, 0, cv::INTER_AREA);
    }

    std::cout << "Image size: " << img.cols << "x" << img.rows
              << " (" << img.rows * img.cols << " pixels)" << std::endl;

    // Convert BGR to RGB
    cv::cvtColor(img, img, cv::COLOR_BGR2RGB);
    return img;
}

/**
 * Extract palette using OpenCV's k-means.
 */
std::vector<ColorEntry> extractKMeans(const cv::Mat& img, int numColors) {
    cv::Mat samples = img.reshape(1, img.rows * img.cols);
    cv::Mat floatSamples;
    samples.convertTo(floatSamples, CV_32F);

    cv::Mat labels, centers;
    cv::kmeans(floatSamples, numColors, labels,
               cv::TermCriteria(cv::TermCriteria::EPS + cv::TermCriteria::MAX_ITER, 100, 0.2),
               10, cv::KMEANS_PP_CENTERS, centers);

    // Count pixels per cluster
    std::vector<int> counts(numColors, 0);
    int totalPixels = labels.rows;
    for (int i = 0; i < totalPixels; i++) {
        counts[labels.at<int>(i)]++;
    }

    std::vector<ColorEntry> palette;
    for (int k = 0; k < numColors; k++) {
        ColorEntry entry;
        entry.rgb[0] = std::max(0, std::min(255, static_cast<int>(centers.at<float>(k, 0))));
        entry.rgb[1] = std::max(0, std::min(255, static_cast<int>(centers.at<float>(k, 1))));
        entry.rgb[2] = std::max(0, std::min(255, static_cast<int>(centers.at<float>(k, 2))));
        entry.hex = rgbToHex(entry.rgb[0], entry.rgb[1], entry.rgb[2]);
        entry.proportion = std::round(static_cast<double>(counts[k]) / totalPixels * 10000.0) / 10000.0;
        entry.name = nameColor(entry.rgb[0], entry.rgb[1], entry.rgb[2]);
        palette.push_back(entry);
    }

    std::sort(palette.begin(), palette.end(),
              [](const ColorEntry& a, const ColorEntry& b) {
                  return a.proportion > b.proportion;
              });
    return palette;
}

/**
 * Median-cut recursive split.
 */
void medianCutSplit(std::vector<std::vector<int>>& pixels, int depth,
                    std::vector<std::pair<std::vector<int>, int>>& results) {
    if (depth == 0 || pixels.empty()) {
        if (!pixels.empty()) {
            long sumR = 0, sumG = 0, sumB = 0;
            for (const auto& px : pixels) {
                sumR += px[0]; sumG += px[1]; sumB += px[2];
            }
            int n = static_cast<int>(pixels.size());
            results.push_back({
                {static_cast<int>(sumR / n), static_cast<int>(sumG / n), static_cast<int>(sumB / n)},
                n
            });
        }
        return;
    }

    // Find channel with greatest range
    int mins[3] = {255, 255, 255};
    int maxs[3] = {0, 0, 0};
    for (const auto& px : pixels) {
        for (int c = 0; c < 3; c++) {
            mins[c] = std::min(mins[c], px[c]);
            maxs[c] = std::max(maxs[c], px[c]);
        }
    }
    int bestChannel = 0, bestRange = 0;
    for (int c = 0; c < 3; c++) {
        int range = maxs[c] - mins[c];
        if (range > bestRange) {
            bestRange = range;
            bestChannel = c;
        }
    }

    int ch = bestChannel;
    std::sort(pixels.begin(), pixels.end(),
              [ch](const std::vector<int>& a, const std::vector<int>& b) {
                  return a[ch] < b[ch];
              });

    size_t mid = pixels.size() / 2;
    std::vector<std::vector<int>> left(pixels.begin(), pixels.begin() + mid);
    std::vector<std::vector<int>> right(pixels.begin() + mid, pixels.end());

    medianCutSplit(left, depth - 1, results);
    medianCutSplit(right, depth - 1, results);
}

std::vector<ColorEntry> extractMedianCut(const cv::Mat& img, int numColors) {
    std::vector<std::vector<int>> pixels;
    for (int y = 0; y < img.rows; y++) {
        for (int x = 0; x < img.cols; x++) {
            cv::Vec3b px = img.at<cv::Vec3b>(y, x);
            pixels.push_back({px[0], px[1], px[2]});
        }
    }

    int depth = static_cast<int>(std::ceil(std::log2(std::max(numColors, 2))));
    std::vector<std::pair<std::vector<int>, int>> results;
    medianCutSplit(pixels, depth, results);

    std::sort(results.begin(), results.end(),
              [](const auto& a, const auto& b) { return a.second > b.second; });

    int totalPixels = static_cast<int>(pixels.size());
    std::vector<ColorEntry> palette;
    for (int i = 0; i < std::min(numColors, static_cast<int>(results.size())); i++) {
        ColorEntry entry;
        entry.rgb[0] = std::max(0, std::min(255, results[i].first[0]));
        entry.rgb[1] = std::max(0, std::min(255, results[i].first[1]));
        entry.rgb[2] = std::max(0, std::min(255, results[i].first[2]));
        entry.hex = rgbToHex(entry.rgb[0], entry.rgb[1], entry.rgb[2]);
        entry.proportion = std::round(static_cast<double>(results[i].second) / totalPixels * 10000.0) / 10000.0;
        entry.name = nameColor(entry.rgb[0], entry.rgb[1], entry.rgb[2]);
        palette.push_back(entry);
    }
    return palette;
}

/**
 * Compare two palettes.
 */
ComparisonResult comparePalettes(const std::vector<ColorEntry>& paletteA,
                                  const std::vector<ColorEntry>& paletteB) {
    auto avgMinDist = [](const std::vector<ColorEntry>& src,
                         const std::vector<ColorEntry>& tgt) -> double {
        if (src.empty()) return 0;
        double total = 0;
        for (const auto& s : src) {
            double minDist = std::numeric_limits<double>::max();
            for (const auto& t : tgt) {
                double d = colorDistance(s.rgb, t.rgb);
                minDist = std::min(minDist, d);
            }
            total += minDist;
        }
        return total / src.size();
    };

    double aToB = avgMinDist(paletteA, paletteB);
    double bToA = avgMinDist(paletteB, paletteA);
    double symmetric = (aToB + bToA) / 2.0;
    double maxDist = std::sqrt(255.0 * 255.0 * 3.0);
    double similarity = std::max(0.0, 1.0 - symmetric / maxDist);

    std::set<std::string> namesA, namesB;
    for (const auto& e : paletteA) namesA.insert(e.name);
    for (const auto& e : paletteB) namesB.insert(e.name);

    std::vector<std::string> common;
    std::set_intersection(namesA.begin(), namesA.end(),
                          namesB.begin(), namesB.end(),
                          std::back_inserter(common));

    ComparisonResult result;
    result.avg_distance_a_to_b = std::round(aToB * 100.0) / 100.0;
    result.avg_distance_b_to_a = std::round(bToA * 100.0) / 100.0;
    result.symmetric_distance = std::round(symmetric * 100.0) / 100.0;
    result.similarity = std::round(similarity * 10000.0) / 10000.0;
    result.common_color_names = common;
    result.palette_a_size = static_cast<int>(paletteA.size());
    result.palette_b_size = static_cast<int>(paletteB.size());
    return result;
}

json paletteToJson(const std::vector<ColorEntry>& palette) {
    json arr = json::array();
    for (const auto& e : palette) {
        arr.push_back({
            {"rgb", {e.rgb[0], e.rgb[1], e.rgb[2]}},
            {"hex", e.hex},
            {"proportion", e.proportion},
            {"name", e.name}
        });
    }
    return arr;
}

void printPalette(const std::string& title, const std::vector<ColorEntry>& palette) {
    std::cout << title << std::endl;
    for (const auto& e : palette) {
        std::cout << "  " << e.hex << " (" << e.name << ") - "
                  << static_cast<int>(e.proportion * 100) << "."
                  << static_cast<int>(e.proportion * 1000) % 10 << "%" << std::endl;
    }
}

int main(int argc, char* argv[]) {
    if (argc < 2) {
        std::cout << "Usage: palette_extractor <image> [options]" << std::endl;
        std::cout << "Options:" << std::endl;
        std::cout << "  -n <num>        Number of colors (default: 6)" << std::endl;
        std::cout << "  -m <method>     Method: kmeans, median-cut, both (default: both)" << std::endl;
        std::cout << "  --compare <img> Compare with second image" << std::endl;
        std::cout << "  -o <file>       Output JSON file" << std::endl;
        return 0;
    }

    std::string imagePath = argv[1];
    int numColors = 6;
    std::string method = "both";
    std::string comparePath;
    std::string outputPath;

    for (int i = 2; i < argc; i++) {
        std::string arg = argv[i];
        if (arg == "-n" && i + 1 < argc) numColors = std::atoi(argv[++i]);
        else if (arg == "-m" && i + 1 < argc) method = argv[++i];
        else if (arg == "--compare" && i + 1 < argc) comparePath = argv[++i];
        else if (arg == "-o" && i + 1 < argc) outputPath = argv[++i];
    }

    std::cout << "Loading image: " << imagePath << std::endl;
    cv::Mat img = loadPixels(imagePath);

    json result;
    result["image"] = imagePath;
    result["num_colors"] = numColors;

    if (method == "kmeans" || method == "both") {
        std::cout << "Extracting palette using k-means clustering..." << std::endl;
        auto kmeansPalette = extractKMeans(img, numColors);
        result["kmeans"] = paletteToJson(kmeansPalette);
        printPalette("K-Means palette:", kmeansPalette);

        if (!comparePath.empty()) {
            std::cout << "\nLoading comparison image: " << comparePath << std::endl;
            cv::Mat img2 = loadPixels(comparePath);
            auto palette2 = extractKMeans(img2, numColors);
            auto comparison = comparePalettes(kmeansPalette, palette2);
            result["comparison"] = {
                {"avg_distance_a_to_b", comparison.avg_distance_a_to_b},
                {"avg_distance_b_to_a", comparison.avg_distance_b_to_a},
                {"symmetric_distance", comparison.symmetric_distance},
                {"similarity", comparison.similarity},
                {"common_color_names", comparison.common_color_names},
                {"palette_a_size", comparison.palette_a_size},
                {"palette_b_size", comparison.palette_b_size}
            };
            std::cout << "\nPalette comparison:" << std::endl;
            std::cout << "  Similarity: " << comparison.similarity * 100 << "%" << std::endl;
            std::cout << "  Symmetric distance: " << comparison.symmetric_distance << std::endl;
        }
    }

    if (method == "median-cut" || method == "both") {
        std::cout << "Extracting palette using median-cut quantization..." << std::endl;
        auto mcPalette = extractMedianCut(img, numColors);
        result["median_cut"] = paletteToJson(mcPalette);
        printPalette("Median-Cut palette:", mcPalette);
    }

    if (!outputPath.empty()) {
        std::ofstream outFile(outputPath);
        outFile << result.dump(2) << std::endl;
        std::cout << "\nResults saved to " << outputPath << std::endl;
    }

    return 0;
}

# Image Color Palette Extractor (C++ - Trial 1)

Extracts dominant colors from images using k-means clustering and median-cut quantization. Uses OpenCV for image I/O and k-means, and nlohmann/json for structured JSON output with color naming and palette comparison.

## Dependencies

- **OpenCV** (4.9.0) - Image loading, color space conversion, and k-means clustering
- **nlohmann/json** (3.11.3) - Modern JSON library for structured palette output

## Build

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
```

### Prerequisites

On Ubuntu/Debian:

```bash
sudo apt-get install -y libopencv-dev cmake g++ git
```

## Usage

```bash
# Extract palette from an image
./build/palette_extractor image.png

# Specify number of colors and method
./build/palette_extractor image.png -n 8 -m kmeans

# Compare palettes between two images
./build/palette_extractor image1.png --compare image2.png

# Save results to JSON
./build/palette_extractor image.png -o palette.json
```

## Features

- K-means clustering via OpenCV for fast, accurate palette extraction
- Median-cut quantization as an alternative method
- Color naming using nearest CSS3 color matching
- Palette comparison between two images with similarity scoring
- JSON output via nlohmann/json