0
# Value Fitting & Mapping
1

2
Functions for mapping and fitting values between different numeric ranges, essential for scaling, normalization, and coordinate transformations.
3

4
## Capabilities
5

6
### Value Normalization
7

8
Normalize values to the standard [0,1] range for further processing.
9

10
```typescript { .api }
11
/**
12
 * Returns normalized value of x with respect to interval [a, b]
13
 * Converts x from [a, b] range to [0, 1] range
14
 * If a equals b, returns 0
15
 * @param x - Value to normalize
16
 * @param a - Source interval minimum  
17
 * @param b - Source interval maximum
18
 * @returns Normalized value in [0, 1] range
19
 */
20
function norm(x: number, a: number, b: number): number;
21
```
22

23
### Range Mapping
24

25
Map values from one numeric range to another with optional clamping.
26

27
```typescript { .api }
28
/**
29
 * Maps value x from [a, b] range to [c, d] range
30
 * No clamping - values outside [a, b] will map beyond [c, d]  
31
 * @param x - Value to map
32
 * @param a - Source range minimum
33
 * @param b - Source range maximum  
34
 * @param c - Target range minimum
35
 * @param d - Target range maximum
36
 * @returns Mapped value in [c, d] range
37
 */
38
function fit(x: number, a: number, b: number, c: number, d: number): number;
39

40
/**
41
 * Clamped version of fit - clamps x to [a, b] before mapping to [c, d]
42
 * Ensures result is always within [c, d] range
43
 * @param x - Value to map  
44
 * @param a - Source range minimum
45
 * @param b - Source range maximum
46
 * @param c - Target range minimum  
47
 * @param d - Target range maximum
48
 * @returns Clamped and mapped value in [c, d] range
49
 */
50
function fitClamped(x: number, a: number, b: number, c: number, d: number): number;
51
```
52

53
### Standard Range Fitting
54

55
Convenience functions for mapping from common standard ranges.
56

57
```typescript { .api }
58
/**
59
 * Maps value from [0, 1] range to [a, b] range with clamping
60
 * Assumes source range is [0, 1]
61
 * @param x - Value in [0, 1] range  
62
 * @param a - Target range minimum
63
 * @param b - Target range maximum
64
 * @returns Mapped value in [a, b] range
65
 */
66
function fit01(x: number, a: number, b: number): number;
67

68
/**
69
 * Maps value from [1, 0] range to [a, b] range with clamping
70
 * Assumes reverse-ordered source range [1, 0]
71
 * @param x - Value in [1, 0] range
72
 * @param a - Target range minimum  
73
 * @param b - Target range maximum
74
 * @returns Mapped value in [a, b] range
75
 */
76
function fit10(x: number, a: number, b: number): number;
77

78
/**
79
 * Maps value from [-1, 1] range to [a, b] range with clamping
80
 * Assumes source range is [-1, 1]  
81
 * @param x - Value in [-1, 1] range
82
 * @param a - Target range minimum
83
 * @param b - Target range maximum
84
 * @returns Mapped value in [a, b] range
85
 */
86
function fit11(x: number, a: number, b: number): number;
87
```
88

89
## Usage Examples
90

91
```typescript
92
import { norm, fit, fitClamped, fit01, fit10, fit11 } from "@thi.ng/math/fit";
93

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

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

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

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

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

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

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

125
// Convert screen coordinates
126
const screenToNormalized = (pixel: number, screenWidth: number) => 
127
  norm(pixel, 0, screenWidth);
128
screenToNormalized(400, 800); // 0.5 (center of screen)
129
```