avatar_generator 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c093a5daee6091591ceb86c0e5f7e8e5cf6f9fa09711a2ae07015e6ca19586d
+  data.tar.gz: 7d62181466ae0d8b1ff3b1dfc02fda753642305e35f4064eb221ff254de641e9
+SHA512:
+  metadata.gz: e61cc2c182a380cb9c8ef317c7d1624a60ba892153dee54648128bdb95d0eb624564eafe964c2cc8152a3d9e99c033c7b3927ad5253fc93acbdc792c75f68a3a
+  data.tar.gz: 0eda3faea365e85d446e6d034afa1237814a5d8706b5fdd2439812a6217809690490ec0efb2c822c4a7fc7d6c27a6edc68b19342933441283f05760b45c46961

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-07
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"gravatar" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["salmanmahmud2014@gmail.com"](mailto:"salmanmahmud2014@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Salman Mahmud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+# 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.
+
+```ruby
+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](./gravatar.png)
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem  "avatar_generator"
+```
+
+Or install it directly:
+
+```bash
+gem  install  avatar_generator
+
+```
+
+## Basic Usage
+
+Generate an avatar using an identifier:
+
+```ruby
+avatar = AvatarGenerator.generate("email@example.com")
+
+```
+
+The same identifier always generates the same avatar:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+AvatarGenerator.generate("email@example.com", background:  "#F5F5F5")
+```
+
+## Base64
+
+Get the generated image as a Base64-encoded string:
+
+```ruby
+avatar = AvatarGenerator.generate("email@example.com")
+avatar.base64
+
+```
+
+## Data URL
+
+Get a browser-compatible Data URL: `avatar.data_url`
+
+Example:
+
+```text
+data:image/png;base64,iVBORw0KGgo...
+```
+
+This can be used directly in an HTML image:
+
+```html
+<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:
+
+```ruby
+class  User < ApplicationRecord
+  def avatar
+	AvatarGenerator.generate(email)
+  end
+end
+```
+
+Then in a Rails view:
+
+```erb
+ <%= image_tag user.avatar.url %>
+ # or
+ <img  src="<%=  AvatarGenerator.generate(user.user_name).data_url  %>">
+```
+
+Or generate and save the avatar:
+
+```ruby
+user.avatar.save
+```
+
+If you run `rails generate avatar_generator:install` it will give you a configure file in your rails initializer.
+
+```ruby
+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:
+
+```ruby
+AvatarGenerator.generate("user_name", size:  500,background:  "#000000")
+```
+
+## Testing
+
+Clone the repository and install dependencies:
+
+```bash
+bundle  install
+```
+
+Run the test suite:
+
+```bash
+bundle  exec  rspec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/avatar_generator.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "lib/avatar_generator/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "avatar_generator"
+  spec.version = AvatarGenerator::VERSION
+
+  spec.authors = ["Salman Mahmud"]
+  spec.email = ["salmanmahmud2014@gmail.com"]
+
+  spec.summary = "Github style avatar generator for Ruby applications"
+  spec.description = <<~DESCRIPTION
+    avatar_generator is a github style deterministic avatar generator for Ruby applications.
+    It generates unique, consistent avatars from identifiers such as
+    usernames, email addresses, or other unique values. The same identifier
+    always produces the same avatar.
+  DESCRIPTION
+
+  spec.homepage = "https://github.com/salmanx/avatar_generator"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] =
+    "https://github.com/salmanx/avatar_generator"
+  spec.metadata["changelog_uri"] =
+    "https://github.com/salmanx/avatar_generator/releases"
+  spec.metadata["bug_tracker_uri"] =
+    "https://github.com/salmanx/avatar_generator/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "{lib,sig}/**/*",
+      "README.md",
+      "LICENSE.txt",
+      "CHANGELOG.md",
+      "CODE_OF_CONDUCT.md",
+      "*.gemspec",
+      "Rakefile",
+    ]
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "base64"
+  spec.add_dependency "chunky_png"
+end

data/lib/avatar_generator/avatar.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  class Avatar
+    def initialize(image, identifier:)
+      @image_data = image
+      @identifier = identifier
+    end
+
+    def image
+      @image ||= Renderer.render(@image_data)
+    end
+
+    def save(filename = nil)
+      filename ||= self.filename
+      filename = sanitize_filename(filename)
+
+      file_path = File.join(
+        AvatarGenerator.configuration.storage_path,
+        filename
+      )
+
+      FileUtils.mkdir_p(
+        File.dirname(file_path)
+      )
+
+      image.save(file_path)
+
+      file_path
+    end
+
+    def path
+      File.join(
+        AvatarGenerator.configuration.storage_path,
+        filename
+      )
+    end
+
+    def url
+      File.join(
+        AvatarGenerator.configuration.public_path,
+        filename
+      )
+    end
+
+    def filename
+      "#{identifier_hash}.png"
+    end
+
+    def blob
+      image.to_blob
+    end
+
+    def io
+      StringIO.new(blob)
+    end
+
+    def base64
+      Base64.strict_encode64(blob)
+    end
+
+    def data_url
+      "data:image/png;base64,#{base64}"
+    end
+
+    private
+
+    def identifier_hash
+      Digest::MD5.hexdigest(
+        @identifier.downcase.strip
+      )
+    end
+
+    def sanitize_filename(filename)
+      name = File.basename(filename.to_s, File.extname(filename))
+
+      name = name.gsub(/\s+/, "_")
+      name = name.gsub(/[^a-zA-Z0-9_]/, "")
+      name = "#{name}.png"
+
+      raise ArgumentError, "filename cannot be empty" if name == ".png"
+
+      name
+    end
+  end
+end

data/lib/avatar_generator/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  class Configuration
+    attr_accessor :size,
+                  :background,
+                  :storage_path,
+                  :public_path
+
+    def initialize
+      @size = 250
+      @background = "#FFFFFF"
+      @storage_path = "public/avatars"
+      @public_path = "/avatars"
+    end
+  end
+end

data/lib/avatar_generator/generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  class Generator
+    GRID_SIZE = 5
+    def initialize(identifier, size: nil, background: nil)
+      @identifier = identifier
+      @image_size = size || AvatarGenerator.configuration.size
+      @background = background || AvatarGenerator.configuration.background
+
+      raise ArgumentError, "image size must be at least 5" if @image_size < 5
+    end
+
+    def call
+      bytes = Digest::MD5.digest(@identifier).bytes
+
+      color =
+        bytes.first(3)
+
+      grid =
+        bytes
+        .each_slice(3)
+        .select { |row| row.length == 3 }
+        .map { |row| mirror_row(row) }
+        .flatten
+        .each_with_index
+        .select { |code, _| code.even? }
+
+      pixel_map =
+        grid.map do |_, index|
+          cell =
+            @image_size / GRID_SIZE
+
+          x =
+            (index % GRID_SIZE) * cell
+
+          y =
+            (index / GRID_SIZE) * cell
+
+          [
+            [x, y],
+            [x + cell - 1, y + cell - 1]
+          ]
+        end
+
+      Image.new(
+        color: color,
+        image_size: @image_size,
+        pixel_map: pixel_map,
+        background: @background
+      )
+    end
+
+    private
+
+    def mirror_row(row)
+      row + [
+        row[1],
+        row[0]
+      ]
+    end
+  end
+end

data/lib/avatar_generator/image.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  Image = Struct.new(
+    :color,
+    :pixel_map,
+    :image_size,
+    :background,
+    keyword_init: true
+  )
+end

data/lib/avatar_generator/renderer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  class Renderer
+    def self.render(image)
+      background = ChunkyPNG::Color.from_hex(image.background)
+
+      png = ChunkyPNG::Image.new(
+        image.image_size,
+        image.image_size,
+        background
+      )
+
+      color = ChunkyPNG::Color.rgb(
+        *image.color
+      )
+
+      image.pixel_map.each do |rectangle|
+        top_left,
+        bottom_right = rectangle
+
+        x1, y1 = top_left
+        x2, y2 = bottom_right
+
+        (x1..x2).each do |x|
+          (y1..y2).each do |y|
+            png[x, y] = color
+          end
+        end
+      end
+
+      png
+    end
+  end
+end

data/lib/avatar_generator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AvatarGenerator
+  VERSION = "0.1.1"
+end

data/lib/avatar_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "avatar_generator/version"
+
+require "digest/md5"
+require "base64"
+require "stringio"
+require "chunky_png"
+require "fileutils"
+
+require_relative "avatar_generator/configuration"
+require_relative "avatar_generator/image"
+require_relative "avatar_generator/generator"
+require_relative "avatar_generator/renderer"
+require_relative "avatar_generator/avatar"
+module AvatarGenerator
+  class Error < StandardError; end
+
+  class << self
+    attr_reader :configuration
+
+    def configure
+      yield(configuration)
+    end
+
+    def generate(identifier, **options)
+      image =
+        Generator
+        .new(identifier, **options)
+        .call
+
+      Avatar.new(
+        image,
+        identifier: identifier
+      )
+    end
+  end
+  @configuration = Configuration.new
+end

data/lib/generators/avatar_generator/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AvatarGenerator
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates a Gravatar initializer."
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template(
+          "avatar_generator.rb",
+          "config/initializers/avatar_generator.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/avatar_generator/install/templates/avatar_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Gravatar configuration
+#
+# You can customize the default settings below.
+# Individual avatars can override these settings when generated.
+
+AvatarGenerator.configure do |config|
+  # Default avatar size in pixels.
+  config.size = 250
+
+  # Default background color.
+  config.background = "#FFFFFF"
+
+  # Directory where generated avatars are stored.
+  config.storage_path = "public/avatars"
+
+  # Public URL path used to access generated avatars.
+  config.public_path = "/avatars"
+end

data/sig/avatar_generator.rbs

@@ -0,0 +1,4 @@
+AvatarGenerator Gravatar
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: avatar_generator
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Salman Mahmud
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: chunky_png
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  avatar_generator is a github style deterministic avatar generator for Ruby applications.
+  It generates unique, consistent avatars from identifiers such as
+  usernames, email addresses, or other unique values. The same identifier
+  always produces the same avatar.
+email:
+- salmanmahmud2014@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- avatar_generator.gemspec
+- lib/avatar_generator.rb
+- lib/avatar_generator/avatar.rb
+- lib/avatar_generator/configuration.rb
+- lib/avatar_generator/generator.rb
+- lib/avatar_generator/image.rb
+- lib/avatar_generator/renderer.rb
+- lib/avatar_generator/version.rb
+- lib/generators/avatar_generator/install/install_generator.rb
+- lib/generators/avatar_generator/install/templates/avatar_generator.rb
+- sig/avatar_generator.rbs
+homepage: https://github.com/salmanx/avatar_generator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/salmanx/avatar_generator
+  source_code_uri: https://github.com/salmanx/avatar_generator
+  changelog_uri: https://github.com/salmanx/avatar_generator/releases
+  bug_tracker_uri: https://github.com/salmanx/avatar_generator/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Github style avatar generator for Ruby applications
+test_files: []