wordclouds

README

Wordclouds in go.

How to use

wordCounts := map[string]int{"important":42, "noteworthy":30, "meh":3}

w := wordclouds.NewWordcloud(
	wordCounts,
	wordclouds.FontFile("fonts/myfont.ttf"),
	wordclouds.Height(2048),
	wordclouds.Width(2048),
)

img := w.Draw()

Options

• Output height and width
• Font: Must be a valid TTF file.
• Font max,min size
• Colors
• Background color
• Placement : random or circular
• Masking

Masking

A list of bounding boxes where the algorithm can not place words can be provided.

The Mask function can be used to create such a mask given a file and a masking color.

boxes := wordclouds.Mask(
	conf.Mask.File,
	conf.Width,
	conf.Height,
	conf.Mask.Color,
)

See the example folder for a fully working implementation.

Speed

Most wordclouds should take a few seconds to be generated. A spatial hashmap is used to find potential collisions.

There are two possible placement algorithm choices:

1. Random: the algorithms randomly tries to place the word anywhere in the image space.
   • If it can't find a spot after 500000 tries, it gives up and moves on to the next word. It's quite slow.
2. Spiral: the algorithm starts to place the words on concentric circles starting at the center of the image. It is very fast and is the default algorithm

Contributing

Feel free to create pull requests, I'll gladly review them!

Documentation

Index

• Constants
• type Box
  • func Mask(path string, width int, height int, exclude color.RGBA) []*Box
  • func (a *Box) String() string
• type Option
  • func BackgroundColor(color color.Color) Option
  • func Colors(colors []color.Color) Option
  • func Debug() Option
  • func FontFile(path string) Option
  • func FontMaxSize(max int) Option
  • func FontMinSize(min int) Option
  • func Height(h int) Option
  • func MaskBoxes(mask []*Box) Option
  • func RandomPlacement(do bool) Option
  • func Width(w int) Option
  • func WordSizeFunction(f string) Option
• type Options
• type Wordcloud
  • func NewWordcloud(wordList map[string]int, options ...Option) *Wordcloud
  • func (w *Wordcloud) Draw() image.Image
  • func (w *Wordcloud) Place(wc wordCount) bool

Constants

const (
	SizeFunctionLinear      = "linear"
	SizeFunctionSqrt        = "sqrt"
	SizeFunctionSqrtInverse = "sqrtinverse"
)

Types

type Box

type Box struct {
	Top    float64
	Left   float64
	Right  float64
	Bottom float64
}

func Mask

func Mask(path string, width int, height int, exclude color.RGBA) []*Box

Mask creates a slice of box structs from a given mask image to be passed to wordclouds.MaskBoxes.

func (*Box) String

func (a *Box) String() string

type Option

type Option func(*Options)

func BackgroundColor

func BackgroundColor(color color.Color) Option

Output file background color

func Colors

func Colors(colors []color.Color) Option

Colors to use for the words

func Debug

func Debug() Option

Draw bounding boxes around words

func FontFile

func FontFile(path string) Option

Path to font file

func FontMaxSize

func FontMaxSize(max int) Option

Max font size

func FontMinSize

func FontMinSize(min int) Option

Min font size

func Height

func Height(h int) Option

func MaskBoxes

func MaskBoxes(mask []*Box) Option

A list of bounding boxes where words can not be placed. See Mask

func RandomPlacement

func RandomPlacement(do bool) Option

Place words randomly

func Width

func Width(w int) Option

func WordSizeFunction

func WordSizeFunction(f string) Option

Set word font sizing function

type Options

type Options struct {
	FontMaxSize     int
	FontMinSize     int
	RandomPlacement bool
	FontFile        string
	Colors          []color.Color
	BackgroundColor color.Color
	Width           int
	Height          int
	Mask            []*Box
	SizeFunction    sizeFunction
	Debug           bool
}

type Wordcloud

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

Wordcloud object. Create one with NewWordcloud and use Draw() to get the image

func NewWordcloud

func NewWordcloud(wordList map[string]int, options ...Option) *Wordcloud

Initialize a wordcloud based on a map of word frequency.

func (*Wordcloud) Draw

func (w *Wordcloud) Draw() image.Image

Draw tries to place words one by one, starting with the ones with the highest counts

func (*Wordcloud) Place

func (w *Wordcloud) Place(wc wordCount) bool