scales

type BandScale ¶

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

BandScale implements a categorical scale with bands. Maps discrete domain values (categories) to continuous range bands. Used for bar charts, where each category gets a band with optional padding.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewBandScale([]string{"A", "B", "C"}, [2]units.Length{units.Px(0), units.Px(300)})
scale.Apply("A") // Returns units.Px(0) (start of first band)
scale.Apply("B") // Returns units.Px(100) (start of second band)
scale.Bandwidth() // Returns units.Px(100) (width of each band)

func NewBandScale(domain []string, range_ [2]units.Length) *BandScale

func (s *BandScale) Align(align float64) *BandScale

func (s *BandScale) Apply(value interface{}) units.Length

func (s *BandScale) ApplyValue(value interface{}) float64

func (s *BandScale) Bandwidth() units.Length

func (s *BandScale) Clone() Scale

func (s *BandScale) Domain() interface{}

func (s *BandScale) Index(value string) int

func (s *BandScale) Padding(padding float64) *BandScale

func (s *BandScale) PaddingInner(padding float64) *BandScale

func (s *BandScale) PaddingOuter(padding float64) *BandScale

func (s *BandScale) Range() [2]units.Length

func (s *BandScale) Round(round bool) *BandScale

func (s *BandScale) Step() units.Length

func (s *BandScale) Type() ScaleType

func (s *BandScale) Values() []string

func (s *BandScale) WithDomain(domain []string) *BandScale

func (s *BandScale) WithRange(range_ [2]units.Length) *BandScale

type BandScaleOptions ¶

type BandScaleOptions struct {
	Padding      float64 // Outer padding (0-1)
	PaddingInner float64 // Inner padding between bands (0-1)
	PaddingOuter float64 // Outer padding at edges (0-1)
	Align        float64 // Alignment within range (0-1, 0.5 = center)
	Round        bool    // Round band positions to integers
}

BandScaleOptions configures BandScale behavior

type CategoricalColorScale ¶

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

CategoricalColorScale maps discrete categories to distinct colors. Each category gets its own color, with cycling for domains larger than the color range.

Example:

colors := []color.Color{
  color.RGB(1, 0, 0), // Red
  color.RGB(0, 1, 0), // Green
  color.RGB(0, 0, 1), // Blue
}
scale := NewCategoricalColorScale(
  []string{"Group A", "Group B", "Group C"},
  colors,
)
scale.ApplyColor("Group A") // Returns red

Common uses: categorical data, group comparisons, qualitative differences

func NewCategoricalColorScale(domain []string, colors []color.Color) *CategoricalColorScale

func (s *CategoricalColorScale) Apply(value interface{}) units.Length

func (s *CategoricalColorScale) ApplyColor(value interface{}) color.Color

func (s *CategoricalColorScale) ApplyValue(value interface{}) float64

func (s *CategoricalColorScale) Clone() Scale

func (s *CategoricalColorScale) Colors() []color.Color

func (s *CategoricalColorScale) Domain() interface{}

func (s *CategoricalColorScale) Range() [2]units.Length

func (s *CategoricalColorScale) Type() ScaleType

func (s *CategoricalColorScale) Unknown(c color.Color) *CategoricalColorScale

type CategoricalScale ¶

type CategoricalScale interface {
	Scale

	// Values returns all domain values
	Values() []string

	// Index returns the index of a value in the domain
	Index(value string) int
}

CategoricalScale extends Scale for categorical scales (Band, Point, Ordinal)

type ColorInterpolatorFunc ¶

type ColorInterpolatorFunc func(t float64) color.Color

ColorInterpolatorFunc is a function that interpolates colors

type ColorScale ¶

type ColorScale interface {
	Scale

	// ApplyColor maps a domain value to a color
	ApplyColor(value interface{}) color.Color

	// Interpolator returns the color interpolation function
	Interpolator() func(t float64) color.Color
}

ColorScale maps domain values to colors

type ContinuousScale ¶

type ContinuousScale interface {
	Scale

	// Invert maps a range value back to a domain value
	Invert(value units.Length) float64

	// InvertValue maps a normalized value (0-1) back to a domain value
	InvertValue(t float64) float64

	// Ticks generates nice tick values for axes
	Ticks(count int) []float64

	// Nice rounds the domain to nice numbers
	Nice(count int) ContinuousScale

	// Clamp enables/disables clamping output to range
	Clamp(enabled bool) ContinuousScale
}

ContinuousScale extends Scale for continuous numeric scales

type DivergingColorScale ¶

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

DivergingColorScale maps a continuous domain to a diverging color gradient. Diverging scales use two distinct hues meeting at a neutral midpoint, ideal for data with a natural center or comparing deviations from a reference.

Example:

scale := NewDivergingColorScale(
  [2]float64{-100, 100},
  color.RGB(0, 0, 1), // Blue (negative)
  color.RGB(1, 1, 1), // White (neutral)
  color.RGB(1, 0, 0), // Red (positive)
)
scale.Apply(-50) // Returns light blue
scale.Apply(0)   // Returns white
scale.Apply(50)  // Returns light red

Common uses: temperature anomalies, profit/loss, before/after comparisons

func NewDivergingColorScale(domain [2]float64, start, mid, end color.Color) *DivergingColorScale

func (s *DivergingColorScale) Apply(value interface{}) units.Length

func (s *DivergingColorScale) ApplyColor(value interface{}) color.Color

func (s *DivergingColorScale) ApplyValue(value interface{}) float64

func (s *DivergingColorScale) Clamp(enabled bool) *DivergingColorScale

func (s *DivergingColorScale) Clone() Scale

func (s *DivergingColorScale) Domain() interface{}

func (s *DivergingColorScale) Interpolate(fn InterpolatorFunc) *DivergingColorScale

func (s *DivergingColorScale) Midpoint(value float64) *DivergingColorScale

func (s *DivergingColorScale) Range() [2]units.Length

func (s *DivergingColorScale) Samples(n int) []color.Color

func (s *DivergingColorScale) Space(space color.GradientSpace) *DivergingColorScale

func (s *DivergingColorScale) Type() ScaleType

type InterpolatorFunc ¶

type InterpolatorFunc func(t float64) float64

InterpolatorFunc is a function that interpolates between two values

type LinearScale ¶

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

LinearScale implements a continuous linear scale. Maps a continuous domain [d0, d1] to a continuous range [r0, r1] using linear interpolation.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewLinearScale([2]float64{0, 100}, [2]units.Length{units.Px(0), units.Px(500)})
scale.Apply(50) // Returns units.Px(250)
scale.Invert(units.Px(250)) // Returns 50

func NewLinearScale(domain [2]float64, range_ [2]units.Length) *LinearScale

func (s *LinearScale) Apply(value interface{}) units.Length

func (s *LinearScale) ApplyValue(value interface{}) float64

func (s *LinearScale) Clamp(enabled bool) ContinuousScale

func (s *LinearScale) Clone() Scale

func (s *LinearScale) Domain() interface{}

func (s *LinearScale) Invert(value units.Length) float64

func (s *LinearScale) InvertValue(t float64) float64

func (s *LinearScale) Nice(count int) ContinuousScale

func (s *LinearScale) Range() [2]units.Length

func (s *LinearScale) Ticks(count int) []float64

func (s *LinearScale) Type() ScaleType

func (s *LinearScale) WithDomain(domain [2]float64) *LinearScale

func (s *LinearScale) WithRange(range_ [2]units.Length) *LinearScale

type LogScale ¶

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

LogScale implements a continuous logarithmic scale. Maps a continuous domain [d0, d1] to a continuous range [r0, r1] using logarithmic interpolation.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewLogScale([2]float64{1, 1000}, [2]units.Length{units.Px(0), units.Px(500)})
scale.Apply(1)    // Returns units.Px(0)
scale.Apply(10)   // Returns units.Px(166.67) - 1/3 of way on log scale
scale.Apply(100)  // Returns units.Px(333.33) - 2/3 of way
scale.Apply(1000) // Returns units.Px(500)

Log scales are useful for data spanning multiple orders of magnitude: - Population (1K to 1B) - Wealth/income distributions - Scientific measurements - Earthquake magnitudes

func NewLogScale(domain [2]float64, range_ [2]units.Length) *LogScale

func (s *LogScale) Apply(value interface{}) units.Length

func (s *LogScale) ApplyValue(value interface{}) float64

func (s *LogScale) Base(base float64) *LogScale

func (s *LogScale) Clamp(enabled bool) ContinuousScale

func (s *LogScale) Clone() Scale

func (s *LogScale) Domain() interface{}

func (s *LogScale) Invert(value units.Length) float64

func (s *LogScale) InvertValue(t float64) float64

func (s *LogScale) Nice(count int) ContinuousScale

func (s *LogScale) Range() [2]units.Length

func (s *LogScale) Ticks(count int) []float64

func (s *LogScale) Type() ScaleType

func (s *LogScale) WithDomain(domain [2]float64) *LogScale

func (s *LogScale) WithRange(range_ [2]units.Length) *LogScale

type LogScaleOptions ¶

type LogScaleOptions struct {
	Base  float64 // Logarithm base (default: 10)
	Clamp bool    // Clamp output to range
}

LogScaleOptions configures LogScale

type NiceOptions ¶

type NiceOptions struct {
	Count int  // Desired number of ticks
	Floor bool // If true, floor the domain start
	Ceil  bool // If true, ceil the domain end
}

NiceOptions configures the Nice operation

type OrdinalScale ¶

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

OrdinalScale implements a categorical scale that maps discrete domain values to discrete range values. Unlike BandScale (which creates bands), OrdinalScale maps each domain value to a specific output value.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewOrdinalScale(
  []string{"small", "medium", "large"},
  []units.Length{units.Px(10), units.Px(20), units.Px(30)},
)
scale.Apply("medium") // Returns units.Px(20)

Ordinal scales are commonly used for: - Categorical color mapping - Size mapping (small/medium/large) - Shape mapping (circle/square/triangle) - Any discrete categorical encoding

func NewOrdinalScale(domain []string, range_ []units.Length) *OrdinalScale

func (s *OrdinalScale) Apply(value interface{}) units.Length

func (s *OrdinalScale) ApplyValue(value interface{}) float64

func (s *OrdinalScale) Clone() Scale

func (s *OrdinalScale) Domain() interface{}

func (s *OrdinalScale) Index(value string) int

func (s *OrdinalScale) Range() [2]units.Length

func (s *OrdinalScale) RangeValues() []units.Length

func (s *OrdinalScale) Type() ScaleType

func (s *OrdinalScale) Unknown(value units.Length) *OrdinalScale

func (s *OrdinalScale) Values() []string

func (s *OrdinalScale) WithDomain(domain []string) *OrdinalScale

func (s *OrdinalScale) WithRange(range_ []units.Length) *OrdinalScale

type PointScale ¶

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

PointScale implements a categorical scale that maps discrete domain values to evenly-spaced points. Unlike BandScale (which has bandwidth), PointScale maps to single positions with no width.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewPointScale(
  []string{"A", "B", "C"},
  [2]units.Length{units.Px(0), units.Px(300)},
)
scale.Apply("A") // Returns units.Px(0) (first point)
scale.Apply("B") // Returns units.Px(150) (middle point)
scale.Apply("C") // Returns units.Px(300) (last point)

Point scales are commonly used for: - Scatter plot categorical axes - Dot plots - Categorical axes in line charts - Any visualization needing evenly-spaced categorical positions

func NewPointScale(domain []string, range_ [2]units.Length) *PointScale

func (s *PointScale) Align(align float64) *PointScale

func (s *PointScale) Apply(value interface{}) units.Length

func (s *PointScale) ApplyValue(value interface{}) float64

func (s *PointScale) Clone() Scale

func (s *PointScale) Domain() interface{}

func (s *PointScale) Index(value string) int

func (s *PointScale) Padding(padding float64) *PointScale

func (s *PointScale) Range() [2]units.Length

func (s *PointScale) Round(round bool) *PointScale

func (s *PointScale) Step() units.Length

func (s *PointScale) Type() ScaleType

func (s *PointScale) Values() []string

func (s *PointScale) WithDomain(domain []string) *PointScale

func (s *PointScale) WithRange(range_ [2]units.Length) *PointScale

type PowScale ¶

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

PowScale implements a continuous power scale. Maps a continuous domain [d0, d1] to a continuous range [r0, r1] using power transformation (value^exponent).

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

scale := NewPowScale([2]float64{0, 100}, [2]units.Length{units.Px(0), units.Px(500)})
scale.Exponent(2) // Square transformation
scale.Apply(0)   // Returns units.Px(0)
scale.Apply(50)  // Returns units.Px(125) - (50/100)^2 * 500
scale.Apply(100) // Returns units.Px(500)

Power scales are useful for: - Area scales (exponent = 0.5 for sqrt, radius → area) - Volume scales (exponent = 1/3 for cube root) - Custom non-linear transformations - Emphasizing small or large values

func NewPowScale(domain [2]float64, range_ [2]units.Length) *PowScale

func NewSqrtScale(domain [2]float64, range_ [2]units.Length) *PowScale

func (s *PowScale) Apply(value interface{}) units.Length

func (s *PowScale) ApplyValue(value interface{}) float64

func (s *PowScale) Clamp(enabled bool) ContinuousScale

func (s *PowScale) Clone() Scale

func (s *PowScale) Domain() interface{}

func (s *PowScale) Exponent(exponent float64) *PowScale

func (s *PowScale) Invert(value units.Length) float64

func (s *PowScale) InvertValue(t float64) float64

func (s *PowScale) Nice(count int) ContinuousScale

func (s *PowScale) Range() [2]units.Length

func (s *PowScale) Ticks(count int) []float64

func (s *PowScale) Type() ScaleType

func (s *PowScale) WithDomain(domain [2]float64) *PowScale

func (s *PowScale) WithRange(range_ [2]units.Length) *PowScale

type PowScaleOptions ¶

type PowScaleOptions struct {
	Exponent float64 // Power exponent (default: 1)
	Clamp    bool    // Clamp output to range
}

PowScaleOptions configures PowScale

type QuantizeScaleOptions ¶

type QuantizeScaleOptions struct {
	Thresholds []float64 // Explicit threshold values
	Nice       bool      // Round thresholds to nice numbers
}

QuantizeScaleOptions configures QuantizeScale

type Scale ¶

type Scale interface {
	// Apply maps a domain value to a range value
	Apply(value interface{}) units.Length

	// ApplyValue maps a domain value to a normalized value (0-1 interpolation factor)
	ApplyValue(value interface{}) float64

	// Domain returns the input domain
	Domain() interface{}

	// Range returns the output range
	Range() [2]units.Length

	// Type returns the scale type
	Type() ScaleType

	// Clone creates a copy of this scale
	Clone() Scale
}

Scale is the universal interface for all scale types. Scales map from a domain (input data space) to a range (output visual space).

Ranges use units.Length to support relative units (%, px, em, etc.). Values stay abstract until final rendering, minimizing conversion errors.

Inspired by D3 scales and Observable Plot scales.

type ScaleConfig ¶

type ScaleConfig struct {
	Type         ScaleType
	Domain       interface{}     // Type depends on scale type
	Range        [2]units.Length // Output range with units
	Clamp        bool
	Nice         bool
	NiceCount    int
	Round        bool
	Padding      float64
	PaddingInner float64
	PaddingOuter float64
	Align        float64
	Base         float64      // For log scales
	Exponent     float64      // For pow scales
	Unknown      units.Length // For ordinal scales
	Interpolator interface{}  // InterpolatorFunc or ColorInterpolatorFunc
}

ScaleConfig is a universal configuration for creating scales

func DefaultScaleConfig() ScaleConfig

type ScaleType ¶

type ScaleType int

ScaleType identifies the type of scale

const (
	ScaleTypeLinear ScaleType = iota
	ScaleTypeLog
	ScaleTypePow
	ScaleTypeSqrt
	ScaleTypeOrdinal
	ScaleTypeBand
	ScaleTypePoint
	ScaleTypeTime
	ScaleTypeQuantize
	ScaleTypeQuantile
	ScaleTypeThreshold
	ScaleTypeIdentity
	ScaleTypeSequential
	ScaleTypeDiverging
)

func (t ScaleType) String() string

type SequentialColorScale ¶

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

SequentialColorScale maps a continuous domain to a sequential color gradient. Sequential scales use a single hue progressing from light to dark, ideal for representing magnitude or intensity.

Example:

scale := NewSequentialColorScale(
  [2]float64{0, 100},
  color.RGB(1, 1, 1), // White
  color.RGB(0, 0, 1), // Blue
)
scale.Apply(50) // Returns middle blue color

Common uses: heatmaps, choropleth maps, magnitude encoding

func NewSequentialColorScale(domain [2]float64, start, end color.Color) *SequentialColorScale

func (s *SequentialColorScale) Apply(value interface{}) units.Length

func (s *SequentialColorScale) ApplyColor(value interface{}) color.Color

func (s *SequentialColorScale) ApplyValue(value interface{}) float64

func (s *SequentialColorScale) Clamp(enabled bool) *SequentialColorScale

func (s *SequentialColorScale) Clone() Scale

func (s *SequentialColorScale) Domain() interface{}

func (s *SequentialColorScale) Interpolate(fn InterpolatorFunc) *SequentialColorScale

func (s *SequentialColorScale) Range() [2]units.Length

func (s *SequentialColorScale) Samples(n int) []color.Color

func (s *SequentialColorScale) Space(space color.GradientSpace) *SequentialColorScale

func (s *SequentialColorScale) Type() ScaleType

type SequentialScaleOptions ¶

type SequentialScaleOptions struct {
	Interpolator ColorInterpolatorFunc // Color interpolation function
	Clamp        bool                  // Clamp output
}

SequentialScaleOptions configures SequentialScale

type TickOptions ¶

type TickOptions struct {
	Count  int       // Desired number of ticks
	Format string    // Format string for tick labels
	Values []float64 // Explicit tick values (overrides Count)
}

TickOptions configures tick generation

type TimeInterval ¶

type TimeInterval int

TimeInterval represents time intervals for TimeScale

const (
	TimeIntervalMillisecond TimeInterval = iota
	TimeIntervalSecond
	TimeIntervalMinute
	TimeIntervalHour
	TimeIntervalDay
	TimeIntervalWeek
	TimeIntervalMonth
	TimeIntervalYear
)

type TimeScale ¶

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

TimeScale implements a continuous scale for temporal data. Maps a time domain [t0, t1] to a continuous range [r0, r1] using linear interpolation.

Ranges use units.Length to support relative units (%, px, em, etc.).

Example:

start := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2024, 12, 31, 0, 0, 0, 0, time.UTC)
scale := NewTimeScale(
  [2]time.Time{start, end},
  [2]units.Length{units.Px(0), units.Px(500)},
)
scale.Apply(time.Date(2024, 7, 1, 0, 0, 0, 0, time.UTC)) // Mid-year position

func NewTimeScale(domain [2]time.Time, range_ [2]units.Length) *TimeScale

func (s *TimeScale) Apply(value interface{}) units.Length

func (s *TimeScale) ApplyValue(value interface{}) float64

func (s *TimeScale) Clamp(enabled bool) *TimeScale

func (s *TimeScale) Clone() Scale

func (s *TimeScale) Domain() interface{}

func (s *TimeScale) Invert(value units.Length) time.Time

func (s *TimeScale) InvertValue(t float64) time.Time

func (s *TimeScale) Nice(interval TimeInterval) *TimeScale

func (s *TimeScale) Range() [2]units.Length

func (s *TimeScale) Ticks(count int) []time.Time

func (s *TimeScale) Type() ScaleType

func (s *TimeScale) WithDomain(domain [2]time.Time) *TimeScale

func (s *TimeScale) WithRange(range_ [2]units.Length) *TimeScale

type TimeTickOptions ¶

type TimeTickOptions struct {
	Interval TimeInterval // Interval for ticks (year, month, day, etc.)
	Count    int          // Desired number of ticks
	Format   string       // Time format string
}

TimeTickOptions configures time tick generation

type TimeValue ¶

type TimeValue struct {
	Time time.Time
}

TimeValue wraps a time.Time for use in scales

func (tv TimeValue) Value() float64