pipeline

Documentation

Overview

Package pipeline orchestrates the full gowall color extraction and theme generation workflow.

Index

• func ApplyConstraints(ansi []color.Centroid, constraints map[int]SlotConstraint) ([]color.Centroid, map[int]bool)
• func ApplyGlobalTweak(ansi []color.Centroid, g GlobalAdjust) []color.Centroid
• func ParseHex(s string) (color.Centroid, error)
• type GlobalAdjust
  • func (g GlobalAdjust) IsZero() bool
• type Options
  • func DefaultOptions() Options
• type ProgressFunc
• type Result
  • func ResultFromThemeData(theme themes.ThemeData) (Result, error)
  • func Run(img image.Image, opts Options, progress ProgressFunc) (Result, error)
• type SlotConstraint
• type SlotTweak

Functions

func ApplyConstraints

func ApplyConstraints(ansi []color.Centroid, constraints map[int]SlotConstraint) ([]color.Centroid, map[int]bool)

ApplyConstraints applies all SlotConstraints to a 16-element ANSI slice. Pinned slots get exact colors. Locked slots have H/S/V channels overridden. Tweaked slots receive delta adjustments. All constrained slots are marked in the returned pinned set so downstream readability enforcement skips them.

func ApplyGlobalTweak

func ApplyGlobalTweak(ansi []color.Centroid, g GlobalAdjust) []color.Centroid

ApplyGlobalTweak applies GlobalAdjust (hue degrees + S/V percent scale) to every ANSI color after generation and before per-slot ApplyConstraints.

func ParseHex

func ParseHex(s string) (color.Centroid, error)

ParseHex parses a "#rrggbb" or "rrggbb" string into a Centroid. Returns error if invalid.

Types

type GlobalAdjust

type GlobalAdjust struct {
	HueDeg float64 // additive rotation in degrees
	SatPct float64 // saturation scale percent (typically about -100..100)
	ValPct float64 // value scale percent (typically about -100..100)
}

GlobalAdjust applies global hue shift and multiplicative saturation/value scaling as percentages: S' = S×(1+SatPct/100), V' = V×(1+ValPct/100). ValPct -50 halves value; SatPct -50 halves saturation (relative to each color, unlike additive dV).

func (GlobalAdjust) IsZero

func (g GlobalAdjust) IsZero() bool

IsZero reports whether no global adjustment is requested.

type Options

type Options struct {
	RetoneANSI      bool             // Use ANSI colors (standard or CustomANSI) retoned to palette
	CustomANSI      []color.Centroid // If RetoneANSI and len==16, use instead of StandardANSI16
	KMeansK         int
	KMeansIters     int
	MaxSamples      int
	Seed            int64 // If non-zero, use for deterministic k-means / reproducible results
	FilterThreshold float32
	Constraints     map[int]SlotConstraint // Per-slot constraints: pin, H/S/V lock, post-gen tweak
	BackgroundHex   string                 // Optional: override background color (#rrggbb)
	Clusterer       color.Clusterer        // nil = default (kmeans++)
	GlobalAdjust    GlobalAdjust           // global hue + S/V % scale; readability/spread run after (see Run)
}

Options configures the color extraction and theme pipeline.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns sensible defaults.

type ProgressFunc

type ProgressFunc func(stage, detail string)

ProgressFunc is called during the pipeline with a short stage name and optional detail.

type Result

type Result struct {
	Theme         themes.ThemeData
	Filtered      []color.Centroid
	ANSI          []color.Centroid
	Tones         []color.Centroid // from image palette (bg/fg ramp)
	TonesFromANSI []color.Centroid // from retoned ANSI colors (16-step ramp); only set when RetoneANSI was used
}

Result holds the pipeline output: theme data and intermediate palettes for display.

func ResultFromThemeData

func ResultFromThemeData(theme themes.ThemeData) (Result, error)

ResultFromThemeData builds a Result from theme data only (no image extraction). Filtered is empty. Used when loading a Gowall Color Reference file.

func Run

func Run(img image.Image, opts Options, progress ProgressFunc) (Result, error)

Run runs the full pipeline on the given image and returns the theme data and palettes. If progress is non-nil, it is called at each stage (e.g. "Loading", "Clustering", "Readability").

type SlotConstraint

type SlotConstraint struct {
	Pin   *color.Centroid // hard override: exact color, skips generation
	LockH *float64        // constrain hue [0,360] after generation; nil = free
	LockS *float64        // constrain saturation [0,1] after generation; nil = free
	LockV *float64        // constrain HSV value [0,1] after generation; nil = free
	Tweak SlotTweak       // post-generation delta adjustments (applied after locks)
}

SlotConstraint controls how a single ANSI slot color is generated. All fields are optional (nil / zero = no effect).

type SlotTweak

type SlotTweak struct {
	DeltaH float64 // degrees to rotate hue (circular)
	DeltaS float64 // add to HSV saturation (clamped 0–1)
	DeltaV float64 // add to HSV value (clamped 0–1)
}

SlotTweak holds additive HSV delta adjustments applied after generation and locking.