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.


Add this line to your application's Gemfile:

gem 'borealis'

And then execute:

$ bundle

Or install it yourself as:

$ gem install borealis


Find the three prominent colors in an image:'image/path.jpg').colors # Returns 3 colors with hex and rgb attributes'image/path.jpg').hexes # Returns 3 hex values'image/path.jpg').rgbs # Returns 3 rgb values

Easily get color values out of a color:

color =
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 =, 255, 255)
cyan.to_lab #=> [91.11652110946342, -48.079618466228716, -14.138127754846131]

Change the defaults:

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


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.


Default: 3

The number of colors you want returned.


Default: 3


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:

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


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


Borealis is copyright 2013 Josh Steiner and thoughtbot, inc., and may be redistributed under the terms specified in the LICENSE file.