@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.
- package/LICENSE +21 -0
- package/README.md +319 -0
- package/build/angles.d.ts +31 -0
- package/build/angles.d.ts.map +1 -0
- package/build/angles.js +85 -0
- package/build/angles.js.map +1 -0
- package/build/angles.spec.d.ts +2 -0
- package/build/angles.spec.d.ts.map +1 -0
- package/build/angles.spec.js +147 -0
- package/build/angles.spec.js.map +1 -0
- package/build/clamp.d.ts +17 -0
- package/build/clamp.d.ts.map +1 -0
- package/build/clamp.js +19 -0
- package/build/clamp.js.map +1 -0
- package/build/clamp.spec.d.ts +2 -0
- package/build/clamp.spec.d.ts.map +1 -0
- package/build/clamp.spec.js +19 -0
- package/build/clamp.spec.js.map +1 -0
- package/build/documentation-validation.spec.d.ts +11 -0
- package/build/documentation-validation.spec.d.ts.map +1 -0
- package/build/documentation-validation.spec.js +401 -0
- package/build/documentation-validation.spec.js.map +1 -0
- package/build/index.d.ts +8 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +8 -0
- package/build/index.js.map +1 -0
- package/build/interpolation.d.ts +175 -0
- package/build/interpolation.d.ts.map +1 -0
- package/build/interpolation.js +369 -0
- package/build/interpolation.js.map +1 -0
- package/build/interpolation.spec.d.ts +2 -0
- package/build/interpolation.spec.d.ts.map +1 -0
- package/build/interpolation.spec.js +480 -0
- package/build/interpolation.spec.js.map +1 -0
- package/build/matrices/arithmetic.d.ts +411 -0
- package/build/matrices/arithmetic.d.ts.map +1 -0
- package/build/matrices/arithmetic.js +954 -0
- package/build/matrices/arithmetic.js.map +1 -0
- package/build/matrices/arithmetic.spec.d.ts +2 -0
- package/build/matrices/arithmetic.spec.d.ts.map +1 -0
- package/build/matrices/arithmetic.spec.js +915 -0
- package/build/matrices/arithmetic.spec.js.map +1 -0
- package/build/matrices/asserts.d.ts +306 -0
- package/build/matrices/asserts.d.ts.map +1 -0
- package/build/matrices/asserts.js +396 -0
- package/build/matrices/asserts.js.map +1 -0
- package/build/matrices/asserts.spec.d.ts +2 -0
- package/build/matrices/asserts.spec.d.ts.map +1 -0
- package/build/matrices/asserts.spec.js +565 -0
- package/build/matrices/asserts.spec.js.map +1 -0
- package/build/matrices/core.d.ts +168 -0
- package/build/matrices/core.d.ts.map +1 -0
- package/build/matrices/core.js +457 -0
- package/build/matrices/core.js.map +1 -0
- package/build/matrices/core.spec.d.ts +2 -0
- package/build/matrices/core.spec.d.ts.map +1 -0
- package/build/matrices/core.spec.js +634 -0
- package/build/matrices/core.spec.js.map +1 -0
- package/build/matrices/decompositions.d.ts +326 -0
- package/build/matrices/decompositions.d.ts.map +1 -0
- package/build/matrices/decompositions.js +816 -0
- package/build/matrices/decompositions.js.map +1 -0
- package/build/matrices/decompositions.spec.d.ts +2 -0
- package/build/matrices/decompositions.spec.d.ts.map +1 -0
- package/build/matrices/decompositions.spec.js +195 -0
- package/build/matrices/decompositions.spec.js.map +1 -0
- package/build/matrices/index.d.ts +9 -0
- package/build/matrices/index.d.ts.map +1 -0
- package/build/matrices/index.js +9 -0
- package/build/matrices/index.js.map +1 -0
- package/build/matrices/linear-algebra.d.ts +64 -0
- package/build/matrices/linear-algebra.d.ts.map +1 -0
- package/build/matrices/linear-algebra.js +253 -0
- package/build/matrices/linear-algebra.js.map +1 -0
- package/build/matrices/linear-algebra.spec.d.ts +2 -0
- package/build/matrices/linear-algebra.spec.d.ts.map +1 -0
- package/build/matrices/linear-algebra.spec.js +355 -0
- package/build/matrices/linear-algebra.spec.js.map +1 -0
- package/build/matrices/normalization.d.ts +62 -0
- package/build/matrices/normalization.d.ts.map +1 -0
- package/build/matrices/normalization.js +167 -0
- package/build/matrices/normalization.js.map +1 -0
- package/build/matrices/normalization.spec.d.ts +2 -0
- package/build/matrices/normalization.spec.d.ts.map +1 -0
- package/build/matrices/normalization.spec.js +335 -0
- package/build/matrices/normalization.spec.js.map +1 -0
- package/build/matrices/transformations.d.ts +484 -0
- package/build/matrices/transformations.d.ts.map +1 -0
- package/build/matrices/transformations.js +592 -0
- package/build/matrices/transformations.js.map +1 -0
- package/build/matrices/transformations.spec.d.ts +2 -0
- package/build/matrices/transformations.spec.d.ts.map +1 -0
- package/build/matrices/transformations.spec.js +755 -0
- package/build/matrices/transformations.spec.js.map +1 -0
- package/build/matrices/types.d.ts +134 -0
- package/build/matrices/types.d.ts.map +1 -0
- package/build/matrices/types.js +6 -0
- package/build/matrices/types.js.map +1 -0
- package/build/quaternions/asserts.d.ts +77 -0
- package/build/quaternions/asserts.d.ts.map +1 -0
- package/build/quaternions/asserts.js +175 -0
- package/build/quaternions/asserts.js.map +1 -0
- package/build/quaternions/asserts.spec.d.ts +2 -0
- package/build/quaternions/asserts.spec.d.ts.map +1 -0
- package/build/quaternions/asserts.spec.js +320 -0
- package/build/quaternions/asserts.spec.js.map +1 -0
- package/build/quaternions/conversions.d.ts +73 -0
- package/build/quaternions/conversions.d.ts.map +1 -0
- package/build/quaternions/conversions.js +179 -0
- package/build/quaternions/conversions.js.map +1 -0
- package/build/quaternions/conversions.spec.d.ts +2 -0
- package/build/quaternions/conversions.spec.d.ts.map +1 -0
- package/build/quaternions/conversions.spec.js +344 -0
- package/build/quaternions/conversions.spec.js.map +1 -0
- package/build/quaternions/core.d.ts +203 -0
- package/build/quaternions/core.d.ts.map +1 -0
- package/build/quaternions/core.js +374 -0
- package/build/quaternions/core.js.map +1 -0
- package/build/quaternions/core.spec.d.ts +2 -0
- package/build/quaternions/core.spec.d.ts.map +1 -0
- package/build/quaternions/core.spec.js +294 -0
- package/build/quaternions/core.spec.js.map +1 -0
- package/build/quaternions/index.d.ts +7 -0
- package/build/quaternions/index.d.ts.map +1 -0
- package/build/quaternions/index.js +7 -0
- package/build/quaternions/index.js.map +1 -0
- package/build/quaternions/interpolation.d.ts +54 -0
- package/build/quaternions/interpolation.d.ts.map +1 -0
- package/build/quaternions/interpolation.js +201 -0
- package/build/quaternions/interpolation.js.map +1 -0
- package/build/quaternions/interpolation.spec.d.ts +2 -0
- package/build/quaternions/interpolation.spec.d.ts.map +1 -0
- package/build/quaternions/interpolation.spec.js +64 -0
- package/build/quaternions/interpolation.spec.js.map +1 -0
- package/build/quaternions/predefined.d.ts +36 -0
- package/build/quaternions/predefined.d.ts.map +1 -0
- package/build/quaternions/predefined.js +42 -0
- package/build/quaternions/predefined.js.map +1 -0
- package/build/quaternions/predefined.spec.d.ts +2 -0
- package/build/quaternions/predefined.spec.d.ts.map +1 -0
- package/build/quaternions/predefined.spec.js +35 -0
- package/build/quaternions/predefined.spec.js.map +1 -0
- package/build/quaternions/types.d.ts +55 -0
- package/build/quaternions/types.d.ts.map +1 -0
- package/build/quaternions/types.js +7 -0
- package/build/quaternions/types.js.map +1 -0
- package/build/random.d.ts +66 -0
- package/build/random.d.ts.map +1 -0
- package/build/random.js +115 -0
- package/build/random.js.map +1 -0
- package/build/random.spec.d.ts +2 -0
- package/build/random.spec.d.ts.map +1 -0
- package/build/random.spec.js +267 -0
- package/build/random.spec.js.map +1 -0
- package/build/vectors/asserts.d.ts +182 -0
- package/build/vectors/asserts.d.ts.map +1 -0
- package/build/vectors/asserts.js +285 -0
- package/build/vectors/asserts.js.map +1 -0
- package/build/vectors/asserts.spec.d.ts +2 -0
- package/build/vectors/asserts.spec.d.ts.map +1 -0
- package/build/vectors/asserts.spec.js +260 -0
- package/build/vectors/asserts.spec.js.map +1 -0
- package/build/vectors/core.d.ts +507 -0
- package/build/vectors/core.d.ts.map +1 -0
- package/build/vectors/core.js +825 -0
- package/build/vectors/core.js.map +1 -0
- package/build/vectors/core.spec.d.ts +2 -0
- package/build/vectors/core.spec.d.ts.map +1 -0
- package/build/vectors/core.spec.js +343 -0
- package/build/vectors/core.spec.js.map +1 -0
- package/build/vectors/index.d.ts +6 -0
- package/build/vectors/index.d.ts.map +1 -0
- package/build/vectors/index.js +6 -0
- package/build/vectors/index.js.map +1 -0
- package/build/vectors/interpolation.d.ts +404 -0
- package/build/vectors/interpolation.d.ts.map +1 -0
- package/build/vectors/interpolation.js +585 -0
- package/build/vectors/interpolation.js.map +1 -0
- package/build/vectors/interpolation.spec.d.ts +2 -0
- package/build/vectors/interpolation.spec.d.ts.map +1 -0
- package/build/vectors/interpolation.spec.js +378 -0
- package/build/vectors/interpolation.spec.js.map +1 -0
- package/build/vectors/predefined.d.ts +191 -0
- package/build/vectors/predefined.d.ts.map +1 -0
- package/build/vectors/predefined.js +191 -0
- package/build/vectors/predefined.js.map +1 -0
- package/build/vectors/predefined.spec.d.ts +2 -0
- package/build/vectors/predefined.spec.d.ts.map +1 -0
- package/build/vectors/predefined.spec.js +333 -0
- package/build/vectors/predefined.spec.js.map +1 -0
- package/build/vectors/types.d.ts +62 -0
- package/build/vectors/types.d.ts.map +1 -0
- package/build/vectors/types.js +6 -0
- package/build/vectors/types.js.map +1 -0
- 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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"}
|