getpal

README

getpal

getpal is a command line app for creating color palettes by sampling images.

It loads a PNG image (MUST be PNG) and returns a list of color values representing the main colors of the image to stdout. This can be redirected to a file or piped to another app. It also optionally creates an image containing a sample swatch of each color if found.

The app uses k-means clustering to find clusters of similar colors and returns the average of each cluster.

Usage:

getpal <input image path> [flags]

Flags:

  -m, --method string    which method to use to choose the best color from each cluster: random, closest, average (default "average")
  -n, --number int       how many colors to put in the palette (default 5)
  -r, --resolution int   the sampling resolution to use. 1 will read every pixel (default 4)
  -s, --swatch string    png file name to write palette swatches
  -v, --version          print version of getpal

By default getpal will sample every 4th row and column of pixels. This speeds things up and still is relatively accurate. You can set an alternate resolution with the -r flag. A resolution of 1 will sample every single pixel in the image and can take a long time, especially with a large palette size.

If you specify a swatch path with the -s flag, getpal will create a png image containing a sample swatch of each color in the resulting palette.

Methods

The --method or -m argument determines how specific colors are chosen for each palette entry.

In all cases, all the sampled pixels from the image are sorted into a number of clusters determined by the --number or -n argument. Each cluster will contain pixels that the algoritm has determined are similar.

If method is average, getpal will return the average color for each given cluster. This may not be a color that is actually in the image.

If method is closest, getpal will return the color in each cluster that is closest to the average of that cluster. This is guaranteed to be an actual color in the image.

If method is random, getpal will return a random color in each cluster. This is guaranteed to be an actual color in the image, but is non-deterministic. In other words, you will get a different palette each time you run getpal with the same arguments. The clusters will be the same each time, but you'll get a different value from each cluster. The other methods are deterministic, i.e. they will always return the same palette for the same arguments.

Example:

getpal image.png -n 6 -r 2 -s palette.png > palette.csv

This will sample image.png at a resolution of 2 pixels, creating a palette of 6 colors, saving the palette images in palette.png, and will output the palette values as comma separated strings in the file palette.csv.

Install:

Via go: go install codeberg.org/bit101/getpal

Or check out this repo and build.

You'll need pkg-config and cairographics installed.

Binaries

Binaries for mac and linux are in the releases.

You'll still have to install the cairographics library. Details at https://cairographics.org

Documentation

Overview

Package main renders an image or video