module RubyIdenticon
A Ruby implementation of go-identicon
RubyIdenticon
creates an Identicon, similar to those created by Github.
A title and key are used by siphash to calculate a hash value that is then used to create a visual identicon representation.
The identicon is made by creating a left hand side pixel representation of each bit in the hash value - this is then mirrored onto the right hand side to create an image that we see as a shape.
The grid and square sizes can be varied to create identicons of differing size.
Constants
- DEFAULT_OPTIONS
the default options used when creating identicons
background_color: (Integer, default 0) the background color of the identicon in rgba notation (e.g. xffffffff for white) border_size: (Integer, default 35) the size in pixels to leave as an empty border around the identicon image grid_size: (Integer, default 7) the number of rows and columns in the identicon, minimum 4, maximum 9 square_size: (Integer, default 50) the size in pixels of each square that makes up the identicon key: (String) a 16 byte key used by siphash when calculating the hash value (see note below)
varying the key ensures uniqueness of an identicon for a given title, it is assumed desirable for different applications to use a different key.
- VERSION
Public Class Methods
create an identicon png and return it as a binary string
Example:
>> RubyIdenticon.create('identicons are great!') => binary blob (String)
@param title [string] the string value to be represented as an identicon @param options [hash] additional options for the identicon
# File lib/ruby_identicon.rb, line 96 def self.create(title, options = {}) options = DEFAULT_OPTIONS.merge(options) raise 'title cannot be nil' if title == nil raise 'key is nil or less than 16 bytes' if options[:key] == nil || options[:key].length < 16 raise 'grid_size must be between 4 and 9' if options[:grid_size] < 4 || options[:grid_size] > 9 raise 'invalid border size' if options[:border_size] < 0 raise 'invalid square size' if options[:square_size] < 0 hash = SipHash.digest(options[:key], title) png = ChunkyPNG::Image.new((options[:border_size] * 2) + (options[:square_size] * options[:grid_size]), (options[:border_size] * 2) + (options[:square_size] * options[:grid_size]), options[:background_color]) # set the foreground color by using the first three bytes of the hash value color = ChunkyPNG::Color.rgba((hash & 0xff), ((hash >> 8) & 0xff), ((hash >> 16) & 0xff), 0xff) # remove the first three bytes that were used for the foreground color hash >>= 24 sqx = sqy = 0 (options[:grid_size] * ((options[:grid_size] + 1) / 2)).times do if hash & 1 == 1 x = options[:border_size] + (sqx * options[:square_size]) y = options[:border_size] + (sqy * options[:square_size]) # left hand side png.rect(x, y, x + options[:square_size] - 1, y + options[:square_size] - 1, color, color) # mirror right hand side x = options[:border_size] + ((options[:grid_size] - 1 - sqx) * options[:square_size]) png.rect(x, y, x + options[:square_size] - 1, y + options[:square_size] - 1, color, color) end hash >>= 1 sqy += 1 if sqy == options[:grid_size] sqy = 0 sqx += 1 end end png.to_blob color_mode: ChunkyPNG::COLOR_INDEXED end
create an identicon png and save it to the given filename
Example:
>> RubyIdenticon.create_and_save('identicons are great!', 'test_identicon.png') => result (Boolean)
@param title [string] the string value to be represented as an identicon @param filename [string] the full path and filename to save the identicon png to @param options [hash] additional options for the identicon
# File lib/ruby_identicon.rb, line 78 def self.create_and_save(title, filename, options = {}) raise 'filename cannot be nil' if filename == nil blob = create(title, options) return false if blob == nil File.open(filename, 'wb') { |f| f.write(blob) } end
# File lib/ruby_identicon.rb, line 141 def self.create_base64(title, options = {}) Base64.encode64(self.create(title, options)).force_encoding('UTF-8') end