Contents

heestand-xyz/keycolor

Find key colors in images.

Install

.package(url: "https://github.com/heestand-xyz/KeyColor", from: "1.0.1")

Example

guard let image = UIImage(named: "My Image") else { return }
let color: Color? = try await image.keyColor()
let colors: [Color] = try await image.keyColors(3)

If the image is monochrome no colors will be returned.

The default saturation and brightness thresholds are at 50%.

Functions

SwiftUI Color

extension UIImage {
    
    func keyColor(
        minSaturation: CGFloat = 0.5,
        minBrightness: CGFloat = 0.5,
        resolution: CGSize? = CGSize(width: 100, height: 100),
        interpolation: Graphic.ResolutionInterpolation = .lanczos
    ) async throws -> Color?
    
    func keyColors(
        _ maxCount: Int,
        minSaturation: CGFloat = 0.5,
        minBrightness: CGFloat = 0.5,
        resolution: CGSize? = CGSize(width: 100, height: 100),
        interpolation: Graphic.ResolutionInterpolation = .lanczos
    ) async throws -> [Color]
}

Both UIImage and NSImage are supported.

PixelColor

extension Graphic {
    
    func keyPixelColor(
        minSaturation: CGFloat = 0.5,
        minBrightness: CGFloat = 0.5,
        resolution: CGSize? = CGSize(width: 100, height: 100),
        interpolation: Graphic.ResolutionInterpolation = .lanczos
    ) async throws -> PixelColor?
    
    func keyPixelColors(
        _ maxCount: Int,
        minSaturation: CGFloat = 0.5,
        minBrightness: CGFloat = 0.5,
        resolution: CGSize? = CGSize(width: 100, height: 100),
        interpolation: Graphic.ResolutionInterpolation = .lanczos
    ) async throws -> [PixelColor]
}

Color locations

Use a live Graphic directly to get colors and the pixels they came from:

let samples = try await graphic.keyColorSamples(
    5,
    minSaturation: 0.25,
    minBrightness: 0.25
)
for sample in samples {
    let color = sample.color.color
    let point = sample.location
}

Each KeyColorSample contains a PixelColor and a normalized CGPoint. Coordinates run from the top-left (0, 0) to the bottom-right (1, 1) and refer to pixel centers in the sampled image. They remain normalized when the image is downsampled. Thresholds are strict; only colors above both minimums qualify. The selector returns fewer than the requested count when the image has fewer distinct qualifying colors.

Stable live colors

Pass the previous unfiltered selections back into the sampler to retain palette order and nearby locations until another candidate wins by a meaningful margin. The match must be within 0.25 RGB distance of the previous color; missing colors are replaced by current qualifying pixels. Exact ties use image scan order, so the same image and history always give the same result.

Then low-pass filter the selected colors and locations independently:

var previous: [KeyColorSample] = []
var filter = KeyColorFilter(colorResponse: 0.25, locationResponse: 0.2)

// For each live graphic:
let samples = try await graphic.keyColorSamples(
    5,
    minSaturation: 0.25,
    minBrightness: 0.25,
    previousSamples: previous,
    replacementMargin: 0.08
)
previous = samples
let displayedSamples = filter.update(with: samples)

The replacement margin is measured in saturation for the first palette slot, and RGB distance from the selected palette for subsequent slots. Passing no history performs ordinary selection. Smaller filter response values give smoother, slower updates; 1 follows each sample immediately. Color filtering uses the shortest hue path and averages saturation and brightness separately, preserving their thresholds without mixing complementary colors into gray. Reset the history and filter when the source changes or rotates.

Powered by PixelColor and AsyncGraphics

Package Metadata

Repository: heestand-xyz/keycolor

Default branch: main

README: README.md