Color Spaces

/**
 * Returns an RGB color space interpolator with configurable gamma correction.
 * Default gamma is 1.0. Colors are converted to RGB if needed.
 * @param a - Starting color (string or d3.color object)
 * @param b - Ending color (string or d3.color object)  
 * @returns Interpolator function returning RGB color string
 */
function interpolateRgb(a: string | Color, b: string | Color): (t: number) => string;

/**
 * Returns a new RGB interpolator factory with specified gamma correction
 * @param gamma - Gamma correction value (typically 2.2 for displays)
 * @returns RGB interpolator factory with gamma correction
 */
interpolateRgb.gamma(gamma: number): typeof interpolateRgb;

import { interpolateRgb } from "d3-interpolate";

// Basic RGB interpolation
const rgbInterp = interpolateRgb("red", "blue");
console.log(rgbInterp(0.0)); // "rgb(255, 0, 0)"
console.log(rgbInterp(0.5)); // "rgb(128, 0, 128)"
console.log(rgbInterp(1.0)); // "rgb(0, 0, 255)"

// Gamma-corrected interpolation (more perceptually accurate)
const gammaRgb = interpolateRgb.gamma(2.2)("red", "blue");
console.log(gammaRgb(0.5)); // "rgb(188, 0, 67)"

// Works with hex colors
const hexInterp = interpolateRgb("#ff0000", "#0000ff");
console.log(hexInterp(0.5)); // "rgb(128, 0, 128)"

// Works with named colors
const namedInterp = interpolateRgb("steelblue", "brown");
console.log(namedInterp(0.5)); // "rgb(142, 92, 109)"

// Handles opacity
const opacityInterp = interpolateRgb("rgba(255,0,0,0.5)", "rgba(0,0,255,0.8)");
console.log(opacityInterp(0.5)); // "rgba(128, 0, 128, 0.65)"

/**
 * Returns a uniform nonrational B-spline interpolator through RGB colors.
 * Returns colors[0] at t=0 and colors[colors.length-1] at t=1.
 * @param colors - Array of color strings to interpolate through
 * @returns Interpolator function returning RGB color string
 */
function interpolateRgbBasis(colors: string[]): (t: number) => string;

/**
 * Returns a cyclical B-spline interpolator through RGB colors.
 * Has cyclical C² continuity when repeated around t in [0,1].
 * @param colors - Array of color strings to interpolate through
 * @returns Interpolator function returning RGB color string
 */
function interpolateRgbBasisClosed(colors: string[]): (t: number) => string;

import { interpolateRgbBasis, interpolateRgbBasisClosed } from "d3-interpolate";

// Rainbow progression
const rainbow = interpolateRgbBasis(["red", "orange", "yellow", "green", "blue", "purple"]);
console.log(rainbow(0.0));   // "rgb(255, 0, 0)" (red)
console.log(rainbow(0.2));   // smooth transition through orange
console.log(rainbow(0.5));   // smooth transition through yellow/green
console.log(rainbow(1.0));   // "rgb(128, 0, 128)" (purple)

// Cyclical color wheel
const wheel = interpolateRgbBasisClosed(["red", "yellow", "blue"]);
console.log(wheel(0.0));   // red
console.log(wheel(0.33));  // yellow
console.log(wheel(0.66));  // blue  
console.log(wheel(1.0));   // back to red (cyclical)

/**
 * Returns an HSL color space interpolator using the shortest path between hues.
 * Colors are converted to HSL if needed.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateHsl(a: string | Color, b: string | Color): (t: number) => string;

/**
 * Returns an HSL color space interpolator without shortest path optimization.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateHslLong(a: string | Color, b: string | Color): (t: number) => string;

import { interpolateHsl, interpolateHslLong } from "d3-interpolate";

// Shortest path (default)
const hslShort = interpolateHsl("hsl(10, 50%, 50%)", "hsl(350, 50%, 50%)");
console.log(hslShort(0.5)); // Hue ~0° (takes shorter 20° path)

// Long path (full circle)
const hslLong = interpolateHslLong("hsl(10, 50%, 50%)", "hsl(350, 50%, 50%)");
console.log(hslLong(0.5)); // Hue ~180° (takes longer 340° path)

// Rainbow with HSL
const hslRainbow = interpolateHsl("hsl(0, 100%, 50%)", "hsl(300, 100%, 50%)");
console.log(hslRainbow(0.5)); // "rgb(0, 255, 128)" (hue ~150°)

/**
 * Returns a CIELAB color space interpolator.
 * Colors are converted to CIELAB if needed. More perceptually uniform than RGB.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateLab(a: string | Color, b: string | Color): (t: number) => string;

import { interpolateLab } from "d3-interpolate";

// Perceptually uniform interpolation
const labInterp = interpolateLab("steelblue", "brown");
console.log(labInterp(0.5)); // More perceptually accurate midpoint

// Better for gradients
const labGradient = interpolateLab("#000000", "#ffffff");
console.log(labGradient(0.5)); // Perceptually middle gray

/**
 * Returns a CIELCh color space interpolator using shortest path between hues.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateHcl(a: string | Color, b: string | Color): (t: number) => string;

/**
 * Returns a CIELCh color space interpolator without shortest path optimization.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateHclLong(a: string | Color, b: string | Color): (t: number) => string;

import { interpolateHcl, interpolateHclLong } from "d3-interpolate";

// Perceptually uniform with hue control
const hclInterp = interpolateHcl("purple", "orange");
console.log(hclInterp(0.5)); // Perceptually accurate intermediate

// Long path for creative effects
const hclRainbow = interpolateHclLong("red", "red"); // Full hue circle

/**
 * Returns a Cubehelix color space interpolator with configurable gamma.
 * Designed for scientific data visualization with monotonic lightness.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateCubehelix(a: string | Color, b: string | Color): (t: number) => string;

/**
 * Returns a Cubehelix color space interpolator without shortest path optimization.
 * @param a - Starting color
 * @param b - Ending color
 * @returns Interpolator function returning RGB color string
 */
function interpolateCubehelixLong(a: string | Color, b: string | Color): (t: number) => string;

/**
 * Returns a new Cubehelix interpolator factory with specified gamma
 * @param gamma - Gamma correction value
 * @returns Cubehelix interpolator factory with gamma correction
 */
interpolateCubehelix.gamma(gamma: number): typeof interpolateCubehelix;
interpolateCubehelixLong.gamma(gamma: number): typeof interpolateCubehelixLong;

import { interpolateCubehelix } from "d3-interpolate";

// Scientific visualization (monotonic lightness)
const sciInterp = interpolateCubehelix("black", "white");
console.log(sciInterp(0.5)); // Perceptually middle brightness

// Gamma correction for displays
const gammaHelix = interpolateCubehelix.gamma(3.0)("purple", "green");
console.log(gammaHelix(0.5)); // Emphasizes high-intensity values

/**
 * Returns an interpolator between two hue angles using shortest path.
 * If either hue is NaN, uses the opposing value.
 * @param a - Starting hue angle (degrees)
 * @param b - Ending hue angle (degrees)
 * @returns Interpolator function returning hue angle in [0, 360)
 */
function interpolateHue(a: number, b: number): (t: number) => number;

import { interpolateHue } from "d3-interpolate";

// Shortest path hue interpolation
const hueInterp = interpolateHue(10, 350);
console.log(hueInterp(0.5)); // 0 (takes 20° path, not 340°)

// Full circle interpolation
const fullCircle = interpolateHue(0, 360);
console.log(fullCircle(0.25)); // 90
console.log(fullCircle(0.5));  // 180
console.log(fullCircle(0.75)); // 270

// Handle NaN values
const nanHue = interpolateHue(NaN, 180);
console.log(nanHue(0.5)); // 180 (uses opposing value)

// Standard display gamma
const displayRgb = interpolateRgb.gamma(2.2)("red", "green");

// Emphasize high-intensity values  
const brightCubehelix = interpolateCubehelix.gamma(3.0)("blue", "yellow");

// Gamma correction also works with CubehelixLong
const gammaCubehelixLong = interpolateCubehelixLong.gamma(2.2)("purple", "green");