AvatarGenerator

A github style deterministic avatar generator for Ruby applications.

AvatarGenerator generates unique avatars from identifiers such as email addresses, usernames, or any other string. The same identifier always produces the same avatar, while different identifiers produce different avatars.

AvatarGenerator.generate("email@example.com")

Features

  • Deterministic avatar generation
  • Same identifier always produces the same avatar
  • Different identifiers generate different avatars
  • Custom image size
  • Custom background color
  • PNG output
  • Save generated avatars to the filesystem
  • Base64 and Data URL output
  • IO and binary blob access
  • Configurable storage and public paths

Examples

Examples generated by this library

Installation

Add the gem to your Gemfile:

gem  "avatar_generator"

Or install it directly:

gem  install  avatar_generator

Basic Usage

Generate an avatar using an identifier:

avatar = AvatarGenerator.generate("email@example.com")

The same identifier always generates the same avatar:

avatar1 = AvatarGenerator.generate("email@example.com")
avatar2 = AvatarGenerator.generate("email@example.com")
avatar1.base64 == avatar2.base64
# => true

Save an Avatar

By default, avatars are saved using a hash-based filename:

avatar = AvatarGenerator.generate("email@example.com")
avatar.save

You can also provide your own filename: avatar.save("your name"). It will use your_name.png.

The default storage directory is: public/avatars

Image Size

The default image size is 250x250. You can specify a custom size:

AvatarGenerator.generate("email@example.com", size:  300)

The generated image will be 300x300. Image size must be at least 5 to properly calculate the grid

Background Color

Default color is #FFFFFF. You can specify a custom background color:

AvatarGenerator.generate("email@example.com", background:  "#F5F5F5")

Base64

Get the generated image as a Base64-encoded string:

avatar = AvatarGenerator.generate("email@example.com")
avatar.base64

Data URL

Get a browser-compatible Data URL: avatar.data_url

Example:

data:image/png;base64,iVBORw0KGgo...

This can be used directly in an HTML image:

<img src="data:image/png;base64,..." />

Blob

Get the generated image as binary data: avatar.blob

IO

Get the generated image as a StringIO object: avatar.io

This can be useful when integrating with libraries that expect an IO-like object.

File Path and URL

Get the filesystem path: avatar.path

Example: public/avatars/7f83b1657ff1fc53b92dc18148a1d65d.png

Get the public URL: avatar.url

Example: /avatars/7f83b1657ff1fc53b92dc18148a1d65d.png

Rails Usage

AvatarGenerator can be used as a simple avatar generator in Rails applications. For example:

class  User < ApplicationRecord
  def avatar
AvatarGenerator.generate(email)
  end
end

Then in a Rails view:

 <%= image_tag user.avatar.url %>
 # or
 <img  src="<%=  AvatarGenerator.generate(user.user_name).data_url  %>">

Or generate and save the avatar:

user.avatar.save

If you run rails generate avatar_generator:install it will give you a configure file in your rails initializer.

AvatarGenerator.configure  do |config|
  config.size = 500
  config.background = "#FFFFFF"
  config.storage_path = "public/avatars"
  config.public_path = "/avatars"
end

Individual avatars can override configured defaults:

AvatarGenerator.generate("user_name", size:  500,background:  "#000000")

Testing

Clone the repository and install dependencies:

bundle  install

Run the test suite:

bundle  exec  rspec

License

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