GravatarBuilt 1.2.0

Status

Main Branch

Dev Branch

Release

GravatarBuilt

A .NET library for generating unique PNG avatars from a string identifier (email, phone number, etc.). The image is derived from an MD5 hash of the input: color and pixel pattern are determined by the input string.

Zero dependencies and fully cross-platform — avatars are rasterized and encoded as PNG entirely in managed code, with no native graphics runtime (no SkiaSharp or similar). The same package runs on Windows, Linux, and macOS anywhere your .NET app runs.

Target frameworks: .NET Standard 2.0, .NET 8, .NET 9, .NET 10
Dependencies: none
Namespace: GravatarBuilt

Installation

NuGet

dotnet add package GravatarBuilt

Or via Package Manager:

Install-Package GravatarBuilt

From source

git clone https://gitlab.com/t1moHa/gravatarbuilt.git
cd gravatarbuilt
dotnet build -c Release
dotnet test

Quick start

using GravatarBuilt;

var gravatar = new Gravatar();

using var stream = gravatar.Generate("user@example.com");

// save to file
using var file = File.Create("avatar.png");
stream.CopyTo(file);

By default this creates a 360×360 px square image with background rgb(242, 241, 242).

API

Constructor

public Gravatar(int? size = null)

var small = new Gravatar(120);   // 120×120
var large = new Gravatar(480);   // 480×480

Properties

var gravatar = new Gravatar(240)
{
    BackgroundColor = new RgbaColor(255, 255, 255) // white background
};

Methods

Generate(string input)

Builds a PNG from the hash of input. The same input produces the same pattern and color (given the same size and background).

Stream Generate(string input)

Returns a MemoryStream containing PNG data; the stream position is at the start (Position = 0). The caller is responsible for disposing the stream (using / Dispose).

Generate(string input, bool dependOnTime)

When dependOnTime is true, mixes the current system time into the seed so each call can produce a new result. When false, behaves like Generate(input).

Stream Generate(string input, bool dependOnTime)

using var unique = gravatar.Generate("user@example.com", dependOnTime: true);
using var stable = gravatar.Generate("user@example.com", dependOnTime: false);

Examples

Save to a file

var gravatar = new Gravatar(240);

using var stream = gravatar.Generate("+79001234567");
using var file = File.Create("phone-avatar.png");
await stream.CopyToAsync(file);

Bytes for network transfer

using var stream = new Gravatar().Generate("user@example.com");
using var ms = new MemoryStream();
await stream.CopyToAsync(ms);
byte[] pngBytes = ms.ToArray();

ASP.NET Core — return PNG in the response

app.MapGet("/avatar/{email}", (string email) =>
{
    var gravatar = new Gravatar(120);
    var stream = gravatar.Generate(email);
    return Results.File(stream, "image/png");
});

Multiple avatars with different backgrounds

var emails = new[] { "alice@mail.com", "bob@mail.com", "carol@mail.com" };
var colors = new[]
{
    new RgbaColor(242, 241, 242),
    new RgbaColor(230, 240, 255),
    new RgbaColor(255, 245, 230),
};

var gravatar = new Gravatar(240);

for (var i = 0; i < emails.Length; i++)
{
    gravatar.BackgroundColor = colors[i];
    using var stream = gravatar.Generate(emails[i]);
    using var file = File.Create($"avatar-{i}.png");
    stream.CopyTo(file);
}

How it works

1. An MD5 hash is computed from the input string.
2. The first hash bytes define the block color.
3. The following bytes form a symmetric 12×12 matrix of “fill / leave background”.
4. The result is rasterized into an RGBA buffer and encoded as PNG (managed, no native dependencies).

Typical inputs: email, phone number, or any other stable unique user identifier.

Migration from SkiaSharp-based versions

BackgroundColor is now RgbaColor instead of SkiaSharp’s SKColor. Replace:

BackgroundColor = new SKColor(255, 255, 255);

with:

BackgroundColor = new RgbaColor(255, 255, 255);

You no longer need a SkiaSharp package reference to consume this library.

Versioning and releases

Package version is set automatically via MinVer from git tags:

git tag v1.0.1
git push origin v1.0.1

A tag like vMAJOR.MINOR.PATCH becomes NuGet version MAJOR.MINOR.PATCH.

License

See LICENSE.txt.