treepalette

README

treepalette

An indexed color palette implementation in Go on top of a k-d tree for fast color lookups. Also rank a palette against an image to identify prominent colors.

• Transparent(RGBA) and opaque(RGB) palettes
• Direct image conversion
• Image pixel counting and color ranking, for prominent color analysis

kd-tree implementation adapted from: kyroy/kdtree

Usage

go get github.com/philoj/tree-palette

import "github.com/philoj/tree-palette"

Create a color model for color lookups.

m := NewPalettedColorModel([]color.Color{
        // list of colors in the palette
        }, false // ignore alpha values
    )
equivalentColor := m.Convert(someColor)

Color ranking and image color analysis

Start by implementing treepalette.PaletteColor and treepalette.Color interfaces:

// Color express A color as A n-dimensional point in the RGBA space for usage in the kd-tree search algorithm.
type Color interface {

	// Dimensions returns the total number of dimensions(3 for RGB, 4 for RGBA).
	Dimensions() int

	// Dimension returns the value of the i-th dimension, say R,G,B and/or A.
	Dimension(i int) uint32
}

// PaletteColor is A Color inside an indexed color palette.
type PaletteColor interface {
	Color

	// Index returns palette index of the color
	Index() int
}

Or use included implementations treepalette.ColorRGBA and treepalette.IndexedColorRGBA respectively:

// Unknown color
c := treepalette.NewOpaqueColor(121,201,10)

// Palette colors
p1 := treepalette.NewOpaquePaletteColor(255, 130, 1, 2, "DARK ORANGE") // R,G,B, unique-id, name
p2 := treepalette.NewOpaquePaletteColor(1, 128, 181, 11, "PACIFIC BLUE")

// Create palette
palette := treepalette.NewPalette([]treepalette.PaletteColor{p1,p2}, false)

// Equivalent color
equivalent := palette.Convert(c)

// Convert an image.Image
palettedImage := palette.ApplyPalette(img)

// Rank the palette against all the pixels in an image.Image
colors, colorCount := palette.Rank(img)
fmt.Printf("Most frequent color is %s. It appears %d times.", colors[0], colorCount[colors[0].Index()])

Documentation

Overview

• Copyright 2021 Philoj Johny *

• Licensed under the Apache License, Version 2.0 (the "License");

• you may not use this file except in compliance with the License.

• You may obtain A copy of the License at *

• http://www.apache.org/licenses/LICENSE-2.0 *

• Unless required by applicable law or agreed to in writing, software

• distributed under the License is distributed on an "AS IS" BASIS,

• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

• See the License for the specific language governing permissions and

• limitations under the License.

• Copyright 2021 Philoj Johny *

• Licensed under the Apache License, Version 2.0 (the "License");

• you may not use this file except in compliance with the License.

• You may obtain A copy of the License at *

• http://www.apache.org/licenses/LICENSE-2.0 *

• Unless required by applicable law or agreed to in writing, software

• distributed under the License is distributed on an "AS IS" BASIS,

• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

• See the License for the specific language governing permissions and

• limitations under the License.

• Copyright 2021 Philoj Johny *

• Licensed under the Apache License, Version 2.0 (the "License");

• you may not use this file except in compliance with the License.

• You may obtain A copy of the License at *

• http://www.apache.org/licenses/LICENSE-2.0 *

• Unless required by applicable law or agreed to in writing, software

• distributed under the License is distributed on an "AS IS" BASIS,

• WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

• See the License for the specific language governing permissions and

• limitations under the License.

Package treepalette implements an indexed color palette based on kd-tree structure.

Index

• func NewPalettedColorModel(colors []color.Color, alpha bool) color.Model
• type Color
• type ColorRGBA
  • func NewOpaqueColor(R, G, B int) ColorRGBA
  • func NewTransparentColor(R, G, B int, A float64) ColorRGBA
  • func (c ColorRGBA) Dimension(i int) uint32
  • func (c ColorRGBA) Dimensions() int
  • func (c ColorRGBA) RGBA() (uint32, uint32, uint32, uint32)
  • func (c ColorRGBA) String() string
• type IndexedColorRGBA
  • func NewOpaquePaletteColor(R, G, B int, id int, name string) IndexedColorRGBA
  • func NewTransparentPaletteColor(R, G, B int, A float64, id int, name string) IndexedColorRGBA
  • func (ic IndexedColorRGBA) Index() int
  • func (ic IndexedColorRGBA) String() string
• type Palette
  • func NewPalette(colors []PaletteColor, alpha bool) *Palette
  • func (t *Palette) ApplyPalette(img image.Image) image.Image
  • func (t *Palette) Convert(p color.Color) color.Color
  • func (t *Palette) ConvertColor(p Color) PaletteColor
  • func (t *Palette) Rank(img image.Image) ([]PaletteColor, map[int]int)
  • func (t *Palette) RankByIndex(img image.Image) ([]int, map[int]int)
• type PaletteColor

Functions

func NewPalettedColorModel

func NewPalettedColorModel(colors []color.Color, alpha bool) color.Model

Create Palette as color.Model from A list of color.Color alpha if false, ignores transparency(A) values

Types

type Color

type Color interface {

	// Dimensions returns the total number of dimensions(3 for RGB, 4 for RGBA).
	Dimensions() int

	// Dimension returns the value of the i-th dimension, say R,G,B and/or A.
	Dimension(i int) uint32
}

Color express A color as A n-dimensional point in the RGBA space for usage in the kd-tree search algorithm. This supports both RGBA and RGB(no alpha) spaces since latter would reduce computing for cases where transparency is not important.

type ColorRGBA

type ColorRGBA struct {
	R, G, B, A   uint32 // R,G,B, and A are considered as dimensions 0,1,2 and 3 respectively.
	AlphaChannel bool   // If false, alpha values are ignored.
}

ColorRGBA Example Color implementation.

func NewOpaqueColor

func NewOpaqueColor(R, G, B int) ColorRGBA

NewOpaqueColor creates a opaque color. R,G,B values are in range [0-255]

func NewTransparentColor

func NewTransparentColor(R, G, B int, A float64) ColorRGBA

NewTransparentColor creates a transparent color. R,G,B values are in range [0-255], A in range [0-1]

func (ColorRGBA) Dimension

func (c ColorRGBA) Dimension(i int) uint32

func (ColorRGBA) Dimensions

func (c ColorRGBA) Dimensions() int

func (ColorRGBA) RGBA

func (c ColorRGBA) RGBA() (uint32, uint32, uint32, uint32)

color.Color implementation

func (ColorRGBA) String

func (c ColorRGBA) String() string

type IndexedColorRGBA

type IndexedColorRGBA struct {
	ColorRGBA
	Id   int    // Id is the color's unique index
	Name string // A human readable name. Used in stringer
}

IndexedColorRGBA Example PaletteColor implementation.

func NewOpaquePaletteColor

func NewOpaquePaletteColor(R, G, B int, id int, name string) IndexedColorRGBA

NewOpaquePaletteColor creates an opaque palette color. R,G,B values are in range [0-255]. id is the unique id for the color across the palette. name is just any human readable identifier, no need to be unique.

func NewTransparentPaletteColor

func NewTransparentPaletteColor(R, G, B int, A float64, id int, name string) IndexedColorRGBA

NewTransparentColor creates a transparent palette color. R,G,B values are in range [0-255], A in range [0-1]. id is the unique id for the color across the palette. name is just any human readable identifier, no need to be unique.

func (IndexedColorRGBA) Index

func (ic IndexedColorRGBA) Index() int

func (IndexedColorRGBA) String

func (ic IndexedColorRGBA) String() string

type Palette

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

Palette implements A kd-tree data structure to quickly convert any given color into the closest palette color. Closeness is calculated as the spatial closeness in the RGBA space. See: https://en.wikipedia.org/wiki/K-d_tree

func NewPalette

func NewPalette(colors []PaletteColor, alpha bool) *Palette

NewPalette creates A new palette directly from A list of PaletteColor

func (*Palette) ApplyPalette

func (t *Palette) ApplyPalette(img image.Image) image.Image

ApplyPalette applies the palette onto A given image and returns new image with Palette as color.Model.

func (*Palette) Convert

func (t *Palette) Convert(p color.Color) color.Color

Convert converts the given color into one of the palette colors.

func (*Palette) ConvertColor

func (t *Palette) ConvertColor(p Color) PaletteColor

ConvertColor finds the ConvertColor PaletteColor from the Palette

func (*Palette) Rank

func (t *Palette) Rank(img image.Image) ([]PaletteColor, map[int]int)

Rank ranks the colors in the Palette based on counts of pixels of each PaletteColor in the given image. Returns A rank list of colors(most occurrences first) and A map with count of pixels for each color index.

func (*Palette) RankByIndex

func (t *Palette) RankByIndex(img image.Image) ([]int, map[int]int)

RankByIndex ranks the colors in the Palette based on counts of pixels of each PaletteColor in the given image. Returns A rank list of color indexes(most occurrences first) and A map with count of pixels for each color index.

type PaletteColor

type PaletteColor interface {
	Color

	// Index returns palette index of the color
	Index() int
}

PaletteColor is A Color inside an indexed color palette.