Value Fitting & Mapping

/**
 * Returns normalized value of x with respect to interval [a, b]
 * Converts x from [a, b] range to [0, 1] range
 * If a equals b, returns 0
 * @param x - Value to normalize
 * @param a - Source interval minimum  
 * @param b - Source interval maximum
 * @returns Normalized value in [0, 1] range
 */
function norm(x: number, a: number, b: number): number;

/**
 * Maps value x from [a, b] range to [c, d] range
 * No clamping - values outside [a, b] will map beyond [c, d]  
 * @param x - Value to map
 * @param a - Source range minimum
 * @param b - Source range maximum  
 * @param c - Target range minimum
 * @param d - Target range maximum
 * @returns Mapped value in [c, d] range
 */
function fit(x: number, a: number, b: number, c: number, d: number): number;

/**
 * Clamped version of fit - clamps x to [a, b] before mapping to [c, d]
 * Ensures result is always within [c, d] range
 * @param x - Value to map  
 * @param a - Source range minimum
 * @param b - Source range maximum
 * @param c - Target range minimum  
 * @param d - Target range maximum
 * @returns Clamped and mapped value in [c, d] range
 */
function fitClamped(x: number, a: number, b: number, c: number, d: number): number;

/**
 * Maps value from [0, 1] range to [a, b] range with clamping
 * Assumes source range is [0, 1]
 * @param x - Value in [0, 1] range  
 * @param a - Target range minimum
 * @param b - Target range maximum
 * @returns Mapped value in [a, b] range
 */
function fit01(x: number, a: number, b: number): number;

/**
 * Maps value from [1, 0] range to [a, b] range with clamping
 * Assumes reverse-ordered source range [1, 0]
 * @param x - Value in [1, 0] range
 * @param a - Target range minimum  
 * @param b - Target range maximum
 * @returns Mapped value in [a, b] range
 */
function fit10(x: number, a: number, b: number): number;

/**
 * Maps value from [-1, 1] range to [a, b] range with clamping
 * Assumes source range is [-1, 1]  
 * @param x - Value in [-1, 1] range
 * @param a - Target range minimum
 * @param b - Target range maximum
 * @returns Mapped value in [a, b] range
 */
function fit11(x: number, a: number, b: number): number;

import { norm, fit, fitClamped, fit01, fit10, fit11 } from "@thi.ng/math/fit";

// Normalization examples
norm(5, 0, 10); // 0.5 (5 is halfway between 0 and 10)
norm(75, 50, 100); // 0.5 (75 is halfway between 50 and 100)
norm(5, 10, 10); // 0 (a equals b case)

// Range mapping without clamping
fit(5, 0, 10, 100, 200); // 150 (maps 5 from [0,10] to [100,200])
fit(15, 0, 10, 100, 200); // 250 (exceeds target range since no clamping)

// Range mapping with clamping  
fitClamped(5, 0, 10, 100, 200); // 150 (same as fit when in range)
fitClamped(15, 0, 10, 100, 200); // 200 (clamped to maximum)
fitClamped(-5, 0, 10, 100, 200); // 100 (clamped to minimum)

// Standard range fitting
fit01(0.3, 10, 20); // 13 (30% between 10 and 20)
fit01(1.5, 10, 20); // 20 (clamped to maximum)

fit10(0.3, 10, 20); // 17 (reverse: 30% from 20 towards 10)
fit10(1.5, 10, 20); // 10 (clamped to reverse maximum)

fit11(0, 10, 30); // 20 (center of range since 0 is center of [-1,1])
fit11(-1, 10, 30); // 10 (minimum since -1 is minimum of [-1,1])
fit11(1, 10, 30); // 30 (maximum since 1 is maximum of [-1,1])

// Practical applications
// Convert temperature: Celsius to Fahrenheit  
const celsiusToFahrenheit = (c: number) => fit(c, 0, 100, 32, 212);
celsiusToFahrenheit(0); // 32°F
celsiusToFahrenheit(100); // 212°F

// Convert screen coordinates
const screenToNormalized = (pixel: number, screenWidth: number) => 
  norm(pixel, 0, screenWidth);
screenToNormalized(400, 800); // 0.5 (center of screen)