Avatar Generator

A Python library for generating unique, deterministic pixel-based avatars from hash values. Perfect for creating user profile pictures, identicons, or visual representations based on hashes.

Overview

Avatar Generator is a flexible and extensible library that transforms hash values into visually distinct avatars. Each hash produces a unique, symmetric pixel pattern with customizable styling options including background colors and opacity levels.

Features

• Deterministic Generation: Same hash always produces the same avatar
• Customizable Styling: Control opacity, background colors, and luminance
• Extensible Architecture: Easy to add new avatar builders
• Multiple Export Formats: Save to file, buffer, or get bytes directly
• Symmetric Patterns: Generates aesthetically pleasing mirrored designs

Installation

pip install avatar-gen

Quick Start

from avatar_generator import AvatarGenerator, PixelAvatarBuilder

# Generate and save an avatar
AvatarGenerator(builder=PixelAvatarBuilder).save_to_file("user_hash", "avatar.png")

Generator methods

save_to_file(hash_value, file_path)

Generates an avatar from the given hash value and saves it to a file.

Parameters:

• hash_value (str): The hash or identifier for the avatar
• file_path (str): Output path for the generated PNG image

Example:

generator = AvatarGenerator(builder=PixelAvatarBuilder)
generator.save_to_file("user123", "avatars/user123.png")

save_to_buffer(hash_value)

Generates an avatar and returns it as a BytesIO buffer object.

Parameters:

• hash_value (str): The hash or identifier for the avatar

Returns: BytesIO object containing the PNG image data

Example:

generator = AvatarGenerator(builder=PixelAvatarBuilder)
buffer = generator.save_to_buffer("user123")

save_to_bytes(hash_value)

Generates an avatar and returns the raw bytes of the PNG image.

Parameters:

• hash_value (str): The hash or identifier for the avatar

Returns: bytes containing the PNG image data

Example:

generator = AvatarGenerator(builder=PixelAvatarBuilder)
image_bytes = generator.save_to_bytes("user123")

Supported avatar builders

• PixelAvatarBuilder

PixelAvatarBuilder

Generates 8x8 pixel-based avatars with symmetric patterns. Each pixel is determined by the hash value, creating unique and recognizable avatars.

Parameters

How it works

1. Avatar Pattern: The lower 24 bits of the hash determine which pixels are drawn (white color)
2. Background Color: The upper 24 bits of the hash determine the background color (RGB values)
3. Transparency: The opacity parameter controls how transparent the white pixels are, allowing the background to show through
4. Luminance Control: The max_background_luminance parameter ensures the background isn't too bright, maintaining good contrast

Example

from avatar_generator import AvatarGenerator, PixelAvatarBuilder

# Generate with default settings
AvatarGenerator(
    builder=PixelAvatarBuilder
).save_to_file("user123", "avatar.png")

# Generate with custom parameters
AvatarGenerator(
    builder=PixelAvatarBuilder,
    opacity=255,              # Fully opaque pixels
    background=True,          # Include background
    max_background_luminance=150  # Darker backgrounds
).save_to_file("admin@example.com", "admin_avatar.png")

# Generate with semi-transparent effect
AvatarGenerator(
    builder=PixelAvatarBuilder,
    opacity=180,              # 70% opaque
    background=True
).save_to_file("user456", "user456_avatar.png")

Example Output

Advanced Usage

Custom Builder Implementation

You can create custom avatar builders by extending the AbstractAvatarBuilder class:

from avatar_generator.builders import AbstractAvatarBuilder
from PIL import Image

class CustomAvatarBuilder(AbstractAvatarBuilder):
    def generate(self, value: int) -> Image:
        # Your custom implementation
        pass

Batch Generation

from avatar_generator import AvatarGenerator, PixelAvatarBuilder

users = ["alice", "bob", "charlie"]
generator = AvatarGenerator(builder=PixelAvatarBuilder)

for user in users:
    generator.save_to_file(user, f"avatars/{user}.png")

Use in Web Applications

from avatar_generator import AvatarGenerator, PixelAvatarBuilder
from io import BytesIO

def get_user_avatar(user_id):
    generator = AvatarGenerator(builder=PixelAvatarBuilder)
    buffer = generator.save_to_buffer(user_id)
    buffer.seek(0)
    return buffer

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See the LICENSE file for details.