0
# Matrix Operations
1

2
2D and 3D matrix transformations for complex animation effects, coordinate transformations, and advanced geometric operations in React Native.
3

4
## Capabilities
5

6
### Matrix Types
7

8
```typescript { .api }
9
/**
10
 * 3x3 transformation matrix (2D transformations)
11
 */
12
type Matrix3 = readonly [
13
  number, number, number,
14
  number, number, number,
15
  number, number, number
16
];
17

18
/**
19
 * 4x4 transformation matrix (3D transformations)
20
 */
21
type Matrix4 = readonly [
22
  number, number, number, number,
23
  number, number, number, number,
24
  number, number, number, number,
25
  number, number, number, number
26
];
27

28
/**
29
 * 2D vector type for matrix operations
30
 */
31
type Vec2 = readonly [number, number];
32
```
33

34
### 2D Matrix Operations
35

36
```typescript { .api }
37
/**
38
 * 3x3 identity matrix
39
 */
40
const identity3: Matrix3;
41

42
/**
43
 * Multiply two 3x3 matrices
44
 * @param m1 - First matrix
45
 * @param m2 - Second matrix
46
 * @returns Product matrix
47
 */
48
function multiply3(m1: Matrix3, m2: Matrix3): Matrix3;
49

50
/**
51
 * Apply matrix transformation to a 2D point
52
 * @param matrix - 3x3 transformation matrix
53
 * @param point - Point to transform
54
 * @returns Transformed point
55
 */
56
function mapPoint(matrix: Matrix3, point: Vec2): Vec2;
57

58
/**
59
 * Calculate dot product of two 3D vectors
60
 * @param row - First vector
61
 * @param col - Second vector
62
 * @returns Dot product
63
 */
64
function dot3(row: readonly [number, number, number], col: readonly [number, number, number]): number;
65

66
/**
67
 * Multiply 3x3 matrix with 3D vector
68
 * @param matrix - 3x3 matrix
69
 * @param vector - 3D vector
70
 * @returns Transformed vector
71
 */
72
function matrixVecMul3(matrix: Matrix3, vector: readonly [number, number, number]): readonly [number, number, number];
73
```
74

75
### 3D Matrix Operations
76

77
```typescript { .api }
78
/**
79
 * 4x4 identity matrix
80
 */
81
const identity4: Matrix4;
82

83
/**
84
 * Create 3D translation matrix
85
 * @param x - X translation
86
 * @param y - Y translation
87
 * @param z - Z translation
88
 * @returns Translation matrix
89
 */
90
function translate(x: number, y: number, z: number): Matrix4;
91

92
/**
93
 * Create 3D rotation matrix around arbitrary axis
94
 * @param axis - Rotation axis vector
95
 * @param angle - Rotation angle in radians
96
 * @returns Rotation matrix
97
 */
98
function rotate(axis: readonly [number, number, number], angle: number): Matrix4;
99

100
/**
101
 * Create X-axis rotation matrix
102
 * @param angle - Rotation angle in radians
103
 * @returns Rotation matrix
104
 */
105
function rotateX(angle: number): Matrix4;
106

107
/**
108
 * Create Y-axis rotation matrix
109
 * @param angle - Rotation angle in radians
110
 * @returns Rotation matrix
111
 */
112
function rotateY(angle: number): Matrix4;
113

114
/**
115
 * Create Z-axis rotation matrix
116
 * @param angle - Rotation angle in radians
117
 * @returns Rotation matrix
118
 */
119
function rotateZ(angle: number): Matrix4;
120

121
/**
122
 * Create perspective transformation matrix
123
 * @param perspective - Perspective value
124
 * @returns Perspective matrix
125
 */
126
function perspective(perspective: number): Matrix4;
127

128
/**
129
 * Create X-axis skew matrix
130
 * @param angle - Skew angle in radians
131
 * @returns Skew matrix
132
 */
133
function skewX(angle: number): Matrix4;
134

135
/**
136
 * Create Y-axis skew matrix
137
 * @param angle - Skew angle in radians
138
 * @returns Skew matrix
139
 */
140
function skewY(angle: number): Matrix4;
141

142
/**
143
 * Multiply two 4x4 matrices
144
 * @param a - First matrix
145
 * @param b - Second matrix
146
 * @returns Product matrix
147
 */
148
function multiply4(a: Matrix4, b: Matrix4): Matrix4;
149

150
/**
151
 * Apply 4x4 matrix transformation to 3D point
152
 * @param matrix - 4x4 transformation matrix
153
 * @param point - 3D point to transform
154
 * @returns Transformed point
155
 */
156
function mapPoint3d(matrix: Matrix4, point: readonly [number, number, number]): readonly [number, number, number];
157

158
/**
159
 * Convert 4x4 matrix to 3x3 matrix
160
 * @param matrix - 4x4 matrix
161
 * @returns 3x3 matrix
162
 */
163
function toMatrix3(matrix: Matrix4): Matrix3;
164
```
165

166
### Transform Processing
167

168
```typescript { .api }
169
/**
170
 * 2D transformation types
171
 */
172
type Transforms2d = (
173
  | { translateX: number }
174
  | { translateY: number }
175
  | { scale: number }
176
  | { scaleX: number }
177
  | { scaleY: number }
178
  | { skewX: string }
179
  | { skewY: string }
180
  | { rotate: string }
181
  | { rotateZ: string }
182
)[];
183

184
/**
185
 * 3D transformation types
186
 */
187
type Transforms3d = (
188
  | { translateX: number }
189
  | { translateY: number }
190
  | { translateZ: number }
191
  | { translate: readonly [number, number] | readonly [number, number, number] }
192
  | { scale: number }
193
  | { scaleX: number }
194
  | { scaleY: number }
195
  | { skewX: number }
196
  | { skewY: number }
197
  | { rotateX: number }
198
  | { rotateY: number }
199
  | { rotateZ: number }
200
  | { rotate: number }
201
  | { perspective: number }
202
  | { matrix: Matrix4 }
203
)[];
204

205
/**
206
 * Process 2D transforms into a single 3x3 matrix
207
 * @param transforms - Array of 2D transformations
208
 * @returns Combined transformation matrix
209
 */
210
function processTransform2d(transforms: Transforms2d): Matrix3;
211

212
/**
213
 * Process 3D transforms into a single 4x4 matrix
214
 * @param transforms - Array of 3D transformations
215
 * @returns Combined transformation matrix
216
 */
217
function processTransform3d(transforms: Transforms3d): Matrix4;
218

219
/**
220
 * Concatenate matrix with additional transforms
221
 * @param matrix - Base matrix
222
 * @param transforms - Additional transforms to apply
223
 * @returns Combined matrix
224
 */
225
function concat4(matrix: Matrix4, transforms: Transforms3d): Matrix4;
226
```
227

228
### SVG Integration
229

230
```typescript { .api }
231
/**
232
 * Convert 2D transforms to SVG matrix string
233
 * @param transforms - 2D transformations
234
 * @returns SVG matrix string
235
 */
236
function svgMatrix(transforms: Transforms2d): string;
237

238
/**
239
 * Parse angle string to radians
240
 * @param angle - Angle string (e.g., "45deg" or "1.5")
241
 * @returns Angle in radians
242
 */
243
function parseAngle(angle: string): number;
244
```
245

246
### Matrix Decomposition
247

248
```typescript { .api }
249
/**
250
 * Decompose matrix back to individual transforms
251
 * @param matrix - Matrix or transforms to decompose
252
 * @returns Array of decomposed transforms
253
 */
254
function decompose2d(matrix: Matrix3 | Transforms2d): readonly [
255
  { translateX: number },
256
  { translateY: number },
257
  { rotateZ: number },
258
  { scaleX: number },
259
  { scaleY: number },  
260
  { rotateZ: number }
261
];
262
```
263

264
**Usage Examples:**
265

266
```typescript
267
import {
268
  processTransform2d,
269
  processTransform3d,
270
  multiply3,
271
  multiply4,
272
  mapPoint,
273
  decompose2d,
274
  svgMatrix
275
} from "react-native-redash";
276
import { useAnimatedStyle, useSharedValue } from "react-native-reanimated";
277

278
// 2D transformations
279
const rotation = useSharedValue(0);
280
const scale = useSharedValue(1);
281

282
const animatedStyle = useAnimatedStyle(() => {
283
  const transforms = [
284
    { translateX: 50 },
285
    { rotate: `${rotation.value}deg` },
286
    { scale: scale.value },
287
    { translateX: -50 }
288
  ];
289
  
290
  // Process transforms to matrix
291
  const matrix = processTransform2d(transforms);
292
  
293
  // Could apply additional matrix operations here
294
  const combinedMatrix = multiply3(matrix, identity3);
295
  
296
  return {
297
    transform: transforms // React Native handles the conversion
298
  };
299
});
300

301
// 3D transformations
302
const animatedStyle3D = useAnimatedStyle(() => {
303
  const transforms3d = [
304
    { perspective: 1000 },
305
    { rotateY: `${rotation.value}deg` },
306
    { translateZ: 50 }
307
  ];
308
  
309
  const matrix = processTransform3d(transforms3d);
310
  
311
  return {
312
    transform: transforms3d
313
  };
314
});
315

316
// Matrix operations for custom calculations
317
const point = [100, 100] as const;
318
const transformMatrix = processTransform2d([
319
  { translateX: 50 },
320
  { rotate: "45deg" },
321
  { scale: 1.5 }
322
]);
323

324
const transformedPoint = mapPoint(transformMatrix, point);
325
```
326

327
**SVG Integration Example:**
328

329
```typescript
330
import React from "react";
331
import Svg, { Rect } from "react-native-svg";
332
import { svgMatrix, processTransform2d } from "react-native-redash";
333
import { useAnimatedProps, useSharedValue } from "react-native-reanimated";
334

335
const AnimatedRect = Animated.createAnimatedComponent(Rect);
336

337
export const AnimatedSVGRect = () => {
338
  const rotation = useSharedValue(0);
339
  
340
  const animatedProps = useAnimatedProps(() => {
341
    const transforms = [
342
      { translateX: 50 },
343
      { rotate: `${rotation.value}deg` },
344
      { translateX: -50 }
345
    ];
346
    
347
    return {
348
      transform: svgMatrix(transforms)
349
    };
350
  });
351
  
352
  return (
353
    <Svg width="100" height="100">
354
      <AnimatedRect
355
        x="25"
356
        y="25"
357
        width="50"
358
        height="50"
359
        fill="blue"
360
        animatedProps={animatedProps}
361
      />
362
    </Svg>
363
  );
364
};
365
```
366

367
**Matrix Utility Object:**
368

369
```typescript { .api }
370
/**
371
 * Utility object with common matrix operations
372
 */
373
const Matrix4: {
374
  translate: typeof translate;
375
  scale: (sx: number, sy: number, sz: number) => Matrix4;
376
  rotateX: typeof rotateX;
377
  rotateY: typeof rotateY;
378
  rotateZ: typeof rotateZ;
379
};
380
```
381

382
**Type Guards for Transform Detection:**
383

384
```typescript { .api }
385
function isTranslateX(transform: Transforms2d[0]): transform is { translateX: number };
386
function isTranslateY(transform: Transforms2d[0]): transform is { translateY: number };
387
function isScale(transform: Transforms2d[0]): transform is { scale: number };
388
function isScaleX(transform: Transforms2d[0]): transform is { scaleX: number };
389
function isScaleY(transform: Transforms2d[0]): transform is { scaleY: number };
390
function isSkewX(transform: Transforms2d[0]): transform is { skewX: string };
391
function isSkewY(transform: Transforms2d[0]): transform is { skewY: string };
392
function isRotate(transform: Transforms2d[0]): transform is { rotate: string };
393
function isRotateZ(transform: Transforms2d[0]): transform is { rotateZ: string };
394
```