0
# Matrix Operations
1

2
Comprehensive matrix mathematics for linear algebra, 3D graphics transformations, and scientific computing. PyGLM provides matrices from 2×2 to 4×4 in multiple precisions with complete linear algebra operations.
3

4
## Capabilities
5

6
### Matrix Types
7

8
PyGLM provides a complete set of matrix types for all common graphics and scientific computing applications.
9

10
```python { .api }
11
# Float32 matrices (default precision)
12
class mat2x2:
13
    def __init__(self): ...  # Identity matrix
14
    def __init__(self, diagonal: float): ...  # Diagonal matrix
15
    def __init__(self, col0: vec2, col1: vec2): ...  # From column vectors
16
    def __getitem__(self, index: int) -> vec2: ...  # Column access
17
    def __setitem__(self, index: int, value: vec2): ...
18

19
class mat2x3:
20
    def __init__(self): ...
21
    def __getitem__(self, index: int) -> vec3: ...
22

23
class mat2x4:
24
    def __init__(self): ...
25
    def __getitem__(self, index: int) -> vec4: ...
26

27
class mat3x2:
28
    def __init__(self): ...
29
    def __getitem__(self, index: int) -> vec2: ...
30

31
class mat3x3:
32
    def __init__(self): ...  # Identity matrix
33
    def __init__(self, diagonal: float): ...  # Diagonal matrix
34
    def __init__(self, col0: vec3, col1: vec3, col2: vec3): ...  # From column vectors
35
    def __getitem__(self, index: int) -> vec3: ...
36

37
class mat3x4:
38
    def __init__(self): ...
39
    def __getitem__(self, index: int) -> vec4: ...
40

41
class mat4x2:
42
    def __init__(self): ...
43
    def __getitem__(self, index: int) -> vec2: ...
44

45
class mat4x3:
46
    def __init__(self): ...
47
    def __getitem__(self, index: int) -> vec3: ...
48

49
class mat4x4:
50
    def __init__(self): ...  # Identity matrix
51
    def __init__(self, diagonal: float): ...  # Diagonal matrix
52
    def __init__(self, col0: vec4, col1: vec4, col2: vec4, col3: vec4): ...  # From column vectors
53
    def __getitem__(self, index: int) -> vec4: ...
54

55
# Convenient aliases for square matrices
56
mat2 = mat2x2  # 2×2 matrix
57
mat3 = mat3x3  # 3×3 matrix  
58
mat4 = mat4x4  # 4×4 matrix
59

60
# Double precision matrices  
61
class dmat2x2:
62
    def __init__(self): ...
63
    def __getitem__(self, index: int) -> dvec2: ...
64

65
class dmat2x3:
66
    def __init__(self): ...
67
    def __getitem__(self, index: int) -> dvec3: ...
68

69
class dmat2x4:
70
    def __init__(self): ...
71
    def __getitem__(self, index: int) -> dvec4: ...
72

73
class dmat3x2:
74
    def __init__(self): ...
75
    def __getitem__(self, index: int) -> dvec2: ...
76

77
class dmat3x3:
78
    def __init__(self): ...
79
    def __getitem__(self, index: int) -> dvec3: ...
80

81
class dmat3x4:
82
    def __init__(self): ...
83
    def __getitem__(self, index: int) -> dvec4: ...
84

85
class dmat4x2:
86
    def __init__(self): ...
87
    def __getitem__(self, index: int) -> dvec2: ...
88

89
class dmat4x3:
90
    def __init__(self): ...
91
    def __getitem__(self, index: int) -> dvec3: ...
92

93
class dmat4x4:
94
    def __init__(self): ...
95
    def __getitem__(self, index: int) -> dvec4: ...
96

97
dmat2 = dmat2x2  # Double precision 2×2
98
dmat3 = dmat3x3  # Double precision 3×3
99
dmat4 = dmat4x4  # Double precision 4×4
100

101
# Integer matrices (signed 32-bit)
102
class imat2x2:
103
    def __init__(self): ...
104
    def __getitem__(self, index: int) -> ivec2: ...
105

106
class imat2x3:
107
    def __init__(self): ...
108
    def __getitem__(self, index: int) -> ivec3: ...
109

110
class imat2x4:
111
    def __init__(self): ...
112
    def __getitem__(self, index: int) -> ivec4: ...
113

114
class imat3x2:
115
    def __init__(self): ...
116
    def __getitem__(self, index: int) -> ivec2: ...
117

118
class imat3x3:
119
    def __init__(self): ...
120
    def __getitem__(self, index: int) -> ivec3: ...
121

122
class imat3x4:
123
    def __init__(self): ...
124
    def __getitem__(self, index: int) -> ivec4: ...
125

126
class imat4x2:
127
    def __init__(self): ...
128
    def __getitem__(self, index: int) -> ivec2: ...
129

130
class imat4x3:
131
    def __init__(self): ...
132
    def __getitem__(self, index: int) -> ivec3: ...
133

134
class imat4x4:
135
    def __init__(self): ...
136
    def __getitem__(self, index: int) -> ivec4: ...
137

138
imat2 = imat2x2  # Integer 2×2
139
imat3 = imat3x3  # Integer 3×3
140
imat4 = imat4x4  # Integer 4×4
141

142
# Unsigned integer matrices
143
class umat2x2:
144
    def __init__(self): ...
145
    def __getitem__(self, index: int) -> uvec2: ...
146

147
class umat2x3:
148
    def __init__(self): ...
149
    def __getitem__(self, index: int) -> uvec3: ...
150

151
class umat2x4:
152
    def __init__(self): ...
153
    def __getitem__(self, index: int) -> uvec4: ...
154

155
class umat3x2:
156
    def __init__(self): ...
157
    def __getitem__(self, index: int) -> uvec2: ...
158

159
class umat3x3:
160
    def __init__(self): ...
161
    def __getitem__(self, index: int) -> uvec3: ...
162

163
class umat3x4:
164
    def __init__(self): ...
165
    def __getitem__(self, index: int) -> uvec4: ...
166

167
class umat4x2:
168
    def __init__(self): ...
169
    def __getitem__(self, index: int) -> uvec2: ...
170

171
class umat4x3:
172
    def __init__(self): ...
173
    def __getitem__(self, index: int) -> uvec3: ...
174

175
class umat4x4:
176
    def __init__(self): ...
177
    def __getitem__(self, index: int) -> uvec4: ...
178

179
umat2 = umat2x2  # Unsigned integer 2×2
180
umat3 = umat3x3  # Unsigned integer 3×3
181
umat4 = umat4x4  # Unsigned integer 4×4
182
```
183

184
**Type Aliases**: PyGLM provides convenient aliases for matrix types:
185
- `f32mat*` = `fmat*` = `mat*` - 32-bit float matrices
186
- `f64mat*` = `dmat*` - 64-bit double matrices  
187
- `i32mat*` = `imat*` - 32-bit signed integer matrices
188
- `u32mat*` = `umat*` - 32-bit unsigned integer matrices
189
```
190
191
### Basic Matrix Operations
192

193
Core linear algebra operations including transpose, inverse, determinant, and matrix multiplication.
194

195
```python { .api }
196
def transpose(m):
197
    """
198
    Calculate the transpose of a matrix.
199

200
    Args:
201
        m: Matrix of any supported type and dimension
202

203
    Returns:
204
        Transposed matrix where rows become columns
205
    """
206

207
def inverse(m):
208
    """
209
    Calculate the inverse of a square matrix.
210

211
    Args:
212
        m: Square matrix (2×2, 3×3, or 4×4)
213

214
    Returns:
215
        Inverse matrix, or identity if matrix is singular
216

217
    Note:
218
        Only works with square matrices
219
    """
220

221
def determinant(m):
222
    """  
223
    Calculate the determinant of a square matrix.
224

225
    Args:
226
        m: Square matrix (2×2, 3×3, or 4×4)
227

228
    Returns:
229
        Scalar determinant value
230
    """
231

232
def matrixCompMult(x, y):
233
    """
234
    Component-wise multiplication of two matrices.
235

236
    Args:
237
        x: First matrix
238
        y: Second matrix of same dimensions
239

240
    Returns:
241
        Matrix where result[i][j] = x[i][j] * y[i][j]
242

243
    Note:
244
        This is NOT standard matrix multiplication
245
    """
246

247
def outerProduct(c, r):
248
    """
249
    Calculate the outer product of two vectors.
250

251
    Args:
252
        c: Column vector
253
        r: Row vector
254

255
    Returns:
256
        Matrix where result[i][j] = c[i] * r[j]
257
    """
258
```
259

260
### Matrix Construction
261

262
Utility functions for creating and manipulating matrices including identity matrix construction and decomposition.
263

264
```python { .api }
265
def identity(matrix_type):
266
    """
267
    Create an identity matrix of the specified type.
268

269
    Args:
270
        matrix_type: Matrix class (e.g., mat4, mat3, dmat4)
271

272
    Returns:
273
        Identity matrix of the specified type
274

275
    Example:
276
        identity_4x4 = glm.identity(glm.mat4)
277
    """
278

279
def decompose(ModelMatrix, Scale, Orientation, Translation, Skew, Perspective):
280
    """
281
    Decompose a transformation matrix into its components.
282

283
    Args:
284
        ModelMatrix: 4×4 transformation matrix to decompose
285
        Scale: vec3 to receive scaling factors (output)
286
        Orientation: quat to receive rotation (output)  
287
        Translation: vec3 to receive translation (output)
288
        Skew: vec3 to receive skew factors (output)
289
        Perspective: vec4 to receive perspective factors (output)
290

291
    Returns:
292
        Boolean indicating success of decomposition
293
    """
294
```
295

296
### Matrix Arithmetic
297

298
All matrix types support standard arithmetic operations through operator overloading:
299

300
- **Addition**: `m1 + m2` - Component-wise addition
301
- **Subtraction**: `m1 - m2` - Component-wise subtraction
302
- **Matrix Multiplication**: `m1 * m2` - Standard matrix multiplication
303
- **Scalar Multiplication**: `m * scalar` - Scale all components
304
- **Vector Multiplication**: `m * v` - Transform vector by matrix
305
- **Negation**: `-m` - Component-wise negation
306
- **Column Access**: `m[i]` - Access matrix columns as vectors
307
- **Comparison**: `m1 == m2`, `m1 != m2` - Component-wise equality
308

309
### Matrix-Vector Operations
310

311
```python { .api }
312
# Matrix-vector multiplication examples:
313
# For mat4 * vec4: transforms 4D vector (typically homogeneous coordinates)
314
# For mat3 * vec3: transforms 3D vector (rotation, scaling)
315
# For mat2 * vec2: transforms 2D vector
316

317
# The following operations are supported through operator overloading:
318
# result_vec4 = mat4_instance * vec4_instance
319
# result_vec3 = mat3_instance * vec3_instance  
320
# result_vec2 = mat2_instance * vec2_instance
321
```
322

323
### Usage Examples
324

325
```python
326
from pyglm import glm
327

328
# Create matrices
329
identity_4x4 = glm.mat4()  # 4×4 identity matrix
330
diagonal_3x3 = glm.mat3(2.0)  # 3×3 matrix with 2.0 on diagonal
331

332
# Create from column vectors
333
col0 = glm.vec3(1, 0, 0)
334
col1 = glm.vec3(0, 1, 0) 
335
col2 = glm.vec3(0, 0, 1)
336
matrix_3x3 = glm.mat3(col0, col1, col2)
337

338
# Matrix operations
339
transposed = glm.transpose(matrix_3x3)
340
inverse_mat = glm.inverse(matrix_3x3)
341
det = glm.determinant(matrix_3x3)  # Should be 1.0 for identity
342

343
# Matrix arithmetic
344
m1 = glm.mat3(1.0)  # Identity
345
m2 = glm.mat3(2.0)  # Diagonal with 2.0
346
sum_matrix = m1 + m2  # Component-wise addition
347
product = m1 * m2     # Matrix multiplication
348

349
# Transform vectors
350
point = glm.vec3(1, 2, 3)
351
transformed = matrix_3x3 * point
352

353
# Access matrix columns
354
first_column = matrix_3x3[0]  # vec3
355
matrix_3x3[1] = glm.vec3(0, 2, 0)  # Set second column
356

357
# 4×4 matrices for 3D graphics
358
model_matrix = glm.mat4()
359
view_matrix = glm.mat4()
360
projection_matrix = glm.mat4()
361

362
# Combined transformation (applied right to left)
363
mvp_matrix = projection_matrix * view_matrix * model_matrix
364

365
# Transform homogeneous coordinates
366
homogeneous_point = glm.vec4(1, 2, 3, 1)  # (x, y, z, w)
367
transformed_point = mvp_matrix * homogeneous_point
368

369
# Matrix decomposition (4×4 only)
370
scale = glm.vec3()
371
orientation = glm.quat()
372
translation = glm.vec3()
373
skew = glm.vec3()
374
perspective = glm.vec4()
375

376
success = glm.decompose(model_matrix, scale, orientation, translation, skew, perspective)
377

378
# Different precision matrices
379
double_matrix = glm.dmat4()  # Double precision
380
integer_matrix = glm.imat3()  # Integer matrix
381
unsigned_matrix = glm.umat2() # Unsigned integer matrix
382

383
# Non-square matrices for specialized applications
384
mat_2x3 = glm.mat2x3()  # 2 columns, 3 rows
385
mat_3x4 = glm.mat3x4()  # 3 columns, 4 rows
386
```
387

388
### Matrix Layout and Memory
389

390
PyGLM matrices use column-major order (like OpenGL):
391
- `matrix[0]` = first column vector
392
- `matrix[1]` = second column vector  
393
- etc.
394

395
For row-major access, use transpose or access individual elements through the column vectors:
396
```python
397
# Column-major access (preferred)
398
first_column = matrix[0]
399
element = matrix[column][row]
400

401
# Get element at row 2, column 1
402
element = matrix[1][2]  # matrix[column][row]
403
```
404

405
The memory layout is compatible with OpenGL's expected matrix format, making it easy to pass matrices directly to graphics APIs using the `value_ptr()` function.