0
# Angle Mathematics & Trigonometry
1

2
Angle manipulation, trigonometric functions, and geometric calculations. Includes fast approximations and specialized angle operations.
3

4
## Capabilities
5

6
### Angle Conversion
7

8
Functions for converting between different angle representations.
9

10
```typescript { .api }
11
/**
12
 * Converts angle from radians to degrees
13
 * @param theta - Angle in radians
14
 * @returns Angle in degrees
15
 */
16
function deg(theta: number): number;
17

18
/**
19
 * Converts angle from degrees to radians
20
 * @param theta - Angle in degrees
21
 * @returns Angle in radians
22
 */
23
function rad(theta: number): number;
24

25
/**
26
 * Converts angle from DMS (degrees, minutes, seconds) to decimal degrees
27
 * @param deg - Degrees component
28
 * @param min - Minutes component (0-59)
29
 * @param sec - Seconds component (0-59)
30
 * @returns Decimal angle in degrees
31
 */
32
function fromDMS(deg: number, min: number, sec: number): number;
33

34
/**
35
 * Converts decimal angle to DMS format
36
 * @param theta - Decimal angle in degrees
37
 * @returns 3-tuple [degrees, minutes, seconds] with sign preserved in degrees
38
 */
39
function toDMS(theta: number): [number, number, number];
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { deg, rad, fromDMS, toDMS } from "@thi.ng/math/angle";
46

47
// Basic conversions
48
const degrees = deg(Math.PI); // 180
49
const radians = rad(90); // 1.5707...
50

51
// DMS conversions
52
const decimal = fromDMS(45, 30, 0); // 45.5 degrees
53
const dms = toDMS(45.75); // [45, 45, 0]
54
```
55

56
### Angle Normalization
57

58
Functions for normalizing angles to specific ranges.
59

60
```typescript { .api }
61
/**
62
 * Projects theta into [0, 2π] interval
63
 * @param theta - Input angle in radians
64
 * @returns Angle normalized to [0, 2π]
65
 */
66
function absTheta(theta: number): number;
67

68
/**
69
 * Returns smallest absolute angle difference between a and b
70
 * Result will be in [0, π] interval
71
 * @param a - First angle in radians
72
 * @param b - Second angle in radians
73
 * @returns Smallest angle difference
74
 */
75
function angleDist(a: number, b: number): number;
76

77
/**
78
 * Like Math.atan2, but always returns angle in [0, TAU) interval
79
 * @param y - Y coordinate
80
 * @param x - X coordinate
81
 * @returns Absolute angle in [0, 2π] range
82
 */
83
function atan2Abs(y: number, x: number): number;
84

85
/**
86
 * Returns quadrant ID (0-3) of given angle
87
 * @param theta - Angle in radians
88
 * @returns Quadrant number: 0=I, 1=II, 2=III, 3=IV
89
 */
90
function quadrant(theta: number): number;
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { absTheta, angleDist, atan2Abs, quadrant } from "@thi.ng/math/angle";
97
import { PI } from "@thi.ng/math/api";
98

99
// Normalize to positive range
100
const normalized = absTheta(-PI / 4); // 7π/4
101

102
// Find shortest rotation between angles
103
const shortestPath = angleDist(PI / 6, 5 * PI / 6); // 2π/3
104

105
// Get absolute arctangent
106
const absAtan = atan2Abs(-1, 1); // 7π/4 instead of -π/4
107

108
// Determine quadrant
109
const quad = quadrant(3 * PI / 2); // 3 (fourth quadrant)
110
```
111

112
### Enhanced Trigonometric Functions
113

114
Extended trigonometric functions beyond the standard sin/cos/tan.
115

116
```typescript { .api }
117
/**
118
 * Returns vector of [sin(theta)*n, cos(theta)*n]
119
 * @param theta - Angle in radians
120
 * @param n - Scale factor (default: 1)
121
 * @returns [sin*n, cos*n] tuple
122
 */
123
function sincos(theta: number, n?: number): [number, number];
124

125
/**
126
 * Returns vector of [cos(theta)*n, sin(theta)*n]
127
 * @param theta - Angle in radians
128
 * @param n - Scale factor (default: 1)
129
 * @returns [cos*n, sin*n] tuple
130
 */
131
function cossin(theta: number, n?: number): [number, number];
132

133
/**
134
 * Cosecant function: 1/sin(theta)
135
 * Approaches ±Infinity for theta near multiples of π
136
 * @param theta - Angle in radians
137
 * @returns Cosecant value
138
 */
139
function csc(theta: number): number;
140

141
/**
142
 * Secant function: 1/cos(theta)
143
 * Approaches ±Infinity for theta near π/2 ± nπ
144
 * @param theta - Angle in radians
145
 * @returns Secant value
146
 */
147
function sec(theta: number): number;
148

149
/**
150
 * Cotangent function: cos/sin
151
 * Approaches ±Infinity for theta near multiples of π
152
 * @param theta - Angle in radians
153
 * @returns Cotangent value
154
 */
155
function cot(theta: number): number;
156
```
157

158
### Fast Trigonometric Approximations
159

160
High-performance approximations for trigonometric functions.
161

162
```typescript { .api }
163
/**
164
 * Approximates cos(xπ) for x in [-1, 1]
165
 * @param x - Normalized input [-1, 1]
166
 * @returns Approximate cosine value
167
 */
168
function normCos(x: number): number;
169

170
/**
171
 * Fast cosine approximation using polynomial
172
 * Maximum error ~0.00059693
173
 * @param theta - Angle in radians
174
 * @returns Approximate cosine value
175
 */
176
function fastCos(theta: number): number;
177

178
/**
179
 * Fast sine approximation using fastCos
180
 * @param theta - Angle in radians
181
 * @returns Approximate sine value
182
 */
183
function fastSin(theta: number): number;
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { sincos, fastCos, fastSin, csc } from "@thi.ng/math/angle";
190

191
// Simultaneous sin/cos calculation (more efficient)
192
const [s, c] = sincos(Math.PI / 4); // [0.707..., 0.707...]
193

194
// Fast approximations for performance-critical code
195
const approxCos = fastCos(1.5); // Fast but less accurate
196
const approxSin = fastSin(1.5);
197

198
// Extended trigonometric functions
199
const cosecant = csc(Math.PI / 6); // 2
200
```
201

202
### Geometric Functions
203

204
Functions for geometric calculations involving angles.
205

206
```typescript { .api }
207
/**
208
 * Law of Cosines: calculates third side of triangle
209
 * @param a - Length of first side
210
 * @param b - Length of second side
211
 * @param gamma - Inner angle between sides a and b (in radians)
212
 * @returns Length of third side
213
 */
214
function loc(a: number, b: number, gamma: number): number;
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
import { loc } from "@thi.ng/math/angle";
221
import { PI } from "@thi.ng/math/api";
222

223
// Triangle with sides 3, 4 and 90° angle between them
224
const hypotenuse = loc(3, 4, PI / 2); // 5 (Pythagorean theorem)
225

226
// General triangle calculation
227
const thirdSide = loc(7, 10, PI / 3); // Side opposite to 60° angle
228
```