Color Namer Ruby

Give me a color and I'll name it.

Color Namer Ruby is an ruby gem package for use in ruby or other projects that provides names for colours based on calculated color distances using the Delta-E color difference technique. Given a color in Hexadecimal, RGA(A), HSL(A), HSV, HSB, or CMYK format, it converts the color to the HSL color space (for now), then calculates the color's Euclidean distance from a set of colors with known names to find the closest matching colour and it's name.

Mike Bostock of D3 fame explains it well:

Lab and HCL color spaces are special in that the perceived difference between two colors is proportional to their Euclidean distance in color space. This special property, called perceptual uniformity, makes them ideal for accurate visual encoding of data. In contrast, the more familiar RGB and HSL color spaces distort data when used for visualization.

The color names are derived from several lists:

• roygbiv
• basic
• html - the HTML color names.
• x11 - The list that preceded the HTML color names
• pantone
• ntc, an astounding collection of over 1500 named colors.

Install the gem and add to the application's Gemfile by executing:

bundle add color_name_ruby

If bundler is not being used to manage dependencies, install the gem by executing:

gem install color_name_ruby

Get a single name for a colour using .get_name by passing a colour in a way that ColorConversion accepts. When passing colours with their properties assigned to keys, you need to pass nil or an empty string as the first parameter.

ColorNamerRuby::Namer.get_name('#3672b4')
=> 'Azure'

ColorNamerRuby::Namer.get_name('', r: 70, g: 130, b: 180, a: 0.5)
=> 'steelblue'

ColorNamerRuby:Namer.get_name('', r: 130, g: 180, b: 70)
=> 'Sushi'

ColorNamerRuby:Namer.get_name('', h: 20, s: 73, l: 20)
=> 'Cioccolato'

ColorNamerRuby:Namer.get_name(nil, h: 107, s: 61, v: 71)
=> 'Apple'

ColorNamerRuby::Namer.get_name(nil, h: 61, s: 71, b: 32)
=> 'Camouflage'

ColorNamerRuby::Namer.get_name(nil, c: 71, m: 15, y: 5, k: 54)
=> 'Blue Dianne'

ColorNamerRuby::Namer.get_name('rgb(51, 102, 204)')
=> 'Denim'

ColorNamerRuby::Namer.get_name('hsl(225, 73%, 57%)')
=> 'royalblue'

Get a list of colour names sorted by their perceptual similarity to the given color by using .get_names. Again, when passing colours with their properties assigned to keys, you need to pass nil or an empty string as the first parameter.

ColorNamerRuby::Namer.get_names('#3672b4')
=> [
=>   { name: 'Azure', hex: '#315BA1', distance: 8.660254037844387 },
=>   { name: 'St Tropaz', hex: '#2D569B', distance: 9.9498743710662 },
=>   { name: 'Denim', hex: '#2B6CC4', distance: 10.816653826391969 },
=>   { name: 'steelblue', hex: '#4682B4', distance: 11.180339887498949 },
=>   { name: 'Steel Blue', hex: '#4682B4', distance: 11.180339887498949 },
=>   .
=>   .
=>   .
=> ]

Get a list of the colour lists that can be checked against.

ColorNamerRuby::Namer.list_names
=> ['basic', 'html', 'ntc', 'pantone', 'roygbiv', 'x11']

This parameter allows you to filter names from the dedicated lists for faster computation. It can be used for both get_name and get_names.

ColorNamerRuby::Namer.get_names('#3672b4', pick: ['basic', 'x11'])

The opposite of options.pick. It can be used for both get_name and get_names.

ColorNamerRuby::Namer.get_names('#3672b4', omit: ['pantone', 'roygbiv'])

This option allows us to limit the number of names that are returned to keep the returned output manageable. It can be used for get_names (since get_name already has a limit of 1).

ColorNamerRuby::Namer.get_names('#3672b4', limit: 5)

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/louiswdavis/color_namer_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the ColorNamerRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.