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

--- /dev/null
+++ b/setup.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+# System packages this project needs on a clean Ubuntu machine.
+set -e
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y -qq --no-install-recommends libeigen3-dev

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

[
  {
    "category": "underspecification",
    "rule": "signature.missing_system_requirement",
    "source": "failure_signature",
    "excerpt": "Could not find a package configuration file provided by \"Eigen3\" (requested"
  },
  {
    "category": "underspecification",
    "rule": "diff.adds_external_environment_requirement",
    "source": "manifest_diff:setup.sh",
    "excerpt": "export DEBIAN_FRONTEND=noninteractive"
  },
  {
    "category": "underspecification",
    "rule": "diff.adds_external_environment_requirement",
    "source": "manifest_diff:setup.sh",
    "excerpt": "apt-get install -y -qq --no-install-recommends libeigen3-dev"
  }
]

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)

include(FetchContent)

# Fetch stb_image
FetchContent_Declare(
    stb
    GIT_REPOSITORY https://github.com/nothings/stb.git
    GIT_TAG master
)
FetchContent_MakeAvailable(stb)

# Find Eigen
find_package(Eigen3 3.4.0 REQUIRED)

add_executable(palette_extractor main.cpp)

target_include_directories(palette_extractor PRIVATE
    ${stb_SOURCE_DIR}
)

target_link_libraries(palette_extractor PRIVATE
    Eigen3::Eigen
)

/**
 * 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:
 *   - stb_image (FetchContent)
 *   - Eigen 3.4.0
 */

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

#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"

#include <Eigen/Dense>

// 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 stb_image.
 */
Eigen::MatrixXd loadPixels(const std::string& path, int maxPixels, int& width, int& height) {
    int channels;
    unsigned char* data = stbi_load(path.c_str(), &width, &height, &channels, 3);
    if (!data) {
        std::cerr << "Error: Could not read image: " << path << std::endl;
        exit(1);
    }

    int total = width * height;

    // Simple downsampling if too many pixels
    int step = 1;
    if (total > maxPixels) {
        step = static_cast<int>(std::ceil(std::sqrt(static_cast<double>(total) / maxPixels)));
    }

    int sampledW = (width + step - 1) / step;
    int sampledH = (height + step - 1) / step;
    int sampledTotal = sampledW * sampledH;

    std::cout << "Image size: " << width << "x" << height
              << " (" << total << " pixels, sampled to " << sampledTotal << ")" << std::endl;

    // Create Eigen matrix (N x 3)
    Eigen::MatrixXd pixels(sampledTotal, 3);
    int idx = 0;
    for (int y = 0; y < height; y += step) {
        for (int x = 0; x < width; x += step) {
            int offset = (y * width + x) * 3;
            pixels(idx, 0) = data[offset];
            pixels(idx, 1) = data[offset + 1];
            pixels(idx, 2) = data[offset + 2];
            idx++;
        }
    }
    pixels.conservativeResize(idx, 3);

    stbi_image_free(data);
    return pixels;
}

/**
 * Extract palette using k-means clustering with Eigen for computation.
 */
std::vector<ColorEntry> extractKMeans(const Eigen::MatrixXd& pixels, int numColors) {
    int n = pixels.rows();
    std::mt19937 rng(42);

    // K-means++ initialization
    Eigen::MatrixXd centers(numColors, 3);
    std::uniform_int_distribution<int> dist(0, n - 1);
    centers.row(0) = pixels.row(dist(rng));

    for (int k = 1; k < numColors; k++) {
        Eigen::VectorXd minDists(n);
        for (int i = 0; i < n; i++) {
            double best = std::numeric_limits<double>::max();
            for (int j = 0; j < k; j++) {
                double d = (pixels.row(i) - centers.row(j)).squaredNorm();
                best = std::min(best, d);
            }
            minDists(i) = best;
        }
        double totalDist = minDists.sum();
        double r = std::uniform_real_distribution<double>(0, totalDist)(rng);
        for (int i = 0; i < n; i++) {
            r -= minDists(i);
            if (r <= 0) {
                centers.row(k) = pixels.row(i);
                break;
            }
        }
    }

    // Iterate
    Eigen::VectorXi assignments(n);
    assignments.setZero();

    for (int iter = 0; iter < 100; iter++) {
        bool changed = false;
        for (int i = 0; i < n; i++) {
            int bestK = 0;
            double bestDist = std::numeric_limits<double>::max();
            for (int k = 0; k < numColors; k++) {
                double d = (pixels.row(i) - centers.row(k)).squaredNorm();
                if (d < bestDist) {
                    bestDist = d;
                    bestK = k;
                }
            }
            if (assignments(i) != bestK) {
                assignments(i) = bestK;
                changed = true;
            }
        }
        if (!changed) break;

        // Recompute centers using Eigen operations
        Eigen::MatrixXd sums = Eigen::MatrixXd::Zero(numColors, 3);
        Eigen::VectorXi counts = Eigen::VectorXi::Zero(numColors);
        for (int i = 0; i < n; i++) {
            int k = assignments(i);
            sums.row(k) += pixels.row(i);
            counts(k)++;
        }
        for (int k = 0; k < numColors; k++) {
            if (counts(k) > 0) {
                centers.row(k) = sums.row(k) / counts(k);
            }
        }
    }

    // Build palette
    Eigen::VectorXi counts = Eigen::VectorXi::Zero(numColors);
    for (int i = 0; i < n; i++) {
        counts(assignments(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>(std::round(centers(k, 0)))));
        entry.rgb[1] = std::max(0, std::min(255, static_cast<int>(std::round(centers(k, 1)))));
        entry.rgb[2] = std::max(0, std::min(255, static_cast<int>(std::round(centers(k, 2)))));
        entry.hex = rgbToHex(entry.rgb[0], entry.rgb[1], entry.rgb[2]);
        entry.proportion = std::round(static_cast<double>(counts(k)) / n * 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;
    }

    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 Eigen::MatrixXd& pixelMatrix, int numColors) {
    // Convert Eigen matrix to vector of vectors
    std::vector<std::vector<int>> pixels;
    for (int i = 0; i < pixelMatrix.rows(); i++) {
        pixels.push_back({
            static_cast<int>(pixelMatrix(i, 0)),
            static_cast<int>(pixelMatrix(i, 1)),
            static_cast<int>(pixelMatrix(i, 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;
}

// Simple JSON output (no nlohmann/json dependency -- using manual formatting)
std::string escapeJson(const std::string& s) {
    std::string out;
    for (char c : s) {
        if (c == '"') out += "\\\"";
        else if (c == '\\') out += "\\\\";
        else out += c;
    }
    return out;
}

std::string paletteToJson(const std::vector<ColorEntry>& palette, int indent = 4) {
    std::string pad(indent, ' ');
    std::string pad2(indent + 2, ' ');
    std::ostringstream oss;
    oss << "[\n";
    for (size_t i = 0; i < palette.size(); i++) {
        const auto& e = palette[i];
        oss << pad << "{\n"
            << pad2 << "\"rgb\": [" << e.rgb[0] << ", " << e.rgb[1] << ", " << e.rgb[2] << "],\n"
            << pad2 << "\"hex\": \"" << escapeJson(e.hex) << "\",\n"
            << pad2 << "\"proportion\": " << e.proportion << ",\n"
            << pad2 << "\"name\": \"" << escapeJson(e.name) << "\"\n"
            << pad << "}";
        if (i + 1 < palette.size()) oss << ",";
        oss << "\n";
    }
    oss << "  ]";
    return oss.str();
}

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 << ") - "
                  << std::fixed << std::setprecision(1) << (e.proportion * 100) << "%" << 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];
    }

    int width, height;
    std::cout << "Loading image: " << imagePath << std::endl;
    Eigen::MatrixXd pixels = loadPixels(imagePath, 100000, width, height);

    std::ostringstream jsonResult;
    jsonResult << "{\n";
    jsonResult << "  \"image\": \"" << escapeJson(imagePath) << "\",\n";
    jsonResult << "  \"num_colors\": " << numColors << ",\n";

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

        if (!comparePath.empty()) {
            int w2, h2;
            std::cout << "\nLoading comparison image: " << comparePath << std::endl;
            auto pixels2 = loadPixels(comparePath, 100000, w2, h2);
            auto palette2 = extractKMeans(pixels2, numColors);
            auto comparison = comparePalettes(kmeansPalette, palette2);
            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(pixels, numColors);
        jsonResult << "  \"median_cut\": " << paletteToJson(mcPalette) << "\n";
        printPalette("Median-Cut palette:", mcPalette);
    }

    jsonResult << "}\n";

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

    return 0;
}

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

Extracts dominant colors from images using k-means clustering and median-cut quantization with color naming and palette comparison.

## Dependencies

- **stb_image** (FetchContent) - Lightweight image loading
- **Eigen** 3.4.0 - Linear algebra for efficient k-means computation

## Build

```bash
mkdir build && cd build
cmake ..
cmake --build .
```

## Usage

```bash
./palette_extractor <image> [-n NUM] [-m METHOD] [--compare IMAGE2] [-o OUTPUT]
```