swift vibrant

Extract prominent colors from an image.

Swift

swift-vibrant

Generate a color palette from a UIImage.

Other color palette generators will only give you a list of the dominant colors in an image. Vibrant does much more.

Now I know what you’re thinking: “But Bryce, colors from an image! That’s what I want! That’s why I’m on your repository in the first place!”

Well I’ve got news for you: swift-vibrant (or node-vibrant, if you use JavaScript. No affiliation but that’s what this project is based off of) will not only give you the dominant colors in an image, oh no. It will also give you a fully featured palette. What’s the difference you might ask?

It provides:

A Vibrant Color (Duh)
A Muted Color
A Dark Vibrant Color
A Dark Muted Color
A Light Vibrant Color
A Light Muted Color

As well as 2 different text colors for each of the above that look good on the color they’re designed for.

Don’t believe me? There’s a 100% money back guarantee! (Just kidding, it’s MIT licensed aka free for your use).

Installation

swift-vibrant is available through CocoaPods. To install
it, simply add the following line to your Podfile:

pod 'swift-vibrant'

Usage

import swiftVibrant

let image = UIImage(named: "name_of_image")

// Calling from a background thread
Vibrant.from(image).getPalette({ palette in 
    // do stuff with your palette
})
// Calling in main thread
Vibrant.from(image).getPalette()
/// do stuff with your palette here

// Using constructor
let v = Vibrant(image, Vibrant.Options)
v.getPalette({ palette in 
    // do stuff with your palette
})

References

`Vibrant`

Main class of swift-vibrant.

`Vibrant.from(src: UIImage): Builder`

Make a Builder for an image. Returns a Builder instance.

`constructor(src: UIImage, opts: Vibrant.Options)`

Name	Description
`image`	Your UIImage instance
`opts`	Options (optional)

`Options`

public struct Options {
       var colorCount: Int = 64
       var quality: Int = 5
       var quantizer: Quantizer.quantizer
       var generator: Generator.generator
       var maxDimension: CGFloat?
       var filters: [Filter]
   }

Field	Default	Description
`colorCount`	64	amount of colors in initial palette from which the swatches will be generated
`quality`	5	Scale down factor used in downsampling stage. `1` means no downsampling. If `maxDimension` is set, this value will not be used.
`quantizer`	`Quantizer.defaultQuantizer`	A `Quantizer` function
`generator`	`Generator.defaultGenerator`	An `Generator` function
`maxDimension`	`nil`	The max size of the image’s longer side used in downsampling stage. This field will override `quality`.
`filters`	`[]`	An array of `Filter`

`quantizer`

public typealias quantizer = (_ pixels: [UInt8], _ options: Vibrant.Options)->[Swatch]

`generator`

public typealias generator = (_ swatches: [Swatch])->Palette

`Filter`

Returns true if the color is to be kept.

public class Filter {
    public typealias filterFunction = (_ red: UInt8, _ green: UInt8, _ blue: UInt8, _ alpha: UInt8)->Bool
    
    var f: filterFunction
}

`getPalette(cb: (Palette)->Void)`

Name	Description
`cb`	callback function.

`Vibrant.Builder`

Helper class for change configurations and create a Vibrant instance. Methods of a Builder instance can be chained like:

Vibrant.from(src)
  .quality(1)
  .clearFilters()
  // ...
  .getPalette()

`quality(q: Int): Builder`

Sets opts.quality to q. Returns this Builder instance.

`maxColorCount(n: Int): Builder`

Sets opts.colorCount to n. Returns this Builder instance.

`maxDimension(d: Int): Builder`

Sets opts.maxDimension to d. Returns this Builder instance.

`addFilter(f: Filter): Builder`

Adds a filter function. Returns this Builder instance.

`removeFilter(f: Filter): Builder`

Removes a filter function. Returns this Builder instance.

`clearFilters(): Builder`

Clear all filters. Returns this Builder instance.

`useQuantizer(quantizer: Quantizer.quantizer): Builder`

Specifies which Quantizer implementation class to use. Returns this Builder instance.

`useGenerator(generator: Generator.generator): Builder`

Sets opts.generator to generator. Returns this Builder instance.

`build(): Vibrant`

Builds and returns a Vibrant instance as configured.

`getPalette(cb: (Palette)->Void)`

Builds a Vibrant instance as configured and calls its getPalette method on a background thread. Calls cb on main thread.

`getPalette()->Palette`

Builds a Vibrant instance as configured and calls its getPalette method on the main thread.

`Vibrant.Swatch`

Represents a color swatch generated from an image’s palette.

`Vec3`

public typealias Vec3<T> = (T, T, T)

`RGB`

public typealias RGB = (r: UInt8, g: UInt8, b: UInt8)

`HSL`

public typealias HSL = (r: Double, g: Double, b: Double)

`XYZ`

public typealias HSL = (r: Double, g: Double, b: Double)

`LAB`

public typealias HSL = (r: Double, g: Double, b: Double)

`constructor(rgb: RGB, population: Int)`

Internal use.

Name	Description
`rgb`	`[r, g, b]`
`population`	Population of the color in an image

`hsl: HSL`

`getPopulation(): Int`

`rgb: RGB`

`hex: String`

Returns a hexadecimal value of the swatch

`getTitleTextColor(): UIColor`

Returns an appropriate color to use for any ‘title’ text which is displayed over this Swatch’s color.

`getBodyTextColor(): UIColor`

Returns an appropriate color to use for any ‘body’ text which is displayed over this Swatch’s color.

`Vibrant.Util`

Utility methods. Internal usage.

`hexToRgb(hex: string): RGB`

`rgbToHex(r: UInt8, g: UInt8, b: UInt8): String`

`hslToRgb(h: Double, s: Double, l: Double): RGB`

`rgbToHsl(r: UInt8, g: UInt8, b: UInt8): HSL`

`xyzToRgb(x: Double, y: Double, z: Double): RGB`

`rgbToXyz(r: UInt8, g: UInt8, b: UInt8): XYZ`

`xyzToCIELab(x: Double, y: Double, z: Double): LAB`

`rgbToCIELab(l: UInt8, a: UInt8, b: UInt8): LAB`

`deltaE94(lab1: Double, lab2: Double): Double`

Computes CIE delta E 1994 diff between lab1 and lab2. The 2 colors are in CIE-Lab color space. Used in tests to compare 2 colors’ perceptual similarity.

`rgbDiff(rgb1: RGB, rgb2: RGB): Double`

Compute CIE delta E 1994 diff between rgb1 and rgb2.

`hexDiff(hex1: String, hex2: String): Double`

Compute CIE delta E 1994 diff between hex1 and hex2.

`getColorDiffStatus(d: Double): String`

Gets a string to describe the meaning of the color diff. Used in tests.

Delta E	Perception	Returns
<= 1.0	Not perceptible by human eyes.	`"Perfect"`
1 - 2	Perceptible through close observation.	`"Close"`
2 - 10	Perceptible at a glance.	`"Good"`
11 - 49	Colors are more similar than opposite	`"Similar"`
50 - 100	Colors are exact opposite	`Wrong`

Notes

This library uses code from ColorThiefSwift, mostly borrowing from their implementation of the modified median cut quantization (MMCQ) algorithm
A majority of the rest was adapted from node-vibrant

Author

Bryce Dougherty: [email protected]

Credits

Kazuki Ohara: ColorThiefSwift

Jari Zwarts: node-vibrant

License

swiftVibrant is available under the MIT license. See the LICENSE file for more info.