Skip to main content
Version: main

Colour extraction

Tinct uses K-means clustering to extract meaningful colours from images. This page explains how the extraction process works.

K-means clustering​

K-means is an unsupervised machine learning algorithm that groups similar colours together. Tinct applies it to images as follows:

  1. Sampling: Read all pixels from the image
  2. Clustering: Group similar colours into K clusters (default: 16)
  3. Centroids: Calculate the centre colour of each cluster
  4. Weighting: Assign weights based on cluster size (colour frequency)

The result is a palette of representative colours with relative importance weights.

Configuring extraction​

Control the number of colours extracted:

# Extract 8 colours
tinct extract -i image -p ~/wallpaper.jpg -c 8

# Extract 24 colours
tinct extract -i image -p ~/wallpaper.jpg -c 24

Seed modes​

Tinct supports different seed modes for deterministic or varied results:

ModeDescription
contentSeed based on image content (default)
filepathSeed based on file path
manualUse a specific seed value
randomRandom seed each time
# Deterministic based on content
tinct generate -i image -p ~/wallpaper.jpg --image.seed content

# Random results
tinct generate -i image -p ~/wallpaper.jpg --image.seed random

Ambient edge extraction​

For monitor bias lighting and LED strip synchronisation, tinct can extract colours from image edges:

tinct generate -i image -p ~/wallpaper.jpg \
  --image.extractAmbience \
  --image.ambienceRegions 8

Region configurations​

RegionsPositions
4top, right, bottom, left
8corners and edges
12corners, edges, and inner points
16Full grid including centre positions

Sampling methods​

MethodDescription
averageAverage colour of the edge region
dominantMost common colour in the region
tinct generate -i image -p ~/wallpaper.jpg \
  --image.extractAmbience \
  --image.ambienceRegions 8 \
  --image.samplingMethod dominant

Remote image support​

Tinct can fetch and cache images from URLs:

tinct generate -i image -p "https://example.com/wallpaper.jpg" -o all

Images are cached locally for subsequent runs. Configure caching with environment variables:

export TINCT_IMAGE_CACHE=true
export TINCT_IMAGE_CACHE_DIR=~/.cache/tinct/images
export TINCT_IMAGE_CACHE_OVERWRITE=false

Colour weights​

Extracted colours include weights representing their prominence in the source:

  • Weights are normalised to sum to 1.0
  • Larger clusters (more pixels) have higher weights
  • Weights influence role assignment priority

Next steps​