Inker

Inker is a Ruby gem for color parsing and manipulation, which allows to parse a HEX, RGB/RGBA and HSL/HSLA color string and provides functionalities for getting more info on color, like brigthness, lightness, saturation, hue. It also allows to change RGBA values in order to obtain new colors.

Installation

Add this line to your application's Gemfile:

gem 'inker'

And then execute:

bundle

Or install it yourself as:

gem install inker

Parsing colors

There're 2 different ways to parse colors with Inker. The first (most direct and simple) is to use String#to_color method, which returns a Inker::Color object. The other is by calling Inker#color, which has the same effect as String#to_color.

require "inker"

"magenta".to_color                   # parse a named color
"#880e4f".to_color                   # parse a hex6 color
"#000".to_color                      # parse a hex3 color
"#b71c1c99".to_color                 # parse a hex8 color (the last 2 chars chars represent alpha value)
"rgb(74, 20, 140)".to_color          # parse a RGB color
"rgba(26, 35, 126, 0.75)".to_color   # parse a RGBA color
"hsl(174, 100%, 29%)".to_color       # parse a HSL color with percentages
"hsl(174, 1.0, 0.29)".to_color       # parse a HSL color with decimals
"hsla(21, 100%, 45%, 0.5)".to_color  # parse a HSLA color with percentages
"hsla(21, 1.0, 0.45, 0.5)".to_color  # parse a HSLA color with decimals

Inker.color("magenta")               # parse a named color
Inker.color("#880e4f")               # parse a hex6 color
Inker.color("rgb(74, 20, 140)")      # parse a rgb color

Output formats

Inker::Color#to_s by default outputs the color in HEX format when called, but there're different output formats you can choose from.

require "inker"

# convert named color to HEX
"magenta".to_color.hex                             #=> "#ff00ff"
"magenta".to_color.to_s                            #=> "#ff00ff"

# convert HEX color to RGB
"#880e4f".to_color.rgb                              #=> "rgb(136, 14, 79)"
"#880e4f".to_color.to_s(:rgb)                       #=> "rgb(136, 14, 79)"

# convert HEX color to RGBA
"#b71c1c99".to_color.rgba                           #=> "rgba(183, 28, 28, 0.6)"
"#b71c1c99".to_color.to_s(:rgba)                    #=> "rgba(183, 28, 28, 0.6)"

# convert RGB color to HEX (the last forces alpha channel presence)
"rgb(74, 20, 140)".to_color.to_s                    #=> "#4a148c"
"rgb(74, 20, 140)".to_color.hex                     #=> "#4a148c"
"rgb(74, 20, 140)".to_color.hex(force_alpha: true)  #=> "#4a148cff"

# convert RGBA to HEX (the last ignores alpha channel)
"rgba(26, 35, 126, 0.75)".to_color.to_s             #=> "#1a237ebf"
"rgba(26, 35, 126, 0.75)".to_color.hex              #=> "#1a237ebf"
"rgba(26, 35, 126, 0.75)".to_color.hex6             #=> "#1a237e"

# convert HSL to HEX, RGB and RGBA
"hsl(174, 100%, 29%)".to_color.to_s                 #=> "#009485"
"hsl(174, 100%, 29%)".to_color.hex                  #=> "#009485"
"hsl(174, 100%, 29%)".to_color.rgb                  #=> "rgb(0, 148, 133)"
"hsl(174, 100%, 29%)".to_color.rgba                 #=> "rgb(0, 148, 133, 1.0)"

# convert HSLA to HEX, RGB and RGBA
"hsla(21, 100%, 45%, 0.5)".to_color.to_s            #=> "#e650007f"
"hsla(21, 100%, 45%, 0.5)".to_color.hex             #=> "#e650007f"
"hsla(21, 100%, 45%, 0.5)".to_color.hex6            #=> "#e65000"
"hsla(21, 100%, 45%, 0.5)".to_color.rgb             #=> "rgb(230, 80, 0)"
"hsla(21, 100%, 45%, 0.5)".to_color.rgba            #=> "rgba(230, 80, 0, 0.5)"

Features

Inker implements some useful features for getting useful color info an color manipulation.

Instance methods

Method name	Description
#red	Returns the value of red component in range 0-255
#red=	Allows to set a new value for red component in range 0-255
#green	Returns the value of green component in range 0-255
#green=	Allows to set a new value for green component in range 0-255
#blue	Returns the value of blue component in range 0-255
#blue=	Allows to set a new value for blue component in range 0-255
#alpha	Returns the value of alpha component in range 0.0-1.0
#alpha=	Allows to set a new value for alpha component in range 0.0-1.0
#brightness	Returns the brightness of the color in range 0-255
#dark?	Returns a boolean (true when color is dark)
#light?	Returns a boolean (true when color is light)
#lightness	Returns the lightness of the color in range 0.0-1.0
#saturation	Returns the saturation of the color in range 0.0-1.0
#hue	Retursn the value of HUE component of the color in range 0-360
#contrast_ratio(other_color)	Calculates the contrast ratio between current color end other_color [1-21]. A good contrast should return a value between 4.5 and 21.
#overlay(other_color)	Calculates the result of the overlay between current color end other_color

Class methods

Method name	Description
Inker::Color.from_rgb(Integer, Integer, Integer)	Create a new Inker::Color instance from RGB components values
Inker::Color.from_rgba(Integer, Integer, Integer, Float)	Same as Inker::Color.from_rgb, but has also the alpha component
Inker::Color.from_hsl(Integer, Float, Float)	Create a new Inker::Color instance from HSL components (Saturation and Lightness in range 0.0-1.0)
Inker::Color.from_hsla(Integer, Float, Float, Float)	Same as Inker::Color.from_hsl, but has also the alpha component
Inker::Color.from_custom_string(String, options)	Generate a new Inker::Color from a custom string, by getting HEX characters from MD5 digest of input string. By setting :position option you can change the index of target HEX chars that are used for HEX color generation. (default position: [0, 29, 14, 30, 28, 31])
Inker::Color.random	Generate a random Inker::Color instance
Inker::Color.contrast_ratio(color1, color2)	Calculates the contrast ratio between two colors and returns a value in range [1-21]. Colors could be specified as Inker::Color instances or strings.
Inker::Color.overlay(color1, color)	Calculates the result of the overlay between two colors and returns a new Inker::Color instance.

Development

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 tags, and push the .gem file to rubygems.org.

Contributing

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

License

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

Code of Conduct

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