avatar

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 10, 2025 License: ISC Imports: 11 Imported by: 0

README

Avatar

GitHub Tag Go Reference License Go Report Card Contributors Issues

avatar is a Go library for generating customizable avatars. It supports creating avatars for text, stickers, and persons with various customization options.

Letter Sticker Male Female
Letter Sticker Male Female

Installation

To install Avatar, use go get:

go get github.com/go-universal/avatar

Usage

Creating a Text Avatar
package main

import (
    "github.com/go-universal/avatar"
    "log"
)

func main() {
    factory := avatar.
        New().
        DefaultPalettes().
        CircleShape().
        Build()

    johnDoe := factory.NewText("John Doe")

    johnDoe.
        RandomizeShape().
        RandomizePalette()

    err := johnDoe.Save("john_doe.svg")
    if err != nil {
        log.Fatal(err)
    }
}
Creating a Sticker Avatar
package main

import (
    "github.com/go-universal/avatar"
    "log"
)

func main() {
    factory := avatar.
        New().
        DefaultPalettes().
        CircleShape().
        Build()

    star := factory.NewSticker("")

    star.
        RandomizeShape().
        RandomizePalette()

    err := star.Save("star.svg")
    if err != nil {
        log.Fatal(err)
    }
}
Creating a Person Avatar
package main

import (
    "github.com/go-universal/avatar"
    "log"
)

func main() {
    factory := avatar.
        New().
        DefaultAccessories().
        DefaultBeards().
        SuitDress().
        PrescriptionGlasses().
        DarkHairColor().
        DefaultHairs().
        DefaultPalettes().
        CircleShape().
        WhiteSkin().
        Build()

    male := factory.NewMale()
    male.
        RandomizeShape().
        RandomizePalette().
        RandomizeSkinColor().
        RandomizeHairColor().
        RandomizeHair().
        RandomizeBeard().
        RandomizeDress().
        RandomizeEye().
        RandomizeEyebrow().
        RandomizeMouth().
        RandomizeGlasses().
        RandomizeAccessory()
    err := male.Save("male.svg")
    if err != nil {
        log.Fatal(err)
    }

    female := factory.NewFemale()
    female.
        RandomizeShape().
        RandomizePalette().
        RandomizeSkinColor().
        RandomizeHairColor().
        RandomizeHair().
        RandomizeBeard().
        RandomizeDress().
        RandomizeEye().
        RandomizeEyebrow().
        RandomizeMouth().
        RandomizeGlasses().
        RandomizeAccessory()
    err := female.Save("female.svg")
    if err != nil {
        log.Fatal(err)
    }
}

Extending

Avatar generation in this package is based on modular SVG elements. You can easily customize the existing avatar styles or add new ones using the provided helper methods.

To create or modify styles:

  • Start by editing the template.ai file.
  • Save your design as an SVG.
  • Extract the relevant parts (e.g., shapes, hair, accessories) and integrate them into the avatar package.

Each SVG shape must include placeholders to enable dynamic replacement of colors in the final rendering.

Template Variables for Custom Palettes

Use the following template variables in your SVG elements to enable dynamic styling:

  • {shape} — Background shape color
  • {skin} — Base skin tone
  • {skin_shadow} — Shadowed areas of the skin
  • {hair} — Hair color
  • {hair_shadow} — Shadowed areas of the hair
  • {hair_highlight} — Highlighted areas of the hair
  • {dress} — Clothing color
  • {dress_shadow} — Shadowed areas of the clothing
  • {decorator} — Accessories (e.g., glasses, necklace)
  • {text} — Text and sticker color

These variables allow your avatar elements to adapt to different themes and palettes dynamically.

License

This project is licensed under the ISC License. See the LICENSE file for details.

Documentation

Index

Constants

View Source 
const None = "::None"

Variables

This section is empty.

Functions

This section is empty.

Types

type Accessory 

type Accessory string

Accessory defines preset accessory types for an avatar. 

const (
	AccessoryNecklace Accessory = "necklace"
	AccessoryChoker   Accessory = "choker"
)

type AvatarFactory 

type AvatarFactory interface {
	// NewMale creates a new male avatar.
	NewMale() PersonAvatar

	// NewFemale creates a new female avatar.
	NewFemale() PersonAvatar

	// NewPerson creates a new person avatar based on the gender specified by the isMale parameter.
	// If isMale is true, it creates a male avatar; otherwise, a female avatar.
	NewPerson(isMale bool) PersonAvatar

	// NewText creates a new text avatar with the specified name.
	NewText(name string) TextAvatar

	// NewSticker creates a new sticker avatar with the specified stickers.
	NewSticker(sticker Sticker) StickerAvatar

	// Shapes returns a list of available avatar background shapes.
	Shapes() []string

	// Palettes returns a list of available color palettes for customization.
	Palettes() []string

	// Stickers returns a list of available stickers for the avatar.
	Stickers() []string

	// SkinColors returns a list of available skin color options.
	SkinColors() []string

	// HairColors returns a list of available hair color options.
	HairColors() []string

	// MaleHairs returns a list of available male hairstyles.
	MaleHairs() []string

	// MaleBeards returns a list of available male beard styles.
	MaleBeards() []string

	// MaleDresses returns a list of available male dresses or outfits.
	MaleDresses() []string

	// MaleEyes returns a list of available male eye styles.
	MaleEyes() []string

	// MaleEyebrows returns a list of available male eyebrow styles.
	MaleEyebrows() []string

	// MaleMouths returns a list of available male mouth styles.
	MaleMouths() []string

	// MaleGlasses returns a list of available male glasses styles.
	MaleGlasses() []string

	// MaleAccessories returns a list of available male accessories.
	MaleAccessories() []string

	// FemaleHairs returns a list of available female hairstyles.
	FemaleHairs() []string

	// FemaleDresses returns a list of available female dresses or outfits.
	FemaleDresses() []string

	// FemaleEyes returns a list of available female eye styles.
	FemaleEyes() []string

	// FemaleEyebrows returns a list of available female eyebrow styles.
	FemaleEyebrows() []string

	// FemaleMouths returns a list of available female mouth styles.
	FemaleMouths() []string

	// FemaleGlasses returns a list of available female glasses styles.
	FemaleGlasses() []string

	// FemaleAccessories returns a list of available female accessories.
	FemaleAccessories() []string
}

AvatarFactory defines an interface for building different types of avatars. It provides methods to create male, female, text and sticker avatars.

type Beard 

type Beard string

Beard defines preset beard types for an avatar. 

const (
	BeardMustach      Beard = "mustach"
	BeardFancyMustach Beard = "fancy-mustach"
	BeardNormal       Beard = "beard"
	BeardMedium       Beard = "medium-beard"
	BeardLong         Beard = "long-beard"
)

type Dress 

type Dress string

Dress defines preset dress types for an avatar. 

const (
	DressSuit   Dress = "suit"
	DressShirt  Dress = "shirt"
	DressTShirt Dress = "t-shirt"
)

type Eye 

type Eye string

Eye defines preset eye types for an avatar.

type Eyebrow 

type Eyebrow string

Eyebrow defines preset eyebrow types for an avatar.

type FactoryBuilder 

type FactoryBuilder interface {
	// AddAccessory adds a custom accessory to the avatar factory.
	// Shape can include fill="{decorator}" to match the avatar palette.
	AddAccessory(isMale bool, name, shape string) FactoryBuilder

	// DefaultAccessories add all predefined accessories to the avatar factory.
	DefaultAccessories() FactoryBuilder

	// NecklaceAccessory add necklace accessory for female to the avatar factory.
	NecklaceAccessory() FactoryBuilder

	// ChokerAccessory add choker accessory for female to the avatar factory.
	ChokerAccessory() FactoryBuilder

	// AddBeard adds a custom beard to the avatar factory.
	// Shape can include fill="{hair}", fill="{hair_shadow}" and fill="{hair_highlight}" to match the avatar palette.
	AddBeard(name, shape string) FactoryBuilder

	// DefaultBeards add all predefined beards to the avatar factory.
	DefaultBeards() FactoryBuilder

	// MustachBeard add mustache beard to the avatar factory.
	MustachBeard() FactoryBuilder

	// FancyMustachBeard add fancy mustache beard to the avatar factory.
	FancyMustachBeard() FactoryBuilder

	// NormalBeard add normal beard to the avatar factory.
	NormalBeard() FactoryBuilder

	// MediumBeard add medium-length beard to the avatar factory.
	MediumBeard() FactoryBuilder

	// LongBeard add long beard to the avatar factory.
	LongBeard() FactoryBuilder

	// SetBodyShape sets the default body shape for the avatar factory.
	// Shape can include fill="{skin}" and fill="{skin_shadow}" to match the avatar palette.
	SetBodyShape(shape string) FactoryBuilder

	// AddDress adds a custom dress to the avatar factory.
	// Shape can include fill="{dress}", fill="{dress_shadow}" and fill="{decorator}" to match the avatar palette.
	AddDress(isMale bool, name, shape string) FactoryBuilder

	// DefaultDresses add all predefined dresses to the avatar factory.
	DefaultDresses() FactoryBuilder

	// SuitDress add suit dress to the avatar factory.
	SuitDress() FactoryBuilder

	// ShirtDress add shirt dress to the avatar factory.
	ShirtDress() FactoryBuilder

	// TShirtDress add t-shirt dress to the avatar factory.
	TShirtDress() FactoryBuilder

	// AddEye adds a custom eye to the avatar factory.
	AddEye(isMale bool, name, shape string) FactoryBuilder

	// AddEyebrow adds a custom eyebrow to the avatar factory.
	AddEyebrow(isMale bool, name, shape string) FactoryBuilder

	// AddGlasses adds a custom glasses to the avatar factory.
	// Shape can include fill="{decorator}" to match the avatar palette.
	AddGlasses(isMale bool, name, shape string) FactoryBuilder

	// DefaultGlasses add all predefined glasses to the avatar factory.
	DefaultGlasses() FactoryBuilder

	// PrescriptionGlasses add prescription glasses to the avatar factory.
	PrescriptionGlasses() FactoryBuilder

	// RoundPrescriptionGlasses add round prescription glasses to the avatar factory.
	RoundPrescriptionGlasses() FactoryBuilder

	// SunglassGlasses add sunglass glasses to the avatar factory.
	SunglassGlasses() FactoryBuilder

	// RoundSunglassGlasses add round sunglass glasses to the avatar factory.
	RoundSunglassGlasses() FactoryBuilder

	// AddHair adds a custom hair to the avatar factory.
	// Shape can include fill="{hair}", fill="{hair_shadow}" and fill="{hair_highlight}" to match the avatar palette.
	AddHair(isMale bool, name, shape string) FactoryBuilder

	// DefaultHairs add all predefined hairs to the avatar factory.
	DefaultHairs() FactoryBuilder

	// ShortHair add short hair to the avatar factory.
	ShortHair() FactoryBuilder

	// MediumHair add medium hair to the avatar factory.
	MediumHair() FactoryBuilder

	// WavyHair add wavy hair to the avatar factory.
	WavyHair() FactoryBuilder

	// CurlyHair add curly hair to the avatar factory.
	CurlyHair() FactoryBuilder

	// AddHaircolor adds a custom hair color to the avatar factory.
	AddHaircolor(name string, color SVGHairColor) FactoryBuilder

	// DefaultHairColors add all predefined hair colors to the avatar factory.
	DefaultHairColors() FactoryBuilder

	// BrownHairColor add brown hair color to the avatar factory.
	BrownHairColor() FactoryBuilder

	// LightHairColor add light hair color to the avatar factory.
	LightHairColor() FactoryBuilder

	// DarkHairColor add dark hair color to the avatar factory.
	DarkHairColor() FactoryBuilder

	// AddMouth adds a custom mouth to the avatar factory.
	AddMouth(isMale bool, name, shape string) FactoryBuilder

	// AddPalette adds a custom palette to the avatar factory.
	AddPalette(name string, palette SVGPalette) FactoryBuilder

	// DefaultPalettes add all predefined palettes to the avatar factory.
	DefaultPalettes() FactoryBuilder

	// PurplePalette add purple palette to the avatar factory.
	PurplePalette() FactoryBuilder

	// GreenPalette add green palette to the avatar factory.
	GreenPalette() FactoryBuilder

	// BluePalette add blue palette to the avatar factory.
	BluePalette() FactoryBuilder

	// YellowPalette add yellow palette to the avatar factory.
	YellowPalette() FactoryBuilder

	// OrangePalette add  orange palette to  avatarthe factory.
	OrangePalette() FactoryBuilder

	// RedPalette add red palette to the avatar factory.
	RedPalette() FactoryBuilder

	// TealPalette add teal palette to the avatar factory.
	TealPalette() FactoryBuilder

	// PinkPalette add pink palette to the avatar factory.
	PinkPalette() FactoryBuilder

	// AddShape adds a custom background shape to the avatar factory.
	// Shape can include fill="{shape}" to match the avatar palette.
	AddShape(name string, shape SVGShape) FactoryBuilder

	// DefaultShapes add all predefined background shapes to the avatar factory.
	DefaultShapes() FactoryBuilder

	// FillShape add square background shape to the avatar factory.
	FillShape() FactoryBuilder

	// CircleShape add circle background shape to the avatar factory.
	CircleShape() FactoryBuilder

	// PolygonShape add polygon background shape to the avatar factory.
	PolygonShape() FactoryBuilder

	// AddSkinColor adds a custom skin color to the avatar factory.
	AddSkinColor(name string, color SVGSkinColor) FactoryBuilder

	// DefaultSkinColors add all predefined skin colors to the avatar factory.
	DefaultSkinColors() FactoryBuilder

	// WhiteSkin add white skin color to the avatar factory.
	WhiteSkin() FactoryBuilder

	// BrownSkin add brown skin color to the avatar factory.
	BrownSkin() FactoryBuilder

	// BlackSkin add black skin color to the avatar factory.
	BlackSkin() FactoryBuilder

	// AddSticker adds a custom sticker to the avatar factory.
	// Shape can include fill="{text}" to match the avatar palette.
	AddSticker(name, shape string) FactoryBuilder

	// AddLetter adds a custom letter shape to the avatar factory.
	// Shape can include fill="{text}" to match the avatar palette.
	AddLetter(letter rune, shape string) FactoryBuilder

	// AddTransformer adds a custom letter transformer to the avatar factory.
	AddTransformer(letter, replacement rune) FactoryBuilder

	// PersianLetters add all predefined persian letters to the avatar factory.
	PersianLetters() FactoryBuilder

	// PersianTransformers add all predefined persian transformers to the avatar factory.
	PersianTransformers() FactoryBuilder

	// Build creates a new AvatarFactory instance.
	Build() AvatarFactory
	// contains filtered or unexported methods
}

FactoryBuilder defines the interface for building an avatar factory.

func New 

func New() FactoryBuilder

New creates a new FactoryBuilder instance.

type Glasses 

type Glasses string

Glasses defines preset glasses types for an avatar. 

const (
	GlassesPrescription      Glasses = "prescription"
	GlassesRoundPrescription Glasses = "round-prescription"
	GlassesSunglass          Glasses = "sunglass"
	GlassesRoundSunglass     Glasses = "round-sunglass"
)

type Hair 

type Hair string

Hair defines preset hair types for an avatar. 

const (
	HairShort  Hair = "short"
	HairMedium Hair = "medium"
	HairWavy   Hair = "wavy"
	HairCurly  Hair = "curly"
)

type HairColor 

type HairColor string

HairColor defines preset hair color types for an avatar. 

const (
	HairBrown HairColor = "brown"
	HairLight HairColor = "light"
	HairDark  HairColor = "dark"
)

type Mouth 

type Mouth string

Mouth defines preset mouth types for an avatar.

type Palette 

type Palette string

Palette defines preset palette types for an avatar. 

const (
	Purple Palette = "purple"
	Green  Palette = "green"
	Blue   Palette = "blue"
	Yellow Palette = "yellow"
	Orange Palette = "orange"
	Red    Palette = "red"
	Teal   Palette = "teal"
	Pink   Palette = "pink"
)

type PersonAvatar 

type PersonAvatar interface {
	// Shape returns the background shape of the avatar.
	Shape() string

	// Palette returns the color palette of the avatar.
	Palette() string

	// SkinColor returns the skin color of the avatar.
	SkinColor() string

	// HairColor returns the hair color of the avatar.
	HairColor() string

	// IsMale returns true if the avatar is male, false otherwise.
	IsMale() bool

	// Hair returns the hair style of the avatar.
	Hair() string

	// Beard returns the beard style of the avatar.
	Beard() string

	// Dress returns the dress style of the avatar.
	Dress() string

	// Eye returns the eye style of the avatar.
	Eye() string

	// Eyebrow returns the eyebrow style of the avatar.
	Eyebrow() string

	// Mouth returns the mouth style of the avatar.
	Mouth() string

	// Glasses returns the glasses style of the avatar.
	Glasses() string

	// Accessory returns the accessory style of the avatar.
	Accessory() string

	// RandomizeShape randomizes the shape of the avatar.
	RandomizeShape(only ...Shape) PersonAvatar

	// RandomizePalette randomizes the color palette of the avatar.
	RandomizePalette(only ...Palette) PersonAvatar

	// RandomizeSkinColor randomizes the skin color of the avatar.
	RandomizeSkinColor(only ...SkinColor) PersonAvatar

	// RandomizeHairColor randomizes the hair color of the avatar.
	RandomizeHairColor(only ...HairColor) PersonAvatar

	// RandomizeHair randomizes the hair style of the avatar.
	RandomizeHair(only ...Hair) PersonAvatar

	// RandomizeBeard randomizes the beard style of the avatar.
	RandomizeBeard(only ...Beard) PersonAvatar

	// RandomizeDress randomizes the dress style of the avatar.
	RandomizeDress(only ...Dress) PersonAvatar

	// RandomizeEye randomizes the eye style of the avatar.
	RandomizeEye(only ...Eye) PersonAvatar

	// RandomizeEyebrow randomizes the eyebrow style of the avatar.
	RandomizeEyebrow(only ...Eyebrow) PersonAvatar

	// RandomizeMouth randomizes the mouth style of the avatar.
	RandomizeMouth(only ...Mouth) PersonAvatar

	// RandomizeGlasses randomizes the glasses style of the avatar.
	RandomizeGlasses(only ...Glasses) PersonAvatar

	// RandomizeAccessory randomizes the accessory style of the avatar.
	RandomizeAccessory(only ...Accessory) PersonAvatar

	// Render returns the inline SVG representation of the avatar.
	Render() string

	// SVG returns the SVG representation of the avatar.
	SVG() string

	// Base64 returns the base64 encoded representation of the avatar.
	Base64() string

	// Save saves the avatar to the specified destination.
	Save(dest string) error

	// Params returns the parameters of the avatar as a map.
	Params() map[string]string
}

PersonAvatar represents an interface for generating and manipulating avatar for person.

type SVGColor 

type SVGColor interface {
	// IsHex returns true if the color is in hexadecimal format.
	IsHex() bool

	// IsDefinition returns true if the color is an SVG definition.
	IsDefinition() bool
	// contains filtered or unexported methods
}

SVGColor represents an interface for SVG color handling.

func NewDefinition 

func NewDefinition(definition string) SVGColor

NewDefinition creates a new SVGColor as an SVG definition. The input definition should contain the placeholder id="{id}".

func NewHex 

func NewHex(color string) SVGColor

NewHex creates a new SVGColor in hexadecimal format. The input color should be a valid hex color string.

type SVGHairColor 

type SVGHairColor interface {
	// contains filtered or unexported methods
}

SVGHairColor is an interface that defines methods to resolve hair colors.

func NewHairColor 

func NewHairColor(base, shadow, highlight SVGColor) SVGHairColor

NewHairColor creates a new instance of SVGHairColor with the provided base, shadow, and highlight colors.

type SVGPalette 

type SVGPalette interface {
	// contains filtered or unexported methods
}

SVGPalette defines an interface for resolving Palette colors.

func NewPalette 

func NewPalette(shape, text, dress, shadow, decorator SVGColor) SVGPalette

NewPalette creates a new SVGPalette with the specified colors.

type SVGShape 

type SVGShape interface {
	// Shape returns the SVG shape as a string.
	Shape() string

	// Mask returns the SVG mask as a string.
	Mask() string
}

SVGShape is an interface that defines methods to resolve background shape and mask.

func NewShape 

func NewShape(shape, mask string) SVGShape

NewShape creates a new SVGShape with the given shape and mask. Shape support fill="{shape}" to colorize shape.

type SVGSkinColor 

type SVGSkinColor interface {
	// contains filtered or unexported methods
}

SVGSkinColor is an interface that defines methods to resolve skin colors.

func NewSkinColor 

func NewSkinColor(skin, shadow SVGColor) SVGSkinColor

NewSkinColor creates a new SVGSkinColor with the provided skin and shadow colors.

type Shape 

type Shape string

Shape defines preset background shape types for an avatar. 

const (
	ShapeFill    Shape = "fill"
	ShapeCircle  Shape = "circle"
	ShapePolygon Shape = "polygon"
)

type SkinColor 

type SkinColor string

SkinColor defines preset skin color types for an avatar. 

const (
	SkinWhite SkinColor = "white"
	SkinBrown SkinColor = "brown"
	SkinBlack SkinColor = "black"
)

type Sticker 

type Sticker string

Shape defines preset sticker types for an avatar.

type StickerAvatar 

type StickerAvatar interface {
	// Shape returns the background shape of the avatar.
	Shape() string

	// Palette returns the color palette of the avatar.
	Palette() string

	// Sticker returns the sticker of the avatar.
	Sticker() string

	// RandomizeShape randomizes the background shape of the avatar.
	RandomizeShape(only ...Shape) StickerAvatar

	// RandomizePalette randomizes the color palette of the avatar.
	RandomizePalette(only ...Palette) StickerAvatar

	// RandomizeSticker randomizes the sticker of the avatar.
	RandomizeSticker(only ...Sticker) StickerAvatar

	// Render returns the inline SVG representation of the avatar.
	Render() string

	// SVG returns the SVG representation of the avatar.
	SVG() string

	// Base64 returns the base64 encoded SVG representation of the avatar.
	Base64() string

	// Save saves the avatar to the specified destination.
	Save(dest string) error

	// Params returns the parameters of the avatar as a map.
	Params() map[string]string
}

type TextAvatar 

type TextAvatar interface {
	// Shape returns the background shape of the avatar.
	Shape() string

	// Palette returns the color palette of the avatar.
	Palette() string

	// Code returns the letter code of the avatar.
	Code() rune

	// Letter returns the letter  of the avatar.
	Letter() string

	// RandomizeShape randomizes the background shape of the avatar.
	RandomizeShape(only ...Shape) TextAvatar

	// RandomizePalette randomizes the color palette of the avatar.
	RandomizePalette(only ...Palette) TextAvatar

	// Render returns the inline SVG representation of the avatar.
	Render() string

	// SVG returns the SVG representation of the avatar.
	SVG() string

	// Base64 returns the base64 encoded SVG representation of the avatar.
	Base64() string

	// Save saves the avatar to the specified destination.
	Save(dest string) error

	// Params returns the parameters of the avatar as a map.
	Params() map[string]string
}

TextAvatar represents an interface for generating and manipulating avatar for text.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.