DominantColors

A library for extracting color from an image. Сurrent version 1.1.8

• Features
• How to use
• Contrast colors
• Average colors
• Cluster colors
• Installation
• Example
• How the algorithm works
• Contributing
• License

Features

The DominantColors makes it easy to find the dominant colors of the image. It returns a color palette of the most common colors in the image.

How to use

Standard settings

A quick way to get colors from an image where the image type is CGImage, UIImage or NSImage:

let dominantColors = try? image.dominantColors(max: 6) // Array of UIColor, NSColor or CGColor

If you need more settings, then call the method directly from the library according to the standard settings:

// Get the CGColors according to the standard settings:
let cgColors = try? DominantColors.dominantColors(image: cgImage, maxCount: 6)

// Get the UIColors according to the standard settings
let uiColors = try? DominantColors.dominantColors(uiImage: uiImage, maxCount: 6)

// Get the NSColors according to the standard settings:
let nsColors = try? DominantColors.dominantColors(nsImage: nsImage, maxCount: 6)

// Get the `Color.Resolved` according to the standard settings:
let colorsResolved =  try? DominantColors.dominantColorsResolved(image: cgImage)

Custom settings

Next examples are given for CGColor, but this is also true for UIColor and NSColor

Algorithm settings

Get colors by selecting algorithm. Extract colors by specifying the color difference formula:

let cgColors = try? DominantColors.dominantColors(image: cgImage, algorithm: .CIE76)

If you need more accurate results, then there is maximum quality (the default is fair):

let cgColors = try? DominantColors.dominantColors(image: cgImage, quality: .best, algorithm: .CIE76)

To quickly extract colors, use:

let cgColors = try? DominantColors.dominantColors(image: cgImage, quality: .fair)

In this case, a pixelization algorithm is used for the original image.

Options settings

Get colors with options:

let cgColors = try? DominantColors.dominantColors(image: cgImage, options: [.excludeBlack, .excludeGray, .excludeWhite])

Sorting settings

For the desired sequence and colors, specify the sorting type:

let cgColors = try? DominantColors.dominantColors(image: cgImage, maxCount: 6, sorting: .darkness)

The default is frequency, which sorts colors in descending order of their number of pixels with that color.

Average colors

Get the average color by dividing the image into segments horizontally:

let cgColors = try? DominantColors.averageColors(image: cgImage, count: 8)

Cluster colors

Finds the dominant colors of an image by using a k-means clustering algorithm:

let cgColors = try? DominantColors.kMeansClusteringColors(image: cgImage, quality: .fair, count: 10)

Contrast colors

In order to obtain colors for displaying text or accompanying content based on the palette of the ordered image, you must use ContrastColors:

let dominantColors = try image.dominantColors()
let contrastColors = ContrastColors(colors: dominantColors.map({ $0.cgColor }))

let backgroundColor = contrastColors?.background 
let primaryColor = contrastColors?.primary
let secondaryColor = contrastColors?.secondary

You can get this result used backgroundColor for background, primaryColor for title and secondaryColor for subtitle:

Example

macOS

• PreviewMacOS in package,
• App MacOSPreview in example folder.

iOS

• PreviewiOS in package,
• App iOSDominantColorsPreview in example folder.

Installation

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding DominantColors as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/DenDmitriev/DominantColors.git", .upToNextMajor(from: "1.1.8"))
]

How the algorithm works

The original image is converted according to the specified quality.

Low

One color is taken from each generated pixel.

Source	Resize	Pixellate

Fair

One color is taken from each generated pixel.

Source	Resize	Pixellate

High

One color is taken from each generated pixel.

Source	Resize	Pixellate

Best

Each pixel color is taken without changing the image.

Next, the colors are sorted by ColorShade and color normality is calculated using the number of pixels of the same color and normal saturation and brightness values. After sorting, each shade bin connects the colors by calculating сolor difference. This happens cyclically until the required number of flowers is in the basket. The next step is to connect the colors between the baskets in the same way until you have the required number of colors. Well, the result is displayed.

Contributing

Contribution to the DominantColors is always welcome. To get information about errors and feature requests, open the issue. To contribute to the codebase, just send a pull request.

License

See the license. The library uses the code of the original library ColorKit, which is rewritten from Objective-C to Swift and supplemented.