@pawells/math-extended 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +319 -0
  3. package/build/angles.d.ts +31 -0
  4. package/build/angles.d.ts.map +1 -0
  5. package/build/angles.js +85 -0
  6. package/build/angles.js.map +1 -0
  7. package/build/angles.spec.d.ts +2 -0
  8. package/build/angles.spec.d.ts.map +1 -0
  9. package/build/angles.spec.js +147 -0
  10. package/build/angles.spec.js.map +1 -0
  11. package/build/clamp.d.ts +17 -0
  12. package/build/clamp.d.ts.map +1 -0
  13. package/build/clamp.js +19 -0
  14. package/build/clamp.js.map +1 -0
  15. package/build/clamp.spec.d.ts +2 -0
  16. package/build/clamp.spec.d.ts.map +1 -0
  17. package/build/clamp.spec.js +19 -0
  18. package/build/clamp.spec.js.map +1 -0
  19. package/build/documentation-validation.spec.d.ts +11 -0
  20. package/build/documentation-validation.spec.d.ts.map +1 -0
  21. package/build/documentation-validation.spec.js +401 -0
  22. package/build/documentation-validation.spec.js.map +1 -0
  23. package/build/index.d.ts +8 -0
  24. package/build/index.d.ts.map +1 -0
  25. package/build/index.js +8 -0
  26. package/build/index.js.map +1 -0
  27. package/build/interpolation.d.ts +175 -0
  28. package/build/interpolation.d.ts.map +1 -0
  29. package/build/interpolation.js +369 -0
  30. package/build/interpolation.js.map +1 -0
  31. package/build/interpolation.spec.d.ts +2 -0
  32. package/build/interpolation.spec.d.ts.map +1 -0
  33. package/build/interpolation.spec.js +480 -0
  34. package/build/interpolation.spec.js.map +1 -0
  35. package/build/matrices/arithmetic.d.ts +411 -0
  36. package/build/matrices/arithmetic.d.ts.map +1 -0
  37. package/build/matrices/arithmetic.js +954 -0
  38. package/build/matrices/arithmetic.js.map +1 -0
  39. package/build/matrices/arithmetic.spec.d.ts +2 -0
  40. package/build/matrices/arithmetic.spec.d.ts.map +1 -0
  41. package/build/matrices/arithmetic.spec.js +915 -0
  42. package/build/matrices/arithmetic.spec.js.map +1 -0
  43. package/build/matrices/asserts.d.ts +306 -0
  44. package/build/matrices/asserts.d.ts.map +1 -0
  45. package/build/matrices/asserts.js +396 -0
  46. package/build/matrices/asserts.js.map +1 -0
  47. package/build/matrices/asserts.spec.d.ts +2 -0
  48. package/build/matrices/asserts.spec.d.ts.map +1 -0
  49. package/build/matrices/asserts.spec.js +565 -0
  50. package/build/matrices/asserts.spec.js.map +1 -0
  51. package/build/matrices/core.d.ts +168 -0
  52. package/build/matrices/core.d.ts.map +1 -0
  53. package/build/matrices/core.js +457 -0
  54. package/build/matrices/core.js.map +1 -0
  55. package/build/matrices/core.spec.d.ts +2 -0
  56. package/build/matrices/core.spec.d.ts.map +1 -0
  57. package/build/matrices/core.spec.js +634 -0
  58. package/build/matrices/core.spec.js.map +1 -0
  59. package/build/matrices/decompositions.d.ts +326 -0
  60. package/build/matrices/decompositions.d.ts.map +1 -0
  61. package/build/matrices/decompositions.js +816 -0
  62. package/build/matrices/decompositions.js.map +1 -0
  63. package/build/matrices/decompositions.spec.d.ts +2 -0
  64. package/build/matrices/decompositions.spec.d.ts.map +1 -0
  65. package/build/matrices/decompositions.spec.js +195 -0
  66. package/build/matrices/decompositions.spec.js.map +1 -0
  67. package/build/matrices/index.d.ts +9 -0
  68. package/build/matrices/index.d.ts.map +1 -0
  69. package/build/matrices/index.js +9 -0
  70. package/build/matrices/index.js.map +1 -0
  71. package/build/matrices/linear-algebra.d.ts +64 -0
  72. package/build/matrices/linear-algebra.d.ts.map +1 -0
  73. package/build/matrices/linear-algebra.js +253 -0
  74. package/build/matrices/linear-algebra.js.map +1 -0
  75. package/build/matrices/linear-algebra.spec.d.ts +2 -0
  76. package/build/matrices/linear-algebra.spec.d.ts.map +1 -0
  77. package/build/matrices/linear-algebra.spec.js +355 -0
  78. package/build/matrices/linear-algebra.spec.js.map +1 -0
  79. package/build/matrices/normalization.d.ts +62 -0
  80. package/build/matrices/normalization.d.ts.map +1 -0
  81. package/build/matrices/normalization.js +167 -0
  82. package/build/matrices/normalization.js.map +1 -0
  83. package/build/matrices/normalization.spec.d.ts +2 -0
  84. package/build/matrices/normalization.spec.d.ts.map +1 -0
  85. package/build/matrices/normalization.spec.js +335 -0
  86. package/build/matrices/normalization.spec.js.map +1 -0
  87. package/build/matrices/transformations.d.ts +484 -0
  88. package/build/matrices/transformations.d.ts.map +1 -0
  89. package/build/matrices/transformations.js +592 -0
  90. package/build/matrices/transformations.js.map +1 -0
  91. package/build/matrices/transformations.spec.d.ts +2 -0
  92. package/build/matrices/transformations.spec.d.ts.map +1 -0
  93. package/build/matrices/transformations.spec.js +755 -0
  94. package/build/matrices/transformations.spec.js.map +1 -0
  95. package/build/matrices/types.d.ts +134 -0
  96. package/build/matrices/types.d.ts.map +1 -0
  97. package/build/matrices/types.js +6 -0
  98. package/build/matrices/types.js.map +1 -0
  99. package/build/quaternions/asserts.d.ts +77 -0
  100. package/build/quaternions/asserts.d.ts.map +1 -0
  101. package/build/quaternions/asserts.js +175 -0
  102. package/build/quaternions/asserts.js.map +1 -0
  103. package/build/quaternions/asserts.spec.d.ts +2 -0
  104. package/build/quaternions/asserts.spec.d.ts.map +1 -0
  105. package/build/quaternions/asserts.spec.js +320 -0
  106. package/build/quaternions/asserts.spec.js.map +1 -0
  107. package/build/quaternions/conversions.d.ts +73 -0
  108. package/build/quaternions/conversions.d.ts.map +1 -0
  109. package/build/quaternions/conversions.js +179 -0
  110. package/build/quaternions/conversions.js.map +1 -0
  111. package/build/quaternions/conversions.spec.d.ts +2 -0
  112. package/build/quaternions/conversions.spec.d.ts.map +1 -0
  113. package/build/quaternions/conversions.spec.js +344 -0
  114. package/build/quaternions/conversions.spec.js.map +1 -0
  115. package/build/quaternions/core.d.ts +203 -0
  116. package/build/quaternions/core.d.ts.map +1 -0
  117. package/build/quaternions/core.js +374 -0
  118. package/build/quaternions/core.js.map +1 -0
  119. package/build/quaternions/core.spec.d.ts +2 -0
  120. package/build/quaternions/core.spec.d.ts.map +1 -0
  121. package/build/quaternions/core.spec.js +294 -0
  122. package/build/quaternions/core.spec.js.map +1 -0
  123. package/build/quaternions/index.d.ts +7 -0
  124. package/build/quaternions/index.d.ts.map +1 -0
  125. package/build/quaternions/index.js +7 -0
  126. package/build/quaternions/index.js.map +1 -0
  127. package/build/quaternions/interpolation.d.ts +54 -0
  128. package/build/quaternions/interpolation.d.ts.map +1 -0
  129. package/build/quaternions/interpolation.js +201 -0
  130. package/build/quaternions/interpolation.js.map +1 -0
  131. package/build/quaternions/interpolation.spec.d.ts +2 -0
  132. package/build/quaternions/interpolation.spec.d.ts.map +1 -0
  133. package/build/quaternions/interpolation.spec.js +64 -0
  134. package/build/quaternions/interpolation.spec.js.map +1 -0
  135. package/build/quaternions/predefined.d.ts +36 -0
  136. package/build/quaternions/predefined.d.ts.map +1 -0
  137. package/build/quaternions/predefined.js +42 -0
  138. package/build/quaternions/predefined.js.map +1 -0
  139. package/build/quaternions/predefined.spec.d.ts +2 -0
  140. package/build/quaternions/predefined.spec.d.ts.map +1 -0
  141. package/build/quaternions/predefined.spec.js +35 -0
  142. package/build/quaternions/predefined.spec.js.map +1 -0
  143. package/build/quaternions/types.d.ts +55 -0
  144. package/build/quaternions/types.d.ts.map +1 -0
  145. package/build/quaternions/types.js +7 -0
  146. package/build/quaternions/types.js.map +1 -0
  147. package/build/random.d.ts +66 -0
  148. package/build/random.d.ts.map +1 -0
  149. package/build/random.js +115 -0
  150. package/build/random.js.map +1 -0
  151. package/build/random.spec.d.ts +2 -0
  152. package/build/random.spec.d.ts.map +1 -0
  153. package/build/random.spec.js +267 -0
  154. package/build/random.spec.js.map +1 -0
  155. package/build/vectors/asserts.d.ts +182 -0
  156. package/build/vectors/asserts.d.ts.map +1 -0
  157. package/build/vectors/asserts.js +285 -0
  158. package/build/vectors/asserts.js.map +1 -0
  159. package/build/vectors/asserts.spec.d.ts +2 -0
  160. package/build/vectors/asserts.spec.d.ts.map +1 -0
  161. package/build/vectors/asserts.spec.js +260 -0
  162. package/build/vectors/asserts.spec.js.map +1 -0
  163. package/build/vectors/core.d.ts +507 -0
  164. package/build/vectors/core.d.ts.map +1 -0
  165. package/build/vectors/core.js +825 -0
  166. package/build/vectors/core.js.map +1 -0
  167. package/build/vectors/core.spec.d.ts +2 -0
  168. package/build/vectors/core.spec.d.ts.map +1 -0
  169. package/build/vectors/core.spec.js +343 -0
  170. package/build/vectors/core.spec.js.map +1 -0
  171. package/build/vectors/index.d.ts +6 -0
  172. package/build/vectors/index.d.ts.map +1 -0
  173. package/build/vectors/index.js +6 -0
  174. package/build/vectors/index.js.map +1 -0
  175. package/build/vectors/interpolation.d.ts +404 -0
  176. package/build/vectors/interpolation.d.ts.map +1 -0
  177. package/build/vectors/interpolation.js +585 -0
  178. package/build/vectors/interpolation.js.map +1 -0
  179. package/build/vectors/interpolation.spec.d.ts +2 -0
  180. package/build/vectors/interpolation.spec.d.ts.map +1 -0
  181. package/build/vectors/interpolation.spec.js +378 -0
  182. package/build/vectors/interpolation.spec.js.map +1 -0
  183. package/build/vectors/predefined.d.ts +191 -0
  184. package/build/vectors/predefined.d.ts.map +1 -0
  185. package/build/vectors/predefined.js +191 -0
  186. package/build/vectors/predefined.js.map +1 -0
  187. package/build/vectors/predefined.spec.d.ts +2 -0
  188. package/build/vectors/predefined.spec.d.ts.map +1 -0
  189. package/build/vectors/predefined.spec.js +333 -0
  190. package/build/vectors/predefined.spec.js.map +1 -0
  191. package/build/vectors/types.d.ts +62 -0
  192. package/build/vectors/types.d.ts.map +1 -0
  193. package/build/vectors/types.js +6 -0
  194. package/build/vectors/types.js.map +1 -0
  195. package/package.json +75 -0
@@ -0,0 +1,484 @@
1
+ /**
2
+ * @fileoverview Matrix transformation functions for 2D and 3D operations.
3
+ *
4
+ * This module provides comprehensive transformation matrix creation and application functions
5
+ * for computer graphics, game development, and mathematical applications. It includes:
6
+ *
7
+ * - Rotation matrices (2D and 3D with Euler angles)
8
+ * - Scale transformation matrices (uniform and non-uniform)
9
+ * - Translation matrices for positional transformations
10
+ * - Vector transformation utilities with homogeneous coordinate support
11
+ * - View and projection matrices for 3D rendering pipelines
12
+ *
13
+ * All matrices use homogeneous coordinates for consistent transformation composition.
14
+ * 2D transformations use 3x3 matrices, 3D transformations use 4x4 matrices.
15
+ *
16
+ * @author JTV Development Team
17
+ * @since 1.0.0
18
+ */
19
+ import { IMatrix3, IMatrix4 } from './types.js';
20
+ import { TVector2, TVector3 } from '../vectors/types.js';
21
+ /**
22
+ * Creates a 2D rotation matrix for rotating points around the origin.
23
+ *
24
+ * The matrix rotates points counterclockwise for positive angles in a standard
25
+ * right-handed coordinate system. Uses homogeneous coordinates for composition
26
+ * with other 2D transformations.
27
+ *
28
+ * Matrix structure:
29
+ * ```
30
+ * [cos(θ) -sin(θ) 0]
31
+ * [sin(θ) cos(θ) 0]
32
+ * [ 0 0 1]
33
+ * ```
34
+ *
35
+ * @param radians - Rotation angle in radians (positive = counterclockwise)
36
+ * @returns {IMatrix3} A 3x3 rotation matrix for 2D transformations
37
+ *
38
+ * @throws {Error} If radians is not a finite number
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * // 90-degree counterclockwise rotation
43
+ * const matrix = MatrixRotation2D(Math.PI / 2);
44
+ *
45
+ * // 45-degree clockwise rotation
46
+ * const clockwise = MatrixRotation2D(-Math.PI / 4);
47
+ * ```
48
+ */
49
+ export declare function MatrixRotation2D(radians: number): IMatrix3;
50
+ /**
51
+ * Creates a 3D roll rotation matrix (rotation around the X-axis).
52
+ *
53
+ * Roll represents banking motion in aviation terminology. Positive angles
54
+ * follow the right-hand rule: curl fingers from Y toward Z, thumb points
55
+ * in positive X direction.
56
+ *
57
+ * Matrix structure:
58
+ * ```
59
+ * [1 0 0 0]
60
+ * [0 cos(θ) -sin(θ) 0]
61
+ * [0 sin(θ) cos(θ) 0]
62
+ * [0 0 0 1]
63
+ * ```
64
+ *
65
+ * @param radians - Roll angle in radians (positive = right-hand rule around X-axis)
66
+ * @returns {IMatrix4} A 4x4 roll rotation matrix
67
+ *
68
+ * @throws {Error} If radians is not a finite number
69
+ *
70
+ * @example
71
+ * ```typescript
72
+ * // 45-degree roll (banking left in aviation)
73
+ * const rollMatrix = MatrixRotation3DRoll(Math.PI / 4);
74
+ * ```
75
+ */
76
+ export declare function MatrixRotation3DRoll(radians: number): IMatrix4;
77
+ /**
78
+ * Creates a 3D pitch rotation matrix (rotation around the Y-axis).
79
+ *
80
+ * Pitch represents elevation motion in aviation terminology. Positive angles
81
+ * follow the right-hand rule: curl fingers from Z toward X, thumb points
82
+ * in positive Y direction.
83
+ *
84
+ * Matrix structure:
85
+ * ```
86
+ * [ cos(θ) 0 sin(θ) 0]
87
+ * [ 0 1 0 0]
88
+ * [-sin(θ) 0 cos(θ) 0]
89
+ * [ 0 0 0 1]
90
+ * ```
91
+ *
92
+ * @param radians - Pitch angle in radians (positive = nose up in aviation)
93
+ * @returns {IMatrix4} A 4x4 pitch rotation matrix
94
+ *
95
+ * @throws {Error} If radians is not a finite number
96
+ *
97
+ * @example
98
+ * ```typescript
99
+ * // 30-degree pitch up
100
+ * const pitchMatrix = MatrixRotation3DPitch(Math.PI / 6);
101
+ * ```
102
+ */
103
+ export declare function MatrixRotation3DPitch(radians: number): IMatrix4;
104
+ /**
105
+ * Creates a 3D yaw rotation matrix (rotation around the Z-axis).
106
+ *
107
+ * Yaw represents heading motion in aviation terminology. Positive angles
108
+ * follow the right-hand rule: curl fingers from X toward Y, thumb points
109
+ * in positive Z direction.
110
+ *
111
+ * Matrix structure:
112
+ * ```
113
+ * [cos(θ) -sin(θ) 0 0]
114
+ * [sin(θ) cos(θ) 0 0]
115
+ * [ 0 0 1 0]
116
+ * [ 0 0 0 1]
117
+ * ```
118
+ *
119
+ * @param radians - Yaw angle in radians (positive = turn left in aviation)
120
+ * @returns {IMatrix4} A 4x4 yaw rotation matrix
121
+ *
122
+ * @throws {Error} If radians is not a finite number
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * // 60-degree yaw left
127
+ * const yawMatrix = MatrixRotation3DYaw(Math.PI / 3);
128
+ * ```
129
+ */
130
+ export declare function MatrixRotation3DYaw(radians: number): IMatrix4;
131
+ /**
132
+ * Creates a composite 3D rotation matrix from yaw, pitch, and roll components.
133
+ *
134
+ * Uses intrinsic rotation sequence: Roll (X) → Pitch (Y) → Yaw (Z), which is
135
+ * the standard aviation rotation order. The rotations are applied in sequence,
136
+ * with each rotation being relative to the rotated coordinate system.
137
+ *
138
+ * This function supports two call patterns:
139
+ * 1. Individual angles: MatrixRotation3D(roll, pitch, yaw)
140
+ * 2. Vector input: MatrixRotation3D([roll, pitch, yaw])
141
+ *
142
+ * @param roll - Roll angle in radians (X-axis rotation) or vector [roll, pitch, yaw]
143
+ * @param pitch - Pitch angle in radians (Y-axis rotation, required if roll is number)
144
+ * @param yaw - Yaw angle in radians (Z-axis rotation, required if roll is number)
145
+ * @returns {IMatrix4} A 4x4 composite rotation matrix
146
+ *
147
+ * @throws {Error} If any angle is not a finite number
148
+ *
149
+ * @example
150
+ * ```typescript
151
+ * // Using individual angles (banking, elevation, heading)
152
+ * const rotationMatrix = MatrixRotation3D(0.1, 0.2, 0.3);
153
+ *
154
+ * // Using vector input
155
+ * const eulerAngles: TVector3 = [0.1, 0.2, 0.3];
156
+ * const rotationMatrix2 = MatrixRotation3D(eulerAngles);
157
+ * ```
158
+ */
159
+ export declare function MatrixRotation3D(roll: number, pitch: number, yaw: number): IMatrix4;
160
+ export declare function MatrixRotation3D(v: TVector3): IMatrix4;
161
+ /**
162
+ * Creates a composite 3D rotation matrix from Euler angles specified in degrees.
163
+ *
164
+ * This is a convenience function that converts degree measurements to radians
165
+ * before calling MatrixRotation3D. Useful when working with user input or
166
+ * data sources that use degrees instead of radians.
167
+ *
168
+ * Uses the same intrinsic rotation sequence: Roll (X) → Pitch (Y) → Yaw (Z).
169
+ *
170
+ * @param roll - Roll angle in degrees (X-axis rotation) or vector [roll, pitch, yaw]
171
+ * @param pitch - Pitch angle in degrees (Y-axis rotation, required if roll is number)
172
+ * @param yaw - Yaw angle in degrees (Z-axis rotation, required if roll is number)
173
+ * @returns {IMatrix4} A 4x4 composite rotation matrix
174
+ *
175
+ * @throws {Error} If any angle is not a finite number
176
+ *
177
+ * @example
178
+ * ```typescript
179
+ * // Using individual angles in degrees
180
+ * const rotation = MatrixRotation3DEulerAngles(45, 30, 60);
181
+ *
182
+ * // Using vector input in degrees
183
+ * const angles: TVector3 = [45, 30, 60];
184
+ * const rotation2 = MatrixRotation3DEulerAngles(angles);
185
+ * ```
186
+ */
187
+ export declare function MatrixRotation3DEulerAngles(roll: number, pitch: number, yaw: number): IMatrix4;
188
+ export declare function MatrixRotation3DEulerAngles(v: TVector3): IMatrix4;
189
+ /**
190
+ * Creates a 2D scale transformation matrix with flexible input options.
191
+ *
192
+ * Scale factors greater than 1 enlarge objects, factors between 0 and 1 shrink
193
+ * objects, and negative values flip objects across the corresponding axis.
194
+ * Uses homogeneous coordinates for composition with other 2D transformations.
195
+ *
196
+ * Matrix structure:
197
+ * ```
198
+ * [sx 0 0]
199
+ * [ 0 sy 0]
200
+ * [ 0 0 1]
201
+ * ```
202
+ *
203
+ * Supports three call patterns:
204
+ * 1. Uniform scaling: MatrixScale2D(scale)
205
+ * 2. Independent scaling: MatrixScale2D(x, y)
206
+ * 3. Vector scaling: MatrixScale2D([x, y])
207
+ *
208
+ * @param scale - Uniform scale factor for both axes, OR X-axis scale factor
209
+ * @param y - Y-axis scale factor (only for independent scaling)
210
+ * @returns {IMatrix3} A 3x3 scale transformation matrix
211
+ *
212
+ * @throws {Error} If any scale factor is not a finite number
213
+ *
214
+ * @example
215
+ * ```typescript
216
+ * // Uniform scaling (double size)
217
+ * const uniform = MatrixScale2D(2.0);
218
+ *
219
+ * // Independent scaling (stretch horizontally, compress vertically)
220
+ * const stretch = MatrixScale2D(2.0, 0.5);
221
+ *
222
+ * // Vector input
223
+ * const scaleVector: TVector2 = [1.5, 0.8];
224
+ * const vectorScale = MatrixScale2D(scaleVector);
225
+ *
226
+ * // Flip horizontally
227
+ * const flip = MatrixScale2D(-1, 1);
228
+ * ```
229
+ */
230
+ export declare function MatrixScale2D(scale: number): IMatrix3;
231
+ export declare function MatrixScale2D(x: number, y: number): IMatrix3;
232
+ export declare function MatrixScale2D(v: TVector2): IMatrix3;
233
+ /**
234
+ * Creates a 3D scale transformation matrix with flexible input options.
235
+ *
236
+ * Scale factors greater than 1 enlarge objects, factors between 0 and 1 shrink
237
+ * objects, and negative values flip objects across the corresponding axis.
238
+ * Uses homogeneous coordinates for composition with other 3D transformations.
239
+ *
240
+ * Matrix structure:
241
+ * ```
242
+ * [sx 0 0 0]
243
+ * [ 0 sy 0 0]
244
+ * [ 0 0 sz 0]
245
+ * [ 0 0 0 1]
246
+ * ```
247
+ *
248
+ * Supports three call patterns:
249
+ * 1. Uniform scaling: MatrixScale3D(scale)
250
+ * 2. Independent scaling: MatrixScale3D(x, y, z)
251
+ * 3. Vector scaling: MatrixScale3D([x, y, z])
252
+ *
253
+ * @param scale - Uniform scale factor for all axes, OR X-axis scale factor
254
+ * @param y - Y-axis scale factor (only for independent scaling)
255
+ * @param z - Z-axis scale factor (only for independent scaling)
256
+ * @returns {IMatrix4} A 4x4 scale transformation matrix
257
+ *
258
+ * @throws {Error} If any scale factor is not a finite number
259
+ *
260
+ * @example
261
+ * ```typescript
262
+ * // Uniform scaling (triple size)
263
+ * const uniform = MatrixScale3D(3.0);
264
+ *
265
+ * // Independent scaling (stretch, compress, normal)
266
+ * const stretch = MatrixScale3D(2.0, 0.5, 1.0);
267
+ *
268
+ * // Vector input
269
+ * const scaleVector: TVector3 = [1.5, 0.8, 2.0];
270
+ * const vectorScale = MatrixScale3D(scaleVector);
271
+ *
272
+ * // Mirror across XY plane
273
+ * const mirror = MatrixScale3D(1, 1, -1);
274
+ * ```
275
+ */
276
+ export declare function MatrixScale3D(scale: number): IMatrix4;
277
+ export declare function MatrixScale3D(x: number, y: number, z: number): IMatrix4;
278
+ export declare function MatrixScale3D(v: TVector3): IMatrix4;
279
+ /**
280
+ * Creates a 2D translation transformation matrix.
281
+ *
282
+ * Moves 2D points by the specified offset distances. Uses homogeneous
283
+ * coordinates to enable composition with other 2D transformations.
284
+ *
285
+ * Matrix structure:
286
+ * ```
287
+ * [1 0 tx]
288
+ * [0 1 ty]
289
+ * [0 0 1]
290
+ * ```
291
+ *
292
+ * @param v - Translation vector [x, y] containing offset distances
293
+ * @returns {IMatrix3} A 3x3 translation transformation matrix
294
+ *
295
+ * @throws {Error} If the input is not a valid 2D vector
296
+ *
297
+ * @example
298
+ * ```typescript
299
+ * // Move 10 units right, 5 units up
300
+ * const translation = MatrixTranslation2D(10, 5);
301
+ *
302
+ * // Using vector input
303
+ * const offset: TVector2 = [10, 5];
304
+ * const translation2 = MatrixTranslation2D(...offset);
305
+ * ```
306
+ */
307
+ export declare function MatrixTranslation2D(...v: TVector2): IMatrix3;
308
+ /**
309
+ * Creates a 3D translation transformation matrix with flexible input options.
310
+ *
311
+ * Moves 3D points by the specified offset distances along each axis.
312
+ * Uses homogeneous coordinates to enable composition with other 3D transformations.
313
+ *
314
+ * Matrix structure:
315
+ * ```
316
+ * [1 0 0 tx]
317
+ * [0 1 0 ty]
318
+ * [0 0 1 tz]
319
+ * [0 0 0 1]
320
+ * ```
321
+ *
322
+ * Supports three call patterns:
323
+ * 1. Uniform translation: MatrixTranslation3D(distance)
324
+ * 2. Independent translation: MatrixTranslation3D(x, y, z)
325
+ * 3. Vector translation: MatrixTranslation3D([x, y, z])
326
+ *
327
+ * @param translationOrX - Uniform translation distance for all axes, OR X-axis distance
328
+ * @param y - Y-axis translation distance (only for independent translation)
329
+ * @param z - Z-axis translation distance (only for independent translation)
330
+ * @returns {IMatrix4} A 4x4 translation transformation matrix
331
+ *
332
+ * @throws {Error} If any translation distance is not a finite number
333
+ *
334
+ * @example
335
+ * ```typescript
336
+ * // Uniform translation (move 5 units in all directions)
337
+ * const uniform = MatrixTranslation3D(5.0);
338
+ *
339
+ * // Independent translation
340
+ * const independent = MatrixTranslation3D(10, -5, 3);
341
+ *
342
+ * // Vector input
343
+ * const offset: TVector3 = [10, -5, 3];
344
+ * const vectorTranslation = MatrixTranslation3D(...offset);
345
+ * ```
346
+ */
347
+ export declare function MatrixTranslation3D(translation: number): IMatrix4;
348
+ export declare function MatrixTranslation3D(x: number, y: number, z: number): IMatrix4;
349
+ export declare function MatrixTranslation3D(v: TVector3): IMatrix4;
350
+ /**
351
+ * Transforms a 2D vector using a 3x3 transformation matrix with homogeneous coordinates.
352
+ *
353
+ * This function applies a transformation matrix to a 2D vector by:
354
+ * 1. Converting the 2D vector to homogeneous coordinates (adding w=1)
355
+ * 2. Performing matrix-vector multiplication
356
+ * 3. Converting back to 2D by dividing by the homogeneous w component
357
+ *
358
+ * This approach enables composition of multiple transformations and supports
359
+ * affine transformations including translation, rotation, scaling, and shearing.
360
+ *
361
+ * @param vector - The 2D vector to transform [x, y]
362
+ * @param matrix - A 3x3 transformation matrix to apply
363
+ * @returns {TVector2} The transformed 2D vector
364
+ *
365
+ * @throws {Error} If the homogeneous w component is near zero (degenerate transformation)
366
+ * @throws {Error} If inputs are not valid vector/matrix types
367
+ *
368
+ * @example
369
+ * ```typescript
370
+ * // Rotate a point 90 degrees counterclockwise
371
+ * const rotationMatrix = MatrixRotation2D(Math.PI / 2);
372
+ * const point: TVector2 = [1, 0];
373
+ * const rotatedPoint = MatrixTransform2D(point, rotationMatrix);
374
+ * // Result: approximately [0, 1]
375
+ *
376
+ * // Chain multiple transformations
377
+ * const scale = MatrixScale2D(2, 2);
378
+ * const translate = MatrixTranslation2D(5, 3);
379
+ * const combined = MatrixMultiply(translate, scale);
380
+ * const transformedPoint = MatrixTransform2D(point, combined);
381
+ * ```
382
+ */
383
+ export declare function MatrixTransform2D(vector: TVector2, matrix: IMatrix3): TVector2;
384
+ /**
385
+ * Transforms a 3D vector using a 4x4 transformation matrix with homogeneous coordinates.
386
+ * Converts to homogeneous coordinates, applies transformation, then converts back to 3D.
387
+ *
388
+ * @param transform - A 4x4 transformation matrix.
389
+ * @param vector - The 3D vector to transform.
390
+ * @returns {TVector3} The transformed 3D vector.
391
+ *
392
+ * @throws {Error} If the w component is near zero (degenerate transformation).
393
+ *
394
+ * @example
395
+ * ```typescript
396
+ * const rotationMatrix = Matrix_Transformation_Rotation3D_Yaw(Math.PI / 4);
397
+ * const point = [1, 0, 0];
398
+ * const rotatedPoint = Matrix_Transformation3D(rotationMatrix, point);
399
+ * ```
400
+ */
401
+ export declare function MatrixTransform3D(vector: TVector3, transform: IMatrix4): TVector3;
402
+ /**
403
+ * Transforms a 3D direction vector using a 3x3 matrix, ignoring translation components.
404
+ * Designed for direction vectors (normals, velocities) where translation should not apply.
405
+ *
406
+ * @param matrix - A 3x3 transformation matrix (rotation and/or scale only).
407
+ * @param direction - The 3D direction vector to transform.
408
+ * @returns {TVector3} The transformed direction vector.
409
+ *
410
+ * @example
411
+ * ```typescript
412
+ * const rotationMatrix = Matrix_Transformation_Rotation3D_Yaw(Math.PI / 4);
413
+ * const normal = [0, 0, 1];
414
+ * const rotatedNormal = Matrix_Transformation_Direction3D(rotationMatrix, normal);
415
+ * ```
416
+ */
417
+ export declare function MatrixDirection3D(direction: TVector3, matrix: IMatrix3): TVector3;
418
+ /**
419
+ * Creates a view matrix for positioning and orienting a 3D camera.
420
+ * Transforms world coordinates to camera coordinates using the "look-at" approach.
421
+ *
422
+ * @param eye - Camera position in world coordinates.
423
+ * @param target - Point the camera is looking at.
424
+ * @param up - Up direction vector (usually [0, 1, 0]).
425
+ * @returns {IMatrix4} A 4x4 view transformation matrix.
426
+ *
427
+ * @example
428
+ * ```typescript
429
+ * const viewMatrix = Matrix_Transformation_View(
430
+ * [10, 5, 10], // Camera position
431
+ * [0, 0, 0], // Looking at origin
432
+ * [0, 1, 0] // Y-axis is up
433
+ * );
434
+ * ```
435
+ */
436
+ export declare function MatrixView(eye: TVector3, target: TVector3, up: TVector3): IMatrix4;
437
+ /**
438
+ * Creates a perspective projection matrix for 3D rendering.
439
+ * Transforms 3D view coordinates to normalized device coordinates with perspective effect.
440
+ *
441
+ * @param fovY - Vertical field of view angle in radians.
442
+ * @param aspect - Aspect ratio of the viewport (width/height).
443
+ * @param near - Distance to near clipping plane (must be positive).
444
+ * @param far - Distance to far clipping plane (must be > near).
445
+ * @returns {IMatrix4} A 4x4 perspective projection matrix.
446
+ *
447
+ * @throws {Error} If parameters are invalid.
448
+ *
449
+ * @example
450
+ * ```typescript
451
+ * const perspectiveMatrix = Matrix_Transformation_Perspective(
452
+ * Math.PI / 4, // 45-degree field of view
453
+ * 16 / 9, // Widescreen aspect ratio
454
+ * 0.1, // Near plane
455
+ * 1000 // Far plane
456
+ * );
457
+ * ```
458
+ */
459
+ export declare function MatrixPerspective(fovY: number, aspect: number, near: number, far: number): IMatrix4;
460
+ /**
461
+ * Creates an orthographic projection matrix for 3D rendering.
462
+ * Maps a rectangular box to the unit cube [-1, 1]³ without perspective distortion.
463
+ *
464
+ * @param left - Left boundary of the orthographic volume.
465
+ * @param right - Right boundary of the orthographic volume.
466
+ * @param bottom - Bottom boundary of the orthographic volume.
467
+ * @param top - Top boundary of the orthographic volume.
468
+ * @param near - Near clipping plane distance.
469
+ * @param far - Far clipping plane distance.
470
+ * @returns {IMatrix4} A 4x4 orthographic projection matrix.
471
+ *
472
+ * @throws {Error} If any opposing boundaries are equal.
473
+ *
474
+ * @example
475
+ * ```typescript
476
+ * const orthoMatrix = Matrix_Transformation_Orthographic(
477
+ * -10, 10, // Left/Right: 20 units wide
478
+ * -7.5, 7.5, // Bottom/Top: 15 units tall
479
+ * -100, 100 // Near/Far: 200 units deep
480
+ * );
481
+ * ```
482
+ */
483
+ export declare function MatrixOrthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): IMatrix4;
484
+ //# sourceMappingURL=transformations.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"transformations.d.ts","sourceRoot":"","sources":["../../src/matrices/transformations.ts"],"names":[],"mappings":"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"}