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

Claude Code wrote this java 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 Java project for a clean Ubuntu 22.04 machine with only JDK 17+ installed. Include:
- Source code
- pom.xml with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

import java.awt.image.BufferedImage;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.util.*;
import java.util.stream.Collectors;
import javax.imageio.ImageIO;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import org.apache.commons.math3.ml.clustering.CentroidCluster;
import org.apache.commons.math3.ml.clustering.DoublePoint;
import org.apache.commons.math3.ml.clustering.KMeansPlusPlusClusterer;

/**
 * Image Color Palette Extractor
 *
 * Extracts dominant colors from images using k-means clustering and median-cut
 * quantization. Provides color naming and palette comparison.
 *
 * Dependencies:
 *   - javax.imageio (built-in)
 *   - commons-math3 3.6.1
 *   - Gson 2.10.1
 */
public class PaletteExtractor {

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

    static class ColorEntry {
        int[] rgb;
        String hex;
        double proportion;
        String name;

        ColorEntry(int[] rgb, double proportion) {
            this.rgb = rgb;
            this.hex = String.format("#%02x%02x%02x", rgb[0], rgb[1], rgb[2]);
            this.proportion = Math.round(proportion * 10000.0) / 10000.0;
            this.name = nameColor(rgb);
        }
    }

    static class ComparisonResult {
        double avgDistanceAtoB;
        double avgDistanceBtoA;
        double symmetricDistance;
        double similarity;
        List<String> commonColorNames;
        int paletteSizeA;
        int paletteSizeB;
    }

    static class ExtractionResult {
        String image;
        int numColors;
        List<ColorEntry> kmeans;
        List<ColorEntry> medianCut;
        ComparisonResult comparison;
    }

    /**
     * Load image pixels as an array of [r, g, b] arrays.
     */
    public static int[][] loadPixels(String path, int maxPixels) throws IOException {
        BufferedImage img = ImageIO.read(new File(path));
        if (img == null) {
            throw new IOException("Could not read image: " + path);
        }

        int w = img.getWidth();
        int h = img.getHeight();
        int total = w * h;

        // Resize if too large
        if (total > maxPixels) {
            double scale = Math.sqrt((double) maxPixels / total);
            int newW = Math.max(1, (int)(w * scale));
            int newH = Math.max(1, (int)(h * scale));
            BufferedImage resized = new BufferedImage(newW, newH, BufferedImage.TYPE_INT_RGB);
            resized.getGraphics().drawImage(
                img.getScaledInstance(newW, newH, java.awt.Image.SCALE_SMOOTH), 0, 0, null
            );
            img = resized;
            w = newW;
            h = newH;
            total = w * h;
        }

        System.out.printf("Image size: %dx%d (%d pixels)%n", w, h, total);

        int[][] pixels = new int[total][3];
        for (int y = 0; y < h; y++) {
            for (int x = 0; x < w; x++) {
                int rgb = img.getRGB(x, y);
                int idx = y * w + x;
                pixels[idx][0] = (rgb >> 16) & 0xFF;
                pixels[idx][1] = (rgb >> 8) & 0xFF;
                pixels[idx][2] = rgb & 0xFF;
            }
        }
        return pixels;
    }

    /**
     * K-means palette extraction using commons-math3.
     */
    public static List<ColorEntry> extractKMeans(int[][] pixels, int nColors) {
        List<DoublePoint> points = new ArrayList<>(pixels.length);
        for (int[] px : pixels) {
            points.add(new DoublePoint(new double[]{px[0], px[1], px[2]}));
        }

        KMeansPlusPlusClusterer<DoublePoint> clusterer =
            new KMeansPlusPlusClusterer<>(nColors, 300);
        List<CentroidCluster<DoublePoint>> clusters = clusterer.cluster(points);

        List<ColorEntry> palette = new ArrayList<>();
        int totalPoints = pixels.length;
        for (CentroidCluster<DoublePoint> cluster : clusters) {
            double[] center = cluster.getCenter().getPoint();
            int[] rgb = {
                (int) Math.round(center[0]),
                (int) Math.round(center[1]),
                (int) Math.round(center[2])
            };
            // Clamp to valid range
            for (int i = 0; i < 3; i++) {
                rgb[i] = Math.max(0, Math.min(255, rgb[i]));
            }
            double proportion = (double) cluster.getPoints().size() / totalPoints;
            palette.add(new ColorEntry(rgb, proportion));
        }

        palette.sort((a, b) -> Double.compare(b.proportion, a.proportion));
        return palette;
    }

    /**
     * Median-cut quantization.
     */
    public static List<ColorEntry> extractMedianCut(int[][] pixels, int nColors) {
        int depth = (int) Math.ceil(Math.log(Math.max(nColors, 2)) / Math.log(2));
        List<int[][]> groups = new ArrayList<>();
        List<Integer> counts = new ArrayList<>();
        medianCutSplit(pixels, depth, groups, counts);

        // Sort by group size
        List<int[]> results = new ArrayList<>();
        for (int i = 0; i < groups.size(); i++) {
            int[][] group = groups.get(i);
            long sumR = 0, sumG = 0, sumB = 0;
            for (int[] px : group) {
                sumR += px[0]; sumG += px[1]; sumB += px[2];
            }
            int len = group.length;
            results.add(new int[]{(int)(sumR / len), (int)(sumG / len), (int)(sumB / len), len});
        }
        results.sort((a, b) -> Integer.compare(b[3], a[3]));

        int totalPixels = pixels.length;
        List<ColorEntry> palette = new ArrayList<>();
        for (int i = 0; i < Math.min(nColors, results.size()); i++) {
            int[] r = results.get(i);
            int[] rgb = {
                Math.max(0, Math.min(255, r[0])),
                Math.max(0, Math.min(255, r[1])),
                Math.max(0, Math.min(255, r[2]))
            };
            palette.add(new ColorEntry(rgb, (double) r[3] / totalPixels));
        }
        return palette;
    }

    private static void medianCutSplit(int[][] pixels, int depth,
                                        List<int[][]> groups, List<Integer> counts) {
        if (depth == 0 || pixels.length == 0) {
            if (pixels.length > 0) {
                groups.add(pixels);
                counts.add(pixels.length);
            }
            return;
        }

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

        final int ch = bestChannel;
        Arrays.sort(pixels, Comparator.comparingInt(a -> a[ch]));
        int mid = pixels.length / 2;

        medianCutSplit(Arrays.copyOfRange(pixels, 0, mid), depth - 1, groups, counts);
        medianCutSplit(Arrays.copyOfRange(pixels, mid, pixels.length), depth - 1, groups, counts);
    }

    /**
     * Find the closest CSS3 color name.
     */
    public static String nameColor(int[] rgb) {
        String bestName = "unknown";
        double bestDist = Double.MAX_VALUE;
        for (Map.Entry<String, int[]> entry : CSS3_COLORS.entrySet()) {
            int[] ref = entry.getValue();
            double dist = Math.sqrt(
                Math.pow(rgb[0] - ref[0], 2) +
                Math.pow(rgb[1] - ref[1], 2) +
                Math.pow(rgb[2] - ref[2], 2)
            );
            if (dist < bestDist) {
                bestDist = dist;
                bestName = entry.getKey();
            }
        }
        return bestName;
    }

    /**
     * Compare two palettes.
     */
    public static ComparisonResult comparePalettes(List<ColorEntry> paletteA,
                                                    List<ColorEntry> paletteB) {
        double aToB = avgMinDistance(paletteA, paletteB);
        double bToA = avgMinDistance(paletteB, paletteA);
        double symmetric = (aToB + bToA) / 2.0;
        double maxDist = Math.sqrt(255 * 255 * 3);
        double similarity = Math.max(0.0, 1.0 - symmetric / maxDist);

        Set<String> namesA = paletteA.stream().map(e -> e.name).collect(Collectors.toSet());
        Set<String> namesB = paletteB.stream().map(e -> e.name).collect(Collectors.toSet());
        namesA.retainAll(namesB);

        ComparisonResult result = new ComparisonResult();
        result.avgDistanceAtoB = Math.round(aToB * 100.0) / 100.0;
        result.avgDistanceBtoA = Math.round(bToA * 100.0) / 100.0;
        result.symmetricDistance = Math.round(symmetric * 100.0) / 100.0;
        result.similarity = Math.round(similarity * 10000.0) / 10000.0;
        result.commonColorNames = new ArrayList<>(namesA);
        Collections.sort(result.commonColorNames);
        result.paletteSizeA = paletteA.size();
        result.paletteSizeB = paletteB.size();
        return result;
    }

    private static double avgMinDistance(List<ColorEntry> source, List<ColorEntry> target) {
        double total = 0;
        for (ColorEntry s : source) {
            double minDist = Double.MAX_VALUE;
            for (ColorEntry t : target) {
                double dist = Math.sqrt(
                    Math.pow(s.rgb[0] - t.rgb[0], 2) +
                    Math.pow(s.rgb[1] - t.rgb[1], 2) +
                    Math.pow(s.rgb[2] - t.rgb[2], 2)
                );
                minDist = Math.min(minDist, dist);
            }
            total += minDist;
        }
        return source.isEmpty() ? 0 : total / source.size();
    }

    public static void main(String[] args) throws IOException {
        if (args.length < 1) {
            System.out.println("Usage: PaletteExtractor <image> [options]");
            System.out.println("Options:");
            System.out.println("  -n <num>        Number of colors (default: 6)");
            System.out.println("  -m <method>     Method: kmeans, median-cut, both (default: both)");
            System.out.println("  --compare <img> Compare with second image");
            System.out.println("  -o <file>       Output JSON file");
            return;
        }

        String imagePath = args[0];
        int numColors = 6;
        String method = "both";
        String comparePath = null;
        String outputPath = null;

        for (int i = 1; i < args.length; i++) {
            switch (args[i]) {
                case "-n": numColors = Integer.parseInt(args[++i]); break;
                case "-m": method = args[++i]; break;
                case "--compare": comparePath = args[++i]; break;
                case "-o": outputPath = args[++i]; break;
            }
        }

        System.out.println("Loading image: " + imagePath);
        int[][] pixels = loadPixels(imagePath, 100000);

        ExtractionResult result = new ExtractionResult();
        result.image = imagePath;
        result.numColors = numColors;

        if (method.equals("kmeans") || method.equals("both")) {
            System.out.println("Extracting palette using k-means clustering...");
            result.kmeans = extractKMeans(pixels, numColors);
            System.out.println("K-Means palette:");
            for (ColorEntry entry : result.kmeans) {
                System.out.printf("  %s (%s) - %.1f%%%n",
                    entry.hex, entry.name, entry.proportion * 100);
            }
        }

        if (method.equals("median-cut") || method.equals("both")) {
            System.out.println("Extracting palette using median-cut quantization...");
            result.medianCut = extractMedianCut(pixels, numColors);
            System.out.println("Median-Cut palette:");
            for (ColorEntry entry : result.medianCut) {
                System.out.printf("  %s (%s) - %.1f%%%n",
                    entry.hex, entry.name, entry.proportion * 100);
            }
        }

        if (comparePath != null) {
            System.out.println("\nLoading comparison image: " + comparePath);
            int[][] pixels2 = loadPixels(comparePath, 100000);
            List<ColorEntry> palette2 = extractKMeans(pixels2, numColors);
            List<ColorEntry> palette1 = result.kmeans != null ? result.kmeans
                : extractKMeans(pixels, numColors);
            result.comparison = comparePalettes(palette1, palette2);
            System.out.printf("%nPalette comparison:%n");
            System.out.printf("  Similarity: %.2f%%%n", result.comparison.similarity * 100);
            System.out.printf("  Symmetric distance: %.2f%n", result.comparison.symmetricDistance);
            System.out.printf("  Common colors: %s%n",
                String.join(", ", result.comparison.commonColorNames));
        }

        if (outputPath != null) {
            Gson gson = new GsonBuilder().setPrettyPrinting().create();
            try (FileWriter writer = new FileWriter(outputPath)) {
                writer.write(gson.toJson(result));
            }
            System.out.println("\nResults saved to " + outputPath);
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.palette</groupId>
    <artifactId>palette-extractor</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>Image Color Palette Extractor</name>
    <description>
        Extracts dominant colors from images using k-means clustering and
        median-cut quantization with color naming and palette comparison.
    </description>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-math3</artifactId>
            <version>3.6.1</version>
        </dependency>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.10.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.3.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>PaletteExtractor</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

# Image Color Palette Extractor (Java - Trial 1)

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

## Dependencies

- **javax.imageio** (built-in) - Image loading and pixel access
- **commons-math3 3.6.1** - K-means++ clustering algorithm
- **Gson 2.10.1** - JSON serialization for output

## Build

```bash
mvn clean package
```

## Usage

```bash
# Extract palette using both methods (default 6 colors)
java -jar target/palette-extractor-1.0.0.jar image.png

# Extract 8 colors using k-means only
java -jar target/palette-extractor-1.0.0.jar image.png -n 8 -m kmeans

# Compare two images and save output
java -jar target/palette-extractor-1.0.0.jar image1.png --compare image2.png -o result.json
```

## Output

JSON output includes RGB values, hex codes, proportion, and named colors for each dominant color.