0
# Curves
1

2
The curves module provides Bézier curve functionality for mathematical paths, animation easing functions, and parametric curve operations. It supports arbitrary dimensional control points and degrees with efficient arc length parameterization.
3

4
## Capabilities
5

6
### Bézier Curve Creation
7

8
Create Bézier curves with arbitrary number of control points and dimensions.
9

10
```javascript { .api }
11
/**
12
 * Create a Bézier curve object with precomputed coefficients
13
 * @param {Array} points - Control points array (minimum 2 points)
14
 *   - For 1D: [n1, n2, n3, ...] or [[n1], [n2], [n3], ...]
15
 *   - For 2D+: [[x1,y1], [x2,y2], [x3,y3], ...]
16
 * @returns {Object} Bezier curve object with mathematical coefficients
17
 */
18
function create(points: Array<number> | Array<Array<number>>): Bezier;
19

20
/**
21
 * Calculate position along the curve at parameter t
22
 * @param {Number} t - Parameter value between 0 and 1 (inclusive)
23
 * @param {Object} bezier - Bezier curve object from create()
24
 * @returns {Number|Array} Position value(s) at parameter t
25
 */
26
function valueAt(t: number, bezier: Bezier): Array<number> | number;
27

28
/**
29
 * Calculate the first derivative (tangent/slope) at parameter t
30
 * @param {Number} t - Parameter value between 0 and 1 (inclusive)
31
 * @param {Object} bezier - Bezier curve object from create()
32
 * @returns {Number|Array} Tangent value(s) at parameter t
33
 */
34
function tangentAt(t: number, bezier: Bezier): Array<number> | number;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
const { curves } = require('@jscad/modeling');
41
const { bezier } = curves;
42

43
// Linear 1D curve for scaling
44
const scaleEasing = bezier.create([1, 2]);
45
const scaleFactor = bezier.valueAt(0.5, scaleEasing); // 1.5
46

47
// Quadratic 2D curve for animation paths
48
const animPath = bezier.create([[0, 0], [50, 100], [100, 0]]);
49
const position = bezier.valueAt(0.5, animPath); // [50, 50]
50
const direction = bezier.tangentAt(0.5, animPath); // [50, -100]
51

52
// Cubic 3D curve for complex paths
53
const spatialPath = bezier.create([
54
  [0, 0, 0],     // start point
55
  [0, 10, 5],    // control point 1
56
  [10, 0, -5],   // control point 2
57
  [10, 10, 0]    // end point
58
]);
59
```
60

61
### Arc Length Operations
62

63
Measure and parameterize curves by arc length for equal spacing and distance-based operations.
64

65
```javascript { .api }
66
/**
67
 * Calculate cumulative arc lengths along the curve
68
 * @param {Number} segments - Number of segments for approximation accuracy
69
 * @param {Object} bezier - Bezier curve object from create()
70
 * @returns {Array} Array of cumulative arc lengths (length = segments + 1)
71
 */
72
function lengths(segments: number, bezier: Bezier): Array<number>;
73

74
/**
75
 * Calculate total arc length of the curve
76
 * @param {Number} segments - Number of segments for approximation accuracy
77
 * @param {Object} bezier - Bezier curve object from create()
78
 * @returns {Number} Approximate total arc length
79
 */
80
function length(segments: number, bezier: Bezier): number;
81

82
/**
83
 * Convert arc length distance to parameter t value
84
 * @param {Object} options - Configuration object
85
 * @param {Number} [options.distance=0] - Arc length distance along curve
86
 * @param {Number} [options.segments=100] - Accuracy segments for approximation
87
 * @param {Object} bezier - Bezier curve object from create()
88
 * @returns {Number} Parameter t value (0-1) corresponding to arc length
89
 */
90
function arcLengthToT(options: {
91
  distance?: number,
92
  segments?: number
93
}, bezier: Bezier): number;
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
const { curves } = require('@jscad/modeling');
100
const { bezier } = curves;
101

102
const curve = bezier.create([[0, 0], [10, 5], [20, 0]]);
103

104
// Measure curve length
105
const totalLength = bezier.length(100, curve); // High accuracy with 100 segments
106

107
// Create equally spaced points along curve
108
const segments = 10;
109
const increment = totalLength / segments;
110
const equalPoints = [];
111

112
for (let i = 0; i <= segments; i++) {
113
  const distance = i * increment;
114
  const t = bezier.arcLengthToT({ distance, segments: 100 }, curve);
115
  const point = bezier.valueAt(t, curve);
116
  equalPoints.push(point);
117
}
118

119
// Get cumulative lengths for analysis
120
const cumLengths = bezier.lengths(50, curve);
121
const halfwayLength = cumLengths[25]; // Length at middle segment
122
```
123

124
## Type Definitions
125

126
```javascript { .api }
127
// Bézier curve object structure
128
type Bezier = {
129
  points: Array<number> | Array<Array<number>>;  // Control points
130
  pointType: string;                             // Point type identifier  
131
  dimensions: number;                            // Number of dimensions
132
  permutations: Array<number>;                   // Binomial coefficients
133
  tangentPermutations: Array<number>;            // Tangent coefficients
134
};
135

136
// Point type identifiers
137
type PointTypes = 
138
  | 'float_single'  // 1D curves: [n1, n2, n3, ...]
139
  | 'float_1'       // 1D curves: [[n1], [n2], [n3], ...]  
140
  | 'float_2'       // 2D curves: [[x,y], [x,y], ...]
141
  | 'float_3'       // 3D curves: [[x,y,z], [x,y,z], ...]
142
  | 'float_n';      // n-dimensional curves
143

144
// Arc length parameterization options
145
type ArcLengthToTOptions = {
146
  distance?: number;   // Arc length distance (default: 0)
147
  segments?: number;   // Accuracy segments (default: 100)
148
};
149
```
150

151
## Mathematical Foundation
152

153
The module implements the standard Bézier curve formula:
154

155
**Position**: `B(t) = Σ(C(n,i) * (1-t)^(n-i) * t^i * P_i)` where:
156
- `C(n,i)` = binomial coefficient `n!/(i!(n-i)!)`
157
- `n` = curve degree (number of control points - 1)
158
- `P_i` = control point i
159
- `t` = parameter (0 to 1)
160

161
**Tangent**: First derivative reduces degree by 1, using control point differences `n * (P_{i+1} - P_i)`
162

163
**Arc Length**: Euclidean distance approximation between evenly spaced parameter samples, with binary search for inverse parameterization.