Borealis

Borealis finds the most prominent colors in an image, attempting to find colors that are distinct from one another.

It provides defaults which favor speed, but the defaults are easily changed if you prefer accuracy. For most purposes, the default settings should be accurate enough.

Installation

Add this line to your application's Gemfile:

gem 'borealis'

And then execute:

$ bundle

Or install it yourself as:

$ gem install borealis

Usage

Find the three prominent colors in an image:

Borealis.new('image/path.jpg').colors # Returns 3 colors with hex and rgb attributes
Borealis.new('image/path.jpg').hexes # Returns 3 hex values
Borealis.new('image/path.jpg').rgbs # Returns 3 rgb values

Easily get color values out of a color:

color = Borealis.new(file).colors.first
color.rgb # "(222, 2, 15)"
color.hex # "#DE020F"

Measure distance between colors:

orange.rgb_distance_to red #=> 127.0
orange.lab_distance_to red #=> 39.79252198414681

maroon.rgb_distance_to dark_red #=> 11.0
maroon.lab_distance_to dark_read #=> 5.071593528474779

Calculate CIE-L*a*b* value of an sRGB color:

cyan = Borealis::Color.new(0, 255, 255)
cyan.to_lab #=> [91.11652110946342, -48.079618466228716, -14.138127754846131]

Change the defaults:

borealis = Borealis.new('image/path.jpg',
  size: '150x150',
  colors: 3,
  delta: 0.001,
  static: false
)

Size

Default: '50x50'

Size takes any Image Geometry that imagemagick handles.

For more accurate results, use a larger image. However, this comes at a severe time cost.

Colors

Default: 3

The number of colors you want returned.

Iterations

Default: 3

Static

Default: true

Static determines whether the color output will be the same each time given the same image. Use false if you want the colors to change each run.

How does it work?

Borealis uses the k-means clustering algorithm, which in this case:

Takes n colors from the image as cluster centers
Adds the rest of the colors to the cluster which they are closest to
Finds the average color in each cluster, setting the results as new cluster centers
Empties each cluster, except for the new center, and repeats steps 2-3 until convergance has been reached

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request