identicon

README

Identicon

A golang library for Identicon generation

This Go library helps to generate deterministic Identicons from strings, like these:

---

⚠️ v1.0 brings BREAKING CHANGES ⚠️

The API changed and also the internal hashing algorithm, so identicons generated after v0.3.2 will look different.

---

Usage:

1. Get it:

go get github.com/tsdtsdtsd/identicon

1. Create a new identicon:

black := color.RGBA{0, 0, 0, 255}
red := color.RGBA{255, 0, 0, 255}

icon, err := identicon.New(
    "gary@example.com", 
    // optional:
    identicon.WithResolution(7),      // default: 5
    identicon.WithImageSize(210),     // default: 100
    identicon.WithBGColor(black),     // default: light gray R:240 G:240 B:240 A:255 (#f0f0f0)
    identicon.WithFGColor(red),       // default: based on identifier
    identicon.WithHasher(sha1.New()), // default: fnv128
)
if err != nil {
    log.Fatal(err)
}

1. Create an image:

   Image() returns an *Image which implements Go's image.Image interface, so you can use the result directly to encode it as an image file:

file, err := os.Create("identicon-gary.png")
if err != nil {
    log.Fatal(err)
}

err = png.Encode(file, icon.Image())
if err != nil {
    log.Fatal(err)
}

file.Close()

Image also implements Go's draw.Image interface, you can use it to change the output further:

    // TODO: example 
    // draw.Draw(icon, ...

Banner example

You can find another example in the /_example folder. It contains an application, which generates the above image. It also helps me to test the algorythm for changes.

Documentation

Index

• type Identicon
  • func New(identifier string, opts ...Option) (*Identicon, error)
  • func (ic *Identicon) HashString() string
  • func (ic *Identicon) Image() *Image
  • func (ic *Identicon) Matrix() [][]bool
  • func (ic *Identicon) Options() *Options
• type Image
  • func (img *Image) At(x, y int) color.Color
  • func (img *Image) Bounds() image.Rectangle
  • func (img *Image) ColorModel() color.Model
  • func (img *Image) NRGBAAt(x, y int) color.NRGBA
  • func (img *Image) Set(x, y int, c color.Color)
• type Option
  • func WithBGColor(c color.Color) Option
  • func WithFGColor(c color.Color) Option
  • func WithHasher(hasher hash.Hash) Option
  • func WithImageSize(size int) Option
  • func WithResolution(resolution int) Option
• type Options
  • func DefaultOptions() *Options

Examples

• New

Types

type Identicon

type Identicon struct {
	Identifier string
	// contains filtered or unexported fields
}

Identicon defines an identicon.

func New

func New(identifier string, opts ...Option) (*Identicon, error)

New returns the identicon for given identifier. Additional options can specify the identicon. DefaultOptions() will be used as a baseline.

Example

package main

import (
	"image/color"
	"image/png"
	"log"
	"os"

	"github.com/tsdtsdtsd/identicon"
)

func main() {
	icon, err := identicon.New("michael@example.com", identicon.WithBGColor(color.RGBA{220, 220, 220, 255}))
	if err != nil {
		log.Fatal(err)
	}

	file, err := os.Create("identicon.png")
	if err != nil {
		log.Fatal(err)
	}

	err = png.Encode(file, icon.Image())
	if err != nil {
		log.Fatal(err)
	}

	file.Close()
}

func (*Identicon) HashString

func (ic *Identicon) HashString() string

HashString returns the hexadacimal representation of the hash as string.

func (*Identicon) Image

func (ic *Identicon) Image() *Image

Image generates and returns the image.

func (*Identicon) Matrix

func (ic *Identicon) Matrix() [][]bool

Matrix returns the identicons "tile map".

func (*Identicon) Options

func (ic *Identicon) Options() *Options

Options returns the identicons options.

type Image

type Image struct {
	// contains filtered or unexported fields
}

func (*Image) At

func (img *Image) At(x, y int) color.Color

At returns the color of the pixel at (x, y). At(Bounds().Min.X, Bounds().Min.Y) returns the upper-left pixel of the grid. At(Bounds().Max.X-1, Bounds().Max.Y-1) returns the lower-right one.

func (*Image) Bounds

func (img *Image) Bounds() image.Rectangle

Bounds returns the domain for which At can return non-zero color.

func (*Image) ColorModel

func (img *Image) ColorModel() color.Model

ColorModel returns the Image's color model.

func (*Image) NRGBAAt

func (img *Image) NRGBAAt(x, y int) color.NRGBA

NRGBAAt returns the color of the pixel at (x, y) as color.NRGBA.

func (*Image) Set

func (img *Image) Set(x, y int, c color.Color)

Set stores given color at position (x, y).

type Option

type Option func(*Identicon)

Option changes a single option

func WithBGColor

func WithBGColor(c color.Color) Option

WithBGColor returns an option that sets the identicon's background color to given color.

func WithFGColor

func WithFGColor(c color.Color) Option

WithFGColor returns an option that sets the identicon's background color to given color.

func WithHasher

func WithHasher(hasher hash.Hash) Option

WithHasher returns an option that sets the identicon's hash generator. The option will be discarded silently if nil given.

func WithImageSize

func WithImageSize(size int) Option

WithImageSize returns an option that sets the identicon's image size to given amount. The option will be discarded silently if given value is non-positive.

func WithResolution

func WithResolution(resolution int) Option

WithResolution returns an option that sets the identicon's grid resolution to given amount. The option will be discarded silently if given value is non-positive.

type Options

type Options struct {
	Resolution int
	ImageSize  int
	Hasher     hash.Hash
	BGColor    color.Color
	FGColor    color.Color
}

Options define customizable settings

func DefaultOptions

func DefaultOptions() *Options

DefaultOptions are the baseline for a new identicon