plavatar

README

plavatar

A library for generating placeholder avatars (=plavatars).

plavatar: A library for generating placeholder avatars (=plavatars).
plavatar-rest A stateless REST microservice wrapping plavatar for you (docker image available) (https://github.com/jonasdoesthings/plavatar-rest)

Install

go get github.com/jonasdoesthings/plavatar/v3
Then you can import the "github.com/jonasdoesthings/plavatar/v3" package.

Usage

Full Docs: https://pkg.go.dev/github.com/jonasdoesthings/plavatar/v3

Basic Example with a built-in generatorFunc:

import (
    "bytes"
    "github.com/jonasdoesthings/plavatar/v3"
)

func generateMyAvatar() (*bytes.Buffer, string) {
    // Set-up a plavatar Generator instance
    avatarGenerator := plavatar.Generator{}
    
    // Configure the plavatar you want to generate 
    options := &plavatar.Options{
        Name:         "exampleSeed", // the seed to use
        OutputShape:  plavatar.ShapeSquare, // ShapeSquare or ShapeCircle
        OutputFormat: plavatar.FormatSVG,
        // OR if you want a PNG with the size of 512x512px:
        // OutputFormat: plavatar.FormatPNG,
        // OutputSize: 512,
    }
    
    // generate the avatar using the built-in Smiley generatorFunc and pass the options from above
    avatar, rngSeed, err := avatarGenerator.GenerateAvatar(avatarGenerator.Smiley, options)
    if err != nil {
        panic(err)
    }

    // returns the avatar as *bytes.Buffer and the used rngSeed as string
    return avatar, rngSeed
}

The plavatar Generator uses a passed generatorFunc to generate the avatar graphic. The generatorFunc takes a svg canvas, a rng, the used rngSeed, and the generation options. The generatorFunc then modifies the passed svg canvas.

Basic example with a custom generatorFunc:

import (
    "bytes"
    svg "github.com/ajstarks/svgo"
    "github.com/jonasdoesthings/plavatar/v3"
    "math/rand"
)

func CustomAvatar(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *plavatar.Options) {
    canvas.Def()
    gradientColors := []svg.Offcolor{{0, "#FF0000", 1}}
    canvas.LinearGradient("bg", 0, 0, 100, 100, gradientColors)
    canvas.DefEnd()

    plavatar.DrawCanvasBackground(canvas, options)
    canvas.Line(-100, -10, 100, 10, "stroke: white; stroke-width: 23")
}

func generateMyCustomAvatar() (*bytes.Buffer, string) {
    avatarGenerator := plavatar.Generator{}
    options := &plavatar.Options{
        Name:         "exampleSeed",
        OutputFormat: plavatar.FormatSVG,
        OutputShape:  plavatar.ShapeSquare,
    }
    avatar, rngSeed, err := avatarGenerator.GenerateAvatar(CustomAvatar, options)
    if err != nil {
        panic(err)
    }

    return avatar, rngSeed
}

If possible, use format=SVG.

Not only is format=SVG extremely faster, if you transfer the image to your user, SVG also saves you a lot of bandwidth and latency (A generated SVG is only ~2% the size of a 512px PNG)

Testing

To run the go tests, use go test -v ./... in the root directory of the project.

Documentation

Overview

Package plavatar implements the core avatar generation functionality.

It contains the Generator struct, which implements the library's main method: Generator.GenerateAvatar.

Generator.GenerateAvatar is called in combination with a GeneratorFunction like Generator.Smiley (see the matching avatar_XXX.go file for details on the GeneratorFunction's implementations)

Index

• Constants
• func DrawCanvasBackground(canvas *svg.SVG, options *Options)
• func RasterizeSVGToPNG(svg io.Reader, imageSize int) (*bytes.Buffer, error)
• type Format
• type Generator
  • func (generator *Generator) GenerateAvatar(...) (*bytes.Buffer, string, error)
  • func (generator *Generator) Gradient(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Happy(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Laughing(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Marble(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Pixels(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Smiley(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
  • func (generator *Generator) Solid(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)
• type Options
• type Shape

Constants

const CanvasSize = 512

Functions

func DrawCanvasBackground

func DrawCanvasBackground(canvas *svg.SVG, options *Options)

DrawCanvasBackground fills the canvas with the fitting background. Important: when using this method, the canvas must already contain definitions for the bg color gradient.

Example definition in your custom generatorFunc:

func MyCustomGenerator(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options) {
	backgroundColor := utils.RandomColorHex(rng)

	canvas.Def()
	gradientColors := []svg.Offcolor{{0, backgroundColor, 1}}
	canvas.LinearGradient("bg", 0, 0, 100, 100, gradientColors)
	canvas.DefEnd()

	DrawCanvasBackground(canvas, options)
	...
}

See avatar_solid.go's source code for a full example on how to define the bg color.

func RasterizeSVGToPNG

func RasterizeSVGToPNG(svg io.Reader, imageSize int) (*bytes.Buffer, error)

RasterizeSVGToPNG rasterizes the SVG file to a PNG image of the given imageSize in the form of a bytes.Buffer.

Types

type Format

type Format = int

Format is the file-format the output image should be encoded in.

const (
	FormatPNG Format = iota
	FormatSVG
)

type Generator

type Generator struct{}

A Generator is used to generate avatars using its Generator.GenerateAvatar method.

func (*Generator) GenerateAvatar

func (generator *Generator) GenerateAvatar(generatorFunc func(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options), generatorOptions *Options) (*bytes.Buffer, string, error)

GenerateAvatar generates an avatar by setting-up the image canvas and then calling the passed generatorFunc. It uses the passed generatorOptions to instruct the avatar generation.

The passed generatorFunc can either be a built-in one like Generator.Smiley, Generator.Solid, or a custom one written by you.

A successful generation, returns err == nil, a string with the used rng seed, and a buffer filled with the image data.

Usage Example:

func generateMyAvatar() (*bytes.Buffer, string) {
	avatarGenerator := plavatar.Generator{}
	options := &plavatar.Options{
		Name:         "exampleSeed",
		OutputSize:   256,
		OutputFormat: plavatar.FormatSVG,
		OutputShape:  plavatar.ShapeSquare,
	}
	avatar, rngSeed, err := avatarGenerator.GenerateAvatar(avatarGenerator.Smiley, options)
	if err != nil {
		panic(err)
	}

	return avatar, rngSeed
}

func (*Generator) Gradient

func (generator *Generator) Gradient(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

func (*Generator) Happy

func (generator *Generator) Happy(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

func (*Generator) Laughing

func (generator *Generator) Laughing(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

func (*Generator) Marble

func (generator *Generator) Marble(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

func (*Generator) Pixels

func (generator *Generator) Pixels(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

Pixels TODO: Currently this always outputs a ShapeCircle in PNG output mode. oksvg does not support clippaths at the moment, so the whole square gets rasterized see: https://github.com/srwiley/oksvg/issues/10

func (*Generator) Smiley

func (generator *Generator) Smiley(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

func (*Generator) Solid

func (generator *Generator) Solid(canvas *svg.SVG, rng *rand.Rand, rngSeed int64, options *Options)

type Options

type Options struct {
	Name         string
	OutputSize   int
	OutputFormat Format
	OutputShape  Shape
}

Options contains the generation instructions like seed (Name) or OutputSize, passed to the generation method

type Shape

type Shape = int

Shape the output image should have.

const (
	ShapeCircle Shape = iota // Instructs the generator to return a circle-shaped avatar. (default)
	ShapeSquare              // Instructs the generator to return a square-shaped avatar.
)