Module: RubyIdenticon

Defined in:
lib/ruby_identicon.rb,
lib/ruby_identicon/version.rb

Overview

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.

Constant Summary collapse

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.

{
  border_size: 35,
  square_size: 50,
  grid_size: 7,
  background_color: ChunkyPNG::Color::TRANSPARENT,
  key: "\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF"
}
VERSION = 
'0.0.4'

Class Method Summary collapse

Class Method Details

.create(title, options = {}) ⇒ Object

create an identicon png and return it as a binary string

Example:

>> RubyIdenticon.create('identicons are great!')
=> binary blob (String)

Parameters:

  • title (string) —

    the string value to be represented as an identicon

  • options (hash) (defaults to: {}) —

    additional options for the identicon



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# 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], y + options[:square_size], 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], y + options[:square_size], 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_and_save(title, filename, options = {}) ⇒ Object

create an identicon png and save it to the given filename

Example:

>> RubyIdenticon.create_and_save('identicons are great!', 'test_identicon.png')
=> result (Boolean)

Parameters:

  • title (string) —

    the string value to be represented as an identicon

  • filename (string) —

    the full path and filename to save the identicon png to

  • options (hash) (defaults to: {}) —

    additional options for the identicon



78
79
80
81
82
83
84
85
 
# 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

.create_base64(title, options = {}) ⇒ Object 



141
142
143
 
# File 'lib/ruby_identicon.rb', line 141

def self.create_base64(title, options = {})
  Base64.encode64(self.create(title, options)).force_encoding('UTF-8')
end