0
# Math
1

2
Mathematical foundation providing vectors, matrices, quaternions, geometric primitives, and utility functions for 3D graphics calculations. All math classes are optimized for performance and provide comprehensive operations.
3

4
## Capabilities
5

6
### Vector Mathematics
7

8
Core vector classes for position, direction, and mathematical operations in 2D, 3D, and 4D space.
9

10
```typescript { .api }
11
import { Vector2, Vector3, Vector4, Matrix3, Matrix4, BufferAttribute } from 'three';
12

13
/**
14
 * 2D vector with x, y components
15
 */
16
class Vector2 {
17
  /** Type flag for vector2 detection */
18
  readonly isVector2: true;
19
  
20
  /** X component */
21
  x: number;
22
  
23
  /** Y component */
24
  y: number;
25
  
26
  /** Vector width (alias for x) */
27
  width: number;
28
  
29
  /** Vector height (alias for y) */
30
  height: number;
31
  
32
  /**
33
   * Create 2D vector
34
   * @param x - X component (default: 0)
35
   * @param y - Y component (default: 0)
36
   */
37
  constructor(x?: number, y?: number);
38
  
39
  /**
40
   * Set vector components
41
   * @param x - X component
42
   * @param y - Y component
43
   * @returns This vector for chaining
44
   */
45
  set(x: number, y: number): this;
46
  
47
  /**
48
   * Set scalar value to both components
49
   * @param scalar - Value for both components
50
   * @returns This vector for chaining
51
   */
52
  setScalar(scalar: number): this;
53
  
54
  /**
55
   * Set X component
56
   * @param x - X value
57
   * @returns This vector for chaining
58
   */
59
  setX(x: number): this;
60
  
61
  /**
62
   * Set Y component
63
   * @param y - Y value
64
   * @returns This vector for chaining
65
   */
66
  setY(y: number): this;
67
  
68
  /**
69
   * Set component by index (0=x, 1=y)
70
   * @param index - Component index
71
   * @param value - Component value
72
   * @returns This vector for chaining
73
   */
74
  setComponent(index: number, value: number): this;
75
  
76
  /**
77
   * Get component by index
78
   * @param index - Component index (0=x, 1=y)
79
   * @returns Component value
80
   */
81
  getComponent(index: number): number;
82
  
83
  /**
84
   * Clone vector
85
   * @returns New vector with same values
86
   */
87
  clone(): Vector2;
88
  
89
  /**
90
   * Copy from another vector
91
   * @param v - Source vector
92
   * @returns This vector for chaining
93
   */
94
  copy(v: Vector2): this;
95
  
96
  /**
97
   * Add another vector
98
   * @param v - Vector to add
99
   * @returns This vector for chaining
100
   */
101
  add(v: Vector2): this;
102
  
103
  /**
104
   * Add scalar to both components
105
   * @param s - Scalar value
106
   * @returns This vector for chaining
107
   */
108
  addScalar(s: number): this;
109
  
110
  /**
111
   * Add scaled vector
112
   * @param v - Vector to add
113
   * @param s - Scale factor
114
   * @returns This vector for chaining
115
   */
116
  addScaledVector(v: Vector2, s: number): this;
117
  
118
  /**
119
   * Add two vectors and store result
120
   * @param a - First vector
121
   * @param b - Second vector
122
   * @returns This vector for chaining
123
   */
124
  addVectors(a: Vector2, b: Vector2): this;
125
  
126
  /**
127
   * Subtract another vector
128
   * @param v - Vector to subtract
129
   * @returns This vector for chaining
130
   */
131
  sub(v: Vector2): this;
132
  
133
  /**
134
   * Subtract scalar from both components
135
   * @param s - Scalar value
136
   * @returns This vector for chaining
137
   */
138
  subScalar(s: number): this;
139
  
140
  /**
141
   * Subtract two vectors and store result
142
   * @param a - First vector
143
   * @param b - Second vector
144
   * @returns This vector for chaining
145
   */
146
  subVectors(a: Vector2, b: Vector2): this;
147
  
148
  /**
149
   * Multiply by another vector (component-wise)
150
   * @param v - Vector to multiply
151
   * @returns This vector for chaining
152
   */
153
  multiply(v: Vector2): this;
154
  
155
  /**
156
   * Multiply by scalar
157
   * @param scalar - Scale factor
158
   * @returns This vector for chaining
159
   */
160
  multiplyScalar(scalar: number): this;
161
  
162
  /**
163
   * Divide by another vector (component-wise)
164
   * @param v - Vector to divide by
165
   * @returns This vector for chaining
166
   */
167
  divide(v: Vector2): this;
168
  
169
  /**
170
   * Divide by scalar
171
   * @param scalar - Divisor
172
   * @returns This vector for chaining
173
   */
174
  divideScalar(scalar: number): this;
175
  
176
  /**
177
   * Apply matrix transformation
178
   * @param m - 3x3 transformation matrix
179
   * @returns This vector for chaining
180
   */
181
  applyMatrix3(m: Matrix3): this;
182
  
183
  /**
184
   * Get minimum components with another vector
185
   * @param v - Vector to compare
186
   * @returns This vector for chaining
187
   */
188
  min(v: Vector2): this;
189
  
190
  /**
191
   * Get maximum components with another vector
192
   * @param v - Vector to compare
193
   * @returns This vector for chaining
194
   */
195
  max(v: Vector2): this;
196
  
197
  /**
198
   * Clamp components between min and max vectors
199
   * @param min - Minimum vector
200
   * @param max - Maximum vector
201
   * @returns This vector for chaining
202
   */
203
  clamp(min: Vector2, max: Vector2): this;
204
  
205
  /**
206
   * Clamp components between scalar values
207
   * @param minVal - Minimum value
208
   * @param maxVal - Maximum value
209
   * @returns This vector for chaining
210
   */
211
  clampScalar(minVal: number, maxVal: number): this;
212
  
213
  /**
214
   * Clamp vector length
215
   * @param min - Minimum length
216
   * @param max - Maximum length
217
   * @returns This vector for chaining
218
   */
219
  clampLength(min: number, max: number): this;
220
  
221
  /**
222
   * Floor all components
223
   * @returns This vector for chaining
224
   */
225
  floor(): this;
226
  
227
  /**
228
   * Ceil all components
229
   * @returns This vector for chaining
230
   */
231
  ceil(): this;
232
  
233
  /**
234
   * Round all components
235
   * @returns This vector for chaining
236
   */
237
  round(): this;
238
  
239
  /**
240
   * Round components towards zero
241
   * @returns This vector for chaining
242
   */
243
  roundToZero(): this;
244
  
245
  /**
246
   * Negate all components
247
   * @returns This vector for chaining
248
   */
249
  negate(): this;
250
  
251
  /**
252
   * Calculate dot product
253
   * @param v - Vector to dot with
254
   * @returns Dot product value
255
   */
256
  dot(v: Vector2): number;
257
  
258
  /**
259
   * Calculate cross product (returns scalar in 2D)
260
   * @param v - Vector to cross with
261
   * @returns Cross product value
262
   */
263
  cross(v: Vector2): number;
264
  
265
  /**
266
   * Get squared length (faster than length)
267
   * @returns Squared length
268
   */
269
  lengthSq(): number;
270
  
271
  /**
272
   * Get vector length
273
   * @returns Vector magnitude
274
   */
275
  length(): number;
276
  
277
  /**
278
   * Get Manhattan length (sum of absolute components)
279
   * @returns Manhattan length
280
   */
281
  manhattanLength(): number;
282
  
283
  /**
284
   * Normalize vector to unit length
285
   * @returns This vector for chaining
286
   */
287
  normalize(): this;
288
  
289
  /**
290
   * Get angle in radians
291
   * @returns Angle from positive X axis
292
   */
293
  angle(): number;
294
  
295
  /**
296
   * Calculate angle to another vector
297
   * @param v - Target vector
298
   * @returns Angle in radians
299
   */
300
  angleTo(v: Vector2): number;
301
  
302
  /**
303
   * Calculate distance to another vector
304
   * @param v - Target vector
305
   * @returns Distance
306
   */
307
  distanceTo(v: Vector2): number;
308
  
309
  /**
310
   * Calculate squared distance (faster than distance)
311
   * @param v - Target vector
312
   * @returns Squared distance
313
   */
314
  distanceToSquared(v: Vector2): number;
315
  
316
  /**
317
   * Calculate Manhattan distance
318
   * @param v - Target vector
319
   * @returns Manhattan distance
320
   */
321
  manhattanDistanceTo(v: Vector2): number;
322
  
323
  /**
324
   * Set vector to given length
325
   * @param length - Target length
326
   * @returns This vector for chaining
327
   */
328
  setLength(length: number): this;
329
  
330
  /**
331
   * Linear interpolation to another vector
332
   * @param v - Target vector
333
   * @param alpha - Interpolation factor (0-1)
334
   * @returns This vector for chaining
335
   */
336
  lerp(v: Vector2, alpha: number): this;
337
  
338
  /**
339
   * Linear interpolation between two vectors
340
   * @param v1 - First vector
341
   * @param v2 - Second vector
342
   * @param alpha - Interpolation factor (0-1)
343
   * @returns This vector for chaining
344
   */
345
  lerpVectors(v1: Vector2, v2: Vector2, alpha: number): this;
346
  
347
  /**
348
   * Check equality with another vector
349
   * @param v - Vector to compare
350
   * @returns True if equal
351
   */
352
  equals(v: Vector2): boolean;
353
  
354
  /**
355
   * Set from array
356
   * @param array - Source array
357
   * @param offset - Array offset
358
   * @returns This vector for chaining
359
   */
360
  fromArray(array: number[], offset?: number): this;
361
  
362
  /**
363
   * Copy to array
364
   * @param array - Target array
365
   * @param offset - Array offset
366
   * @returns Target array
367
   */
368
  toArray(array?: number[], offset?: number): number[];
369
  
370
  /**
371
   * Set from buffer attribute
372
   * @param attribute - Buffer attribute
373
   * @param index - Vertex index
374
   * @returns This vector for chaining
375
   */
376
  fromBufferAttribute(attribute: BufferAttribute, index: number): this;
377
  
378
  /**
379
   * Rotate around center point
380
   * @param center - Rotation center
381
   * @param angle - Rotation angle in radians
382
   * @returns This vector for chaining
383
   */
384
  rotateAround(center: Vector2, angle: number): this;
385
  
386
  /**
387
   * Random vector within unit circle
388
   * @returns This vector for chaining
389
   */
390
  random(): this;
391
  
392
  /**
393
   * Iterator for component access
394
   */
395
  [Symbol.iterator](): Iterator<number>;
396
}
397

398
/**
399
 * 3D vector with x, y, z components
400
 */
401
class Vector3 {
402
  /** Type flag for vector3 detection */
403
  readonly isVector3: true;
404
  
405
  /** X component */
406
  x: number;
407
  
408
  /** Y component */
409
  y: number;
410
  
411
  /** Z component */
412
  z: number;
413
  
414
  /**
415
   * Create 3D vector
416
   * @param x - X component (default: 0)
417
   * @param y - Y component (default: 0)
418
   * @param z - Z component (default: 0)
419
   */
420
  constructor(x?: number, y?: number, z?: number);
421
  
422
  // All Vector2 methods plus:
423
  
424
  /**
425
   * Set vector components
426
   * @param x - X component
427
   * @param y - Y component
428
   * @param z - Z component
429
   * @returns This vector for chaining
430
   */
431
  set(x: number, y: number, z: number): this;
432
  
433
  /**
434
   * Set Z component
435
   * @param z - Z value
436
   * @returns This vector for chaining
437
   */
438
  setZ(z: number): this;
439
  
440
  /**
441
   * Set from spherical coordinates
442
   * @param s - Spherical coordinates
443
   * @returns This vector for chaining
444
   */
445
  setFromSpherical(s: Spherical): this;
446
  
447
  /**
448
   * Set from spherical coordinates
449
   * @param radius - Distance from origin
450
   * @param phi - Polar angle
451
   * @param theta - Azimuthal angle
452
   * @returns This vector for chaining
453
   */
454
  setFromSphericalCoords(radius: number, phi: number, theta: number): this;
455
  
456
  /**
457
   * Set from cylindrical coordinates
458
   * @param c - Cylindrical coordinates
459
   * @returns This vector for chaining
460
   */
461
  setFromCylindrical(c: Cylindrical): this;
462
  
463
  /**
464
   * Set from cylindrical coordinates
465
   * @param radius - Distance from Y axis
466
   * @param theta - Angle around Y axis
467
   * @param y - Height along Y axis
468
   * @returns This vector for chaining
469
   */
470
  setFromCylindricalCoords(radius: number, theta: number, y: number): this;
471
  
472
  /**
473
   * Set from matrix position (4th column)
474
   * @param m - 4x4 matrix
475
   * @returns This vector for chaining
476
   */
477
  setFromMatrixPosition(m: Matrix4): this;
478
  
479
  /**
480
   * Set from matrix scale (diagonal elements)
481
   * @param m - 4x4 matrix
482
   * @returns This vector for chaining
483
   */
484
  setFromMatrixScale(m: Matrix4): this;
485
  
486
  /**
487
   * Set from matrix column
488
   * @param m - Source matrix
489
   * @param index - Column index (0-3)
490
   * @returns This vector for chaining
491
   */
492
  setFromMatrixColumn(m: Matrix4, index: number): this;
493
  
494
  /**
495
   * Set from Euler angles
496
   * @param e - Euler angles
497
   * @returns This vector for chaining
498
   */
499
  setFromEuler(e: Euler): this;
500
  
501
  /**
502
   * Apply 3x3 matrix transformation
503
   * @param m - 3x3 matrix
504
   * @returns This vector for chaining
505
   */
506
  applyMatrix3(m: Matrix3): this;
507
  
508
  /**
509
   * Apply normal matrix (inverse transpose)
510
   * @param m - Normal matrix
511
   * @returns This vector for chaining
512
   */
513
  applyNormalMatrix(m: Matrix3): this;
514
  
515
  /**
516
   * Apply 4x4 matrix transformation
517
   * @param m - 4x4 matrix
518
   * @returns This vector for chaining
519
   */
520
  applyMatrix4(m: Matrix4): this;
521
  
522
  /**
523
   * Apply quaternion rotation
524
   * @param q - Quaternion rotation
525
   * @returns This vector for chaining
526
   */
527
  applyQuaternion(q: Quaternion): this;
528
  
529
  /**
530
   * Project using camera matrices
531
   * @param camera - Camera with projection matrix
532
   * @returns This vector for chaining
533
   */
534
  project(camera: Camera): this;
535
  
536
  /**
537
   * Unproject from screen space
538
   * @param camera - Camera with projection matrix
539
   * @returns This vector for chaining
540
   */
541
  unproject(camera: Camera): this;
542
  
543
  /**
544
   * Transform direction by matrix (ignore translation)
545
   * @param m - 4x4 matrix
546
   * @returns This vector for chaining
547
   */
548
  transformDirection(m: Matrix4): this;
549
  
550
  /**
551
   * Calculate cross product
552
   * @param v - Vector to cross with
553
   * @returns This vector for chaining
554
   */
555
  cross(v: Vector3): this;
556
  
557
  /**
558
   * Calculate cross product of two vectors
559
   * @param a - First vector
560
   * @param b - Second vector
561
   * @returns This vector for chaining
562
   */
563
  crossVectors(a: Vector3, b: Vector3): this;
564
  
565
  /**
566
   * Project onto another vector
567
   * @param v - Target vector
568
   * @returns This vector for chaining
569
   */
570
  projectOnVector(v: Vector3): this;
571
  
572
  /**
573
   * Project onto plane
574
   * @param planeNormal - Plane normal vector
575
   * @returns This vector for chaining
576
   */
577
  projectOnPlane(planeNormal: Vector3): this;
578
  
579
  /**
580
   * Reflect across plane
581
   * @param normal - Plane normal
582
   * @returns This vector for chaining
583
   */
584
  reflect(normal: Vector3): this;
585
  
586
  /**
587
   * Random vector within unit sphere
588
   * @returns This vector for chaining
589
   */
590
  random(): this;
591
  
592
  /**
593
   * Random direction on unit sphere
594
   * @returns This vector for chaining
595
   */
596
  randomDirection(): this;
597
}
598

599
/**
600
 * 4D vector with x, y, z, w components
601
 */
602
class Vector4 {
603
  /** Type flag for vector4 detection */
604
  readonly isVector4: true;
605
  
606
  /** X component */
607
  x: number;
608
  
609
  /** Y component */
610
  y: number;
611
  
612
  /** Z component */
613
  z: number;
614
  
615
  /** W component */
616
  w: number;
617
  
618
  /** Vector width (alias for z) */
619
  width: number;
620
  
621
  /** Vector height (alias for w) */
622
  height: number;
623
  
624
  /**
625
   * Create 4D vector
626
   * @param x - X component (default: 0)
627
   * @param y - Y component (default: 0)
628
   * @param z - Z component (default: 0)
629
   * @param w - W component (default: 1)
630
   */
631
  constructor(x?: number, y?: number, z?: number, w?: number);
632
  
633
  // Similar methods to Vector3 plus:
634
  
635
  /**
636
   * Set vector components
637
   * @param x - X component
638
   * @param y - Y component
639
   * @param z - Z component
640
   * @param w - W component
641
   * @returns This vector for chaining
642
   */
643
  set(x: number, y: number, z: number, w: number): this;
644
  
645
  /**
646
   * Set W component
647
   * @param w - W value
648
   * @returns This vector for chaining
649
   */
650
  setW(w: number): this;
651
  
652
  /**
653
   * Apply 4x4 matrix transformation
654
   * @param m - 4x4 matrix
655
   * @returns This vector for chaining
656
   */
657
  applyMatrix4(m: Matrix4): this;
658
  
659
  /**
660
   * Divide by W component (perspective divide)
661
   * @returns This vector for chaining
662
   */
663
  divideScalar(scalar: number): this;
664
  
665
  /**
666
   * Set axis and angle from quaternion
667
   * @param q - Source quaternion
668
   * @returns This vector for chaining
669
   */
670
  setAxisAngleFromQuaternion(q: Quaternion): this;
671
  
672
  /**
673
   * Set axis and angle from rotation matrix
674
   * @param m - Rotation matrix
675
   * @returns This vector for chaining
676
   */
677
  setAxisAngleFromRotationMatrix(m: Matrix4): this;
678
}
679
```
680

681
**Usage Examples:**
682

683
```typescript
684
import { Vector2, Vector3, Vector4, Matrix4 } from 'three';
685

686
// Vector creation and operations
687
const v1 = new Vector3(1, 2, 3);
688
const v2 = new Vector3(4, 5, 6);
689

690
// Basic operations
691
const result = v1.clone().add(v2); // (5, 7, 9)
692
const dot = v1.dot(v2); // Dot product: 32
693
const cross = v1.clone().cross(v2); // Cross product
694

695
// Vector transformations
696
const matrix = new Matrix4().makeTranslation(10, 0, 0);
697
v1.applyMatrix4(matrix); // Apply transformation
698

699
// Normalization and length
700
const length = v1.length();
701
v1.normalize(); // Convert to unit vector
702
v1.setLength(5); // Set specific length
703

704
// Interpolation
705
const lerped = v1.clone().lerp(v2, 0.5); // 50% interpolation
706

707
// 2D vectors for UI/screen coordinates
708
const screenPos = new Vector2(100, 200);
709
const uv = new Vector2(0.5, 0.5);
710

711
// 4D vectors for homogeneous coordinates
712
const homogeneous = new Vector4(x, y, z, 1);
713
homogeneous.applyMatrix4(projectionMatrix);
714
```
715

716
### Matrix Mathematics
717

718
Matrix classes for transformations, projections, and linear algebra operations in 2D, 3D, and 4D.
719

720
```typescript { .api }
721
import { Matrix3, Matrix4, Vector3, Quaternion, Euler } from 'three';
722

723
/**
724
 * 3x3 matrix for 2D transformations and normal matrices
725
 */
726
class Matrix3 {
727
  /** Type flag for matrix3 detection */
728
  readonly isMatrix3: true;
729
  
730
  /** Matrix elements in column-major order */
731
  elements: number[];
732
  
733
  /**
734
   * Create 3x3 matrix
735
   */
736
  constructor();
737
  
738
  /**
739
   * Set matrix elements
740
   * @param n11-n33 - Matrix elements (row-major order)
741
   * @returns This matrix for chaining
742
   */
743
  set(
744
    n11: number, n12: number, n13: number,
745
    n21: number, n22: number, n23: number,
746
    n31: number, n32: number, n33: number
747
  ): this;
748
  
749
  /**
750
   * Set to identity matrix
751
   * @returns This matrix for chaining
752
   */
753
  identity(): this;
754
  
755
  /**
756
   * Clone matrix
757
   * @returns New matrix with same values
758
   */
759
  clone(): Matrix3;
760
  
761
  /**
762
   * Copy from another matrix
763
   * @param m - Source matrix
764
   * @returns This matrix for chaining
765
   */
766
  copy(m: Matrix3): this;
767
  
768
  /**
769
   * Extract basis from 4x4 matrix
770
   * @param matrix4 - Source 4x4 matrix
771
   * @returns This matrix for chaining
772
   */
773
  extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
774
  
775
  /**
776
   * Set from 4x4 matrix (upper-left 3x3)
777
   * @param m - Source 4x4 matrix
778
   * @returns This matrix for chaining
779
   */
780
  setFromMatrix4(m: Matrix4): this;
781
  
782
  /**
783
   * Multiply by another matrix
784
   * @param m - Matrix to multiply by
785
   * @returns This matrix for chaining
786
   */
787
  multiply(m: Matrix3): this;
788
  
789
  /**
790
   * Premultiply by another matrix
791
   * @param m - Matrix to multiply with
792
   * @returns This matrix for chaining
793
   */
794
  premultiply(m: Matrix3): this;
795
  
796
  /**
797
   * Multiply two matrices and store result
798
   * @param a - First matrix
799
   * @param b - Second matrix
800
   * @returns This matrix for chaining
801
   */
802
  multiplyMatrices(a: Matrix3, b: Matrix3): this;
803
  
804
  /**
805
   * Multiply by scalar
806
   * @param s - Scalar value
807
   * @returns This matrix for chaining
808
   */
809
  multiplyScalar(s: number): this;
810
  
811
  /**
812
   * Calculate determinant
813
   * @returns Matrix determinant
814
   */
815
  determinant(): number;
816
  
817
  /**
818
   * Invert matrix
819
   * @returns This matrix for chaining
820
   */
821
  invert(): this;
822
  
823
  /**
824
   * Transpose matrix
825
   * @returns This matrix for chaining
826
   */
827
  transpose(): this;
828
  
829
  /**
830
   * Get normal matrix from 4x4 matrix
831
   * @param matrix4 - Source transformation matrix
832
   * @returns This matrix for chaining
833
   */
834
  getNormalMatrix(matrix4: Matrix4): this;
835
  
836
  /**
837
   * Transpose into another matrix
838
   * @param matrix - Target matrix
839
   * @returns This matrix for chaining
840
   */
841
  transposeIntoArray(r: number[]): this;
842
  
843
  /**
844
   * Set UV transform
845
   * @param tx - X translation
846
   * @param ty - Y translation
847
   * @param sx - X scale
848
   * @param sy - Y scale
849
   * @param rotation - Rotation angle
850
   * @param cx - X center
851
   * @param cy - Y center
852
   * @returns This matrix for chaining
853
   */
854
  setUvTransform(
855
    tx: number, ty: number, 
856
    sx: number, sy: number, 
857
    rotation: number, 
858
    cx: number, cy: number
859
  ): this;
860
  
861
  /**
862
   * Scale matrix
863
   * @param sx - X scale
864
   * @param sy - Y scale
865
   * @returns This matrix for chaining
866
   */
867
  scale(sx: number, sy: number): this;
868
  
869
  /**
870
   * Rotate matrix
871
   * @param theta - Rotation angle in radians
872
   * @returns This matrix for chaining
873
   */
874
  rotate(theta: number): this;
875
  
876
  /**
877
   * Translate matrix
878
   * @param tx - X translation
879
   * @param ty - Y translation
880
   * @returns This matrix for chaining
881
   */
882
  translate(tx: number, ty: number): this;
883
  
884
  /**
885
   * Check equality
886
   * @param matrix - Matrix to compare
887
   * @returns True if equal
888
   */
889
  equals(matrix: Matrix3): boolean;
890
  
891
  /**
892
   * Set from array
893
   * @param array - Source array
894
   * @param offset - Array offset
895
   * @returns This matrix for chaining
896
   */
897
  fromArray(array: number[], offset?: number): this;
898
  
899
  /**
900
   * Copy to array
901
   * @param array - Target array
902
   * @param offset - Array offset
903
   * @returns Target array
904
   */
905
  toArray(array?: number[], offset?: number): number[];
906
}
907

908
/**
909
 * 4x4 matrix for 3D transformations and projections
910
 */
911
class Matrix4 {
912
  /** Type flag for matrix4 detection */
913
  readonly isMatrix4: true;
914
  
915
  /** Matrix elements in column-major order */
916
  elements: number[];
917
  
918
  /**
919
   * Create 4x4 matrix
920
   */
921
  constructor();
922
  
923
  /**
924
   * Set matrix elements
925
   * @param n11-n44 - Matrix elements (row-major order)
926
   * @returns This matrix for chaining
927
   */
928
  set(
929
    n11: number, n12: number, n13: number, n14: number,
930
    n21: number, n22: number, n23: number, n24: number,
931
    n31: number, n32: number, n33: number, n34: number,
932
    n41: number, n42: number, n43: number, n44: number
933
  ): this;
934
  
935
  /**
936
   * Set to identity matrix
937
   * @returns This matrix for chaining
938
   */
939
  identity(): this;
940
  
941
  /**
942
   * Clone matrix
943
   * @returns New matrix with same values
944
   */
945
  clone(): Matrix4;
946
  
947
  /**
948
   * Copy from another matrix
949
   * @param m - Source matrix
950
   * @returns This matrix for chaining
951
   */
952
  copy(m: Matrix4): this;
953
  
954
  /**
955
   * Copy position from matrix
956
   * @param m - Source matrix
957
   * @returns This matrix for chaining
958
   */
959
  copyPosition(m: Matrix4): this;
960
  
961
  /**
962
   * Set basis vectors and position
963
   * @param xAxis - X axis vector
964
   * @param yAxis - Y axis vector
965
   * @param zAxis - Z axis vector
966
   * @param origin - Origin position
967
   * @returns This matrix for chaining
968
   */
969
  makeBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3, origin?: Vector3): this;
970
  
971
  /**
972
   * Extract basis vectors
973
   * @param xAxis - Target X axis vector
974
   * @param yAxis - Target Y axis vector
975
   * @param zAxis - Target Z axis vector
976
   * @returns This matrix for chaining
977
   */
978
  extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
979
  
980
  /**
981
   * Create rotation matrix from Euler angles
982
   * @param euler - Euler angles
983
   * @returns This matrix for chaining
984
   */
985
  makeRotationFromEuler(euler: Euler): this;
986
  
987
  /**
988
   * Create rotation matrix from quaternion
989
   * @param q - Quaternion rotation
990
   * @returns This matrix for chaining
991
   */
992
  makeRotationFromQuaternion(q: Quaternion): this;
993
  
994
  /**
995
   * Create look-at matrix
996
   * @param eye - Camera position
997
   * @param target - Look-at target
998
   * @param up - Up direction
999
   * @returns This matrix for chaining
1000
   */
1001
  lookAt(eye: Vector3, target: Vector3, up: Vector3): this;
1002
  
1003
  /**
1004
   * Multiply by another matrix
1005
   * @param m - Matrix to multiply by
1006
   * @returns This matrix for chaining
1007
   */
1008
  multiply(m: Matrix4): this;
1009
  
1010
  /**
1011
   * Premultiply by another matrix
1012
   * @param m - Matrix to multiply with
1013
   * @returns This matrix for chaining
1014
   */
1015
  premultiply(m: Matrix4): this;
1016
  
1017
  /**
1018
   * Multiply two matrices and store result
1019
   * @param a - First matrix
1020
   * @param b - Second matrix
1021
   * @returns This matrix for chaining
1022
   */
1023
  multiplyMatrices(a: Matrix4, b: Matrix4): this;
1024
  
1025
  /**
1026
   * Multiply by scalar
1027
   * @param s - Scalar value
1028
   * @returns This matrix for chaining
1029
   */
1030
  multiplyScalar(s: number): this;
1031
  
1032
  /**
1033
   * Calculate determinant
1034
   * @returns Matrix determinant
1035
   */
1036
  determinant(): number;
1037
  
1038
  /**
1039
   * Invert matrix
1040
   * @returns This matrix for chaining
1041
   */
1042
  invert(): this;
1043
  
1044
  /**
1045
   * Transpose matrix
1046
   * @returns This matrix for chaining
1047
   */
1048
  transpose(): this;
1049
  
1050
  /**
1051
   * Set position component
1052
   * @param v - Position vector
1053
   * @returns This matrix for chaining
1054
   */
1055
  setPosition(v: Vector3): this;
1056
  setPosition(x: number, y: number, z: number): this;
1057
  
1058
  /**
1059
   * Get maximum scale factor
1060
   * @returns Maximum scale
1061
   */
1062
  getMaxScaleOnAxis(): number;
1063
  
1064
  /**
1065
   * Create translation matrix
1066
   * @param x - X translation
1067
   * @param y - Y translation
1068
   * @param z - Z translation
1069
   * @returns This matrix for chaining
1070
   */
1071
  makeTranslation(x: number, y: number, z: number): this;
1072
  
1073
  /**
1074
   * Create rotation matrix around X axis
1075
   * @param theta - Rotation angle
1076
   * @returns This matrix for chaining
1077
   */
1078
  makeRotationX(theta: number): this;
1079
  
1080
  /**
1081
   * Create rotation matrix around Y axis
1082
   * @param theta - Rotation angle
1083
   * @returns This matrix for chaining
1084
   */
1085
  makeRotationY(theta: number): this;
1086
  
1087
  /**
1088
   * Create rotation matrix around Z axis
1089
   * @param theta - Rotation angle
1090
   * @returns This matrix for chaining
1091
   */
1092
  makeRotationZ(theta: number): this;
1093
  
1094
  /**
1095
   * Create rotation matrix around arbitrary axis
1096
   * @param axis - Rotation axis (normalized)
1097
   * @param angle - Rotation angle
1098
   * @returns This matrix for chaining
1099
   */
1100
  makeRotationAxis(axis: Vector3, angle: number): this;
1101
  
1102
  /**
1103
   * Create scale matrix
1104
   * @param x - X scale
1105
   * @param y - Y scale
1106
   * @param z - Z scale
1107
   * @returns This matrix for chaining
1108
   */
1109
  makeScale(x: number, y: number, z: number): this;
1110
  
1111
  /**
1112
   * Create shear matrix
1113
   * @param xy - XY shear
1114
   * @param xz - XZ shear
1115
   * @param yx - YX shear
1116
   * @param yz - YZ shear
1117
   * @param zx - ZX shear
1118
   * @param zy - ZY shear
1119
   * @returns This matrix for chaining
1120
   */
1121
  makeShear(xy: number, xz: number, yx: number, yz: number, zx: number, zy: number): this;
1122
  
1123
  /**
1124
   * Create perspective projection matrix
1125
   * @param left - Left plane
1126
   * @param right - Right plane
1127
   * @param top - Top plane
1128
   * @param bottom - Bottom plane
1129
   * @param near - Near plane
1130
   * @param far - Far plane
1131
   * @returns This matrix for chaining
1132
   */
1133
  makePerspective(
1134
    left: number, right: number, 
1135
    top: number, bottom: number, 
1136
    near: number, far: number
1137
  ): this;
1138
  
1139
  /**
1140
   * Create orthographic projection matrix
1141
   * @param left - Left plane
1142
   * @param right - Right plane
1143
   * @param top - Top plane
1144
   * @param bottom - Bottom plane
1145
   * @param near - Near plane
1146
   * @param far - Far plane
1147
   * @returns This matrix for chaining
1148
   */
1149
  makeOrthographic(
1150
    left: number, right: number, 
1151
    top: number, bottom: number, 
1152
    near: number, far: number
1153
  ): this;
1154
  
1155
  /**
1156
   * Check equality
1157
   * @param matrix - Matrix to compare
1158
   * @returns True if equal
1159
   */
1160
  equals(matrix: Matrix4): boolean;
1161
  
1162
  /**
1163
   * Set from array
1164
   * @param array - Source array
1165
   * @param offset - Array offset
1166
   * @returns This matrix for chaining
1167
   */
1168
  fromArray(array: number[], offset?: number): this;
1169
  
1170
  /**
1171
   * Copy to array
1172
   * @param array - Target array
1173
   * @param offset - Array offset
1174
   * @returns Target array
1175
   */
1176
  toArray(array?: number[], offset?: number): number[];
1177
  
1178
  /**
1179
   * Decompose matrix into components
1180
   * @param position - Output position vector
1181
   * @param quaternion - Output quaternion
1182
   * @param scale - Output scale vector
1183
   * @returns This matrix for chaining
1184
   */
1185
  decompose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
1186
  
1187
  /**
1188
   * Compose matrix from components
1189
   * @param position - Position vector
1190
   * @param quaternion - Quaternion rotation
1191
   * @param scale - Scale vector
1192
   * @returns This matrix for chaining
1193
   */
1194
  compose(position: Vector3, quaternion: Quaternion, scale: Vector3): this;
1195
}
1196
```
1197

1198
**Usage Examples:**
1199

1200
```typescript
1201
import { Matrix4, Matrix3, Vector3, Quaternion, Euler } from 'three';
1202

1203
// Create transformation matrices
1204
const translation = new Matrix4().makeTranslation(10, 0, 0);
1205
const rotation = new Matrix4().makeRotationY(Math.PI / 4);
1206
const scale = new Matrix4().makeScale(2, 2, 2);
1207

1208
// Combine transformations
1209
const transform = new Matrix4()
1210
  .multiply(translation)
1211
  .multiply(rotation)
1212
  .multiply(scale);
1213

1214
// Create from components
1215
const position = new Vector3(1, 2, 3);
1216
const quaternion = new Quaternion().setFromEuler(new Euler(0, Math.PI/2, 0));
1217
const scaleVec = new Vector3(1, 1, 1);
1218

1219
const composed = new Matrix4().compose(position, quaternion, scaleVec);
1220

1221
// Decompose matrix
1222
const pos = new Vector3();
1223
const quat = new Quaternion();
1224
const scl = new Vector3();
1225
composed.decompose(pos, quat, scl);
1226

1227
// Normal matrix for lighting
1228
const normalMatrix = new Matrix3().getNormalMatrix(transform);
1229

1230
// Projection matrices
1231
const perspective = new Matrix4().makePerspective(-1, 1, 1, -1, 1, 100);
1232
const orthographic = new Matrix4().makeOrthographic(-10, 10, 10, -10, 1, 100);
1233
```
1234

1235
### Geometric Primitives
1236

1237
Mathematical primitives for 3D geometry calculations including rays, planes, spheres, and spatial testing.
1238

1239
```typescript { .api }
1240
import { Ray, Vector3, Plane, Sphere, Box3, Triangle } from 'three';
1241

1242
/**
1243
 * Ray for raycasting and geometric calculations
1244
 */
1245
class Ray {
1246
  /** Ray origin point */
1247
  origin: Vector3;
1248
  
1249
  /** Ray direction vector (should be normalized) */
1250
  direction: Vector3;
1251
  
1252
  /**
1253
   * Create ray
1254
   * @param origin - Ray origin point
1255
   * @param direction - Ray direction (normalized)
1256
   */
1257
  constructor(origin?: Vector3, direction?: Vector3);
1258
  
1259
  /**
1260
   * Set ray origin and direction
1261
   * @param origin - Ray origin point
1262
   * @param direction - Ray direction
1263
   * @returns This ray for chaining
1264
   */
1265
  set(origin: Vector3, direction: Vector3): this;
1266
  
1267
  /**
1268
   * Copy from another ray
1269
   * @param ray - Source ray
1270
   * @returns This ray for chaining
1271
   */
1272
  copy(ray: Ray): this;
1273
  
1274
  /**
1275
   * Get point along ray at distance t
1276
   * @param t - Distance along ray
1277
   * @param target - Target vector for result
1278
   * @returns Point on ray
1279
   */
1280
  at(t: number, target: Vector3): Vector3;
1281
  
1282
  /**
1283
   * Transform ray by matrix
1284
   * @param matrix4 - Transformation matrix
1285
   * @returns This ray for chaining
1286
   */
1287
  applyMatrix4(matrix4: Matrix4): this;
1288
  
1289
  /**
1290
   * Get closest point on ray to given point
1291
   * @param point - Reference point
1292
   * @param target - Target vector for result
1293
   * @returns Closest point on ray
1294
   */
1295
  closestPointToPoint(point: Vector3, target: Vector3): Vector3;
1296
  
1297
  /**
1298
   * Get distance from ray to point
1299
   * @param point - Reference point
1300
   * @returns Distance to point
1301
   */
1302
  distanceToPoint(point: Vector3): number;
1303
  
1304
  /**
1305
   * Test intersection with sphere
1306
   * @param sphere - Sphere to test
1307
   * @param target - Target vector for intersection point
1308
   * @returns Intersection point or null
1309
   */
1310
  intersectSphere(sphere: Sphere, target: Vector3): Vector3 | null;
1311
  
1312
  /**
1313
   * Test intersection with plane
1314
   * @param plane - Plane to test
1315
   * @param target - Target vector for intersection point
1316
   * @returns Intersection point or null
1317
   */
1318
  intersectPlane(plane: Plane, target: Vector3): Vector3 | null;
1319
  
1320
  /**
1321
   * Test intersection with triangle
1322
   * @param a - Triangle vertex A
1323
   * @param b - Triangle vertex B
1324
   * @param c - Triangle vertex C
1325
   * @param backfaceCulling - Enable backface culling
1326
   * @param target - Target vector for intersection point
1327
   * @returns Intersection point or null
1328
   */
1329
  intersectTriangle(a: Vector3, b: Vector3, c: Vector3, backfaceCulling: boolean, target: Vector3): Vector3 | null;
1330
}
1331
```
1332

1333
The math system provides the mathematical foundation for all 3D graphics operations in Three.js, with optimized vector operations, transformation matrices, and geometric calculations essential for rendering, animation, and interaction.