palettedb

README

palettedb

A desktop app and Go library for creating, browsing, exporting, and reusing color palettes built on gaul. Palettes are stored in a local SQLite database, and a set of well-known data-visualization colormaps ship built in.

Features

• Two kinds of palettes — discrete gradients and parametric sine palettes (see below).
• Built-in colormaps — viridis, plasma, inferno, magma, cividis, turbo, mako, rocket, flare, crest, vlag, icefire, and a couple of project sine palettes
• Live previews — every palette shows a continuous gradient strip and rows of discrete swatches.
• Export — write any palette to a GIMP palette (.gpl) or CSV with a configurable number of colors.
• Library API — fetch palettes by name for your own Go programs.

The two palette types

Discrete palettes

A discrete palette is a list of color stops, each at an adjustable position in [0, 1]. Colors between stops are interpolated (in HCL). Drag the ticks on the gradient to move stops, or edit the color/position directly in the table.

Sine palettes

This is a procedural palette introduced by the amazing Inigo Quilez. I use it all the time for generative art, especially shaders.

A sine (cosine-gradient) palette is defined by four RGB coefficient vectors A, B, C, D where the color at position t is

color(t) = A + B * cos(2π * (C * t + D))

This produces smooth, endlessly-cyclable gradients from just a few numbers. Lock axes to move them together, roll the dice to explore, or type exact values.

Install / run

Requires Go 1.26+.

go run github.com/aldernero/palettedb/cmd/palettedb@latest

or from a clone:

go build ./cmd/palettedb && ./palettedb
# or: make build

On Linux, the default build runs through XWayland. For a native-Wayland build (better multi-monitor HiDPI handling) install the dev headers (wayland-devel libxkbcommon-devel libdecor-devel wayland-protocols-devel on Fedora) and build with the wayland tag:

go run -tags wayland ./cmd/palettedb

The database lives at ~/.config/palettedb/palettedb.db (XDG). It is created on first run; built-in palettes work even with no database.

Using palettes from code

palettedb is also importable as a library. By-name lookups search your saved palettes first, then the built-ins — so viridis, turbo, warm-sunset, etc. resolve even against an empty (or missing) database.

package main

import (
	"fmt"
	"log"

	"github.com/aldernero/palettedb"
)

func main() {
	// Opens ~/.config/palettedb/palettedb.db (or use palettedb.Open(path)).
	db, err := palettedb.OpenDefault()
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// A discrete palette (built-in) as a gaul.Gradient.
	grad, err := db.LoadDiscreteByName("viridis")
	if err != nil {
		log.Fatal(err)
	}

	// Sample 8 evenly-spaced colors.
	for i := 0; i < 8; i++ {
		r, g, b, _ := grad.ColorAtStop(i, 8).RGBA()
		fmt.Printf("%d: #%02X%02X%02X\n", i, uint8(r>>8), uint8(g>>8), uint8(b>>8))
	}

	// A sine palette by name.
	sp, err := db.LoadSineByName("warm-sunset")
	if err != nil {
		log.Fatal(err)
	}
	mid := sp.ColorAt(0.5) // color at the midpoint
	fmt.Println(mid)
}

Both gaul.Gradient and gaul.SinePalette satisfy the gaul.Palette interface:

type Palette interface {
	ColorAt(t float64) color.Color    // t in [0,1]
	ColorAtStop(i, n int) color.Color // stop i of n (t = i/(n-1))
}

If you don't know the type ahead of time, use PaletteByName, which returns a gaul.Palette plus its kind:

p, kind, err := db.PaletteByName("turbo") // kind == "discrete"
if err != nil {
	log.Fatal(err)
}
c := p.ColorAt(0.42)

Development

make test   # go test ./...
make lint   # golangci-lint (v2), default and -tags wayland
make all    # vet + lint + test

Attribution & license

palettedb is licensed under the Apache License 2.0.

The built-in colormaps are third-party data used under their own licenses (CC0, Apache-2.0, and BSD-3-Clause) — see internal/builtins/THIRD_PARTY_NOTICES.md. UI icons are from Google Material Symbols (Apache-2.0) — see ui/resources/THIRD_PARTY_NOTICES.md.

Documentation

Overview

Package palettedb provides a public API for opening and querying the palettedb SQLite database from external programs.

Example

Example shows fetching palettes by name. By-name lookups search the user's saved palettes first, then the built-ins, so "viridis" and "warm-sunset" resolve even against an empty database.

package main

import (
	"fmt"
	"log"

	"github.com/aldernero/palettedb"
)

func main() {
	db, err := palettedb.OpenDefault()
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// A discrete palette (built-in) as a gaul.Gradient.
	grad, err := db.LoadDiscreteByName("viridis")
	if err != nil {
		log.Fatal(err)
	}
	for i := 0; i < 8; i++ {
		r, g, b, _ := grad.ColorAtStop(i, 8).RGBA()
		fmt.Printf("%d: #%02X%02X%02X\n", i, uint8(r>>8), uint8(g>>8), uint8(b>>8))
	}

	// A sine palette by name.
	sp, err := db.LoadSineByName("warm-sunset")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(sp.ColorAt(0.5))

	// When the type is unknown, PaletteByName returns a gaul.Palette + its kind.
	p, kind, err := db.PaletteByName("turbo")
	if err != nil {
		log.Fatal(err)
	}
	_ = p.ColorAt(0.42)
	fmt.Println(kind)
}

Index

• func BuiltinDiscreteByName(name string) (gaul.Gradient, error)
• func BuiltinNames(paletteType string) []string
• func BuiltinSineByName(name string) (gaul.SinePalette, error)
• func DefaultPath() (string, error)
• type DB
  • func Open(path string) (*DB, error)
  • func OpenDefault() (*DB, error)
  • func (d *DB) Close() error
  • func (d *DB) List() ([]Entry, error)
  • func (d *DB) ListNames(paletteType string) ([]string, error)
  • func (d *DB) LoadDiscreteByName(name string) (gaul.Gradient, error)
  • func (d *DB) LoadSineByName(name string) (gaul.SinePalette, error)
  • func (d *DB) PaletteByName(name string) (gaul.Palette, string, error)
• type Entry
  • func Builtins() []Entry

Examples

• Package

Functions

func BuiltinDiscreteByName

func BuiltinDiscreteByName(name string) (gaul.Gradient, error)

BuiltinDiscreteByName returns the built-in discrete palette with the given name (case-insensitive) as a gaul.Gradient. Unlike LoadDiscreteByName it needs no open database.

func BuiltinNames

func BuiltinNames(paletteType string) []string

BuiltinNames returns the names of built-in palettes of the given type ("sine" or "discrete") ordered by name.

func BuiltinSineByName

func BuiltinSineByName(name string) (gaul.SinePalette, error)

BuiltinSineByName returns the built-in sine palette with the given name (case-insensitive). Unlike LoadSineByName it needs no open database.

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the default database location used by OpenDefault (~/.config/palettedb/palettedb.db, honoring XDG_CONFIG_HOME).

Types

type DB

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

DB is an opened palette database.

func Open

func Open(path string) (*DB, error)

Open opens the palette database at path.

func OpenDefault

func OpenDefault() (*DB, error)

OpenDefault opens the palette database at the default XDG config path (~/.config/palettedb/palettedb.db).

func (*DB) Close

func (d *DB) Close() error

Close closes the database connection.

func (*DB) List

func (d *DB) List() ([]Entry, error)

List returns all palettes stored in the database ordered by name. Built-in palettes are not included.

func (*DB) ListNames

func (d *DB) ListNames(paletteType string) ([]string, error)

ListNames returns the names of stored palettes of the given type ("sine" or "discrete") ordered by name. Built-in palettes are not included.

func (*DB) LoadDiscreteByName

func (d *DB) LoadDiscreteByName(name string) (gaul.Gradient, error)

LoadDiscreteByName loads a discrete palette by name as a gaul.Gradient, searching the user's saved palettes first and then the built-in palettes. Returns an error if no discrete palette with that name exists in either.

func (*DB) LoadSineByName

func (d *DB) LoadSineByName(name string) (gaul.SinePalette, error)

LoadSineByName loads a sine palette by name, searching the user's saved palettes first and then the built-in palettes. Returns an error if no sine palette with that name exists in either.

func (*DB) PaletteByName

func (d *DB) PaletteByName(name string) (gaul.Palette, string, error)

PaletteByName looks up a palette of either type by name (saved palettes first, then built-ins) and returns it as a gaul.Palette along with its type ("sine" or "discrete"). Use this when the caller does not know the type.

type Entry

type Entry struct {
	Name        string
	Type        string // "sine" or "discrete"
	Description string
}

Entry describes a palette stored in the database.

func Builtins

func Builtins() []Entry

Builtins returns the read-only palettes compiled into the library (discrete colormaps such as viridis and turbo, plus sine palettes) ordered by name. They resolve through the same LoadSineByName/LoadDiscreteByName/PaletteByName lookups as stored palettes.