0
# Transformation Functions
1

2
High-level transformation matrix creation functions essential for 3D graphics programming. These functions create the standard projection, view, and model transformation matrices used in OpenGL, DirectX, and other graphics APIs.
3

4
## Capabilities
5

6
### Projection Matrices
7

8
Functions for creating projection matrices that transform 3D coordinates to screen coordinates.
9

10
```python { .api }
11
def perspective(fovy, aspect, near, far):
12
    """
13
    Create a perspective projection matrix.
14

15
    Args:
16
        fovy: Field of view angle in radians (vertical)
17
        aspect: Aspect ratio (width/height)
18
        near: Near clipping plane distance (must be positive)
19
        far: Far clipping plane distance (must be positive)
20

21
    Returns:
22
        4×4 perspective projection matrix
23

24
    Example:
25
        proj = glm.perspective(glm.radians(45.0), 16.0/9.0, 0.1, 100.0)
26
    """
27

28
def perspectiveFov(fov, width, height, near, far):
29
    """
30
    Create a perspective projection matrix using field of view.
31

32
    Args:
33
        fov: Field of view angle in radians
34
        width: Viewport width
35
        height: Viewport height  
36
        near: Near clipping plane distance
37
        far: Far clipping plane distance
38

39
    Returns:
40
        4×4 perspective projection matrix
41
    """
42

43
def ortho(left, right, bottom, top, near, far):
44
    """
45
    Create an orthographic projection matrix.
46

47
    Args:
48
        left: Left clipping plane
49
        right: Right clipping plane
50
        bottom: Bottom clipping plane
51
        top: Top clipping plane
52
        near: Near clipping plane
53
        far: Far clipping plane
54

55
    Returns:
56
        4×4 orthographic projection matrix
57

58
    Example:
59
        ortho_proj = glm.ortho(-10.0, 10.0, -10.0, 10.0, -1.0, 1.0)
60
    """
61

62
def frustum(left, right, bottom, top, near, far):
63
    """
64
    Create a frustum projection matrix.
65

66
    Args:
67
        left: Left clipping plane at near
68
        right: Right clipping plane at near
69
        bottom: Bottom clipping plane at near
70
        top: Top clipping plane at near
71
        near: Near clipping plane distance
72
        far: Far clipping plane distance
73

74
    Returns:
75
        4×4 frustum projection matrix
76
    """
77

78
def infinitePerspective(fovy, aspect, near):
79
    """
80
    Create an infinite perspective projection matrix.
81

82
    Args:
83
        fovy: Field of view angle in radians
84
        aspect: Aspect ratio (width/height)
85
        near: Near clipping plane distance
86

87
    Returns:
88
        4×4 infinite perspective projection matrix (no far plane)
89
    """
90
```
91

92
### View Matrices
93

94
Functions for creating view matrices that position and orient the camera in 3D space.
95

96
```python { .api }
97
def lookAt(eye, center, up):
98
    """
99
    Create a view matrix for a camera looking at a target.
100

101
    Args:
102
        eye: Camera position (vec3)
103
        center: Target position to look at (vec3)
104
        up: Up direction vector (vec3, typically (0,1,0))
105

106
    Returns:
107
        4×4 view matrix that transforms world coordinates to camera space
108

109
    Example:
110
        view = glm.lookAt(glm.vec3(0,0,3), glm.vec3(0,0,0), glm.vec3(0,1,0))
111
    """
112

113
def lookAtRH(eye, center, up):
114
    """
115
    Create a right-handed view matrix.
116

117
    Args:
118
        eye: Camera position (vec3)
119
        center: Target position to look at (vec3)
120
        up: Up direction vector (vec3)
121

122
    Returns:
123
        4×4 right-handed view matrix
124
    """
125

126
def lookAtLH(eye, center, up):
127
    """
128
    Create a left-handed view matrix.
129

130
    Args:
131
        eye: Camera position (vec3)
132
        center: Target position to look at (vec3)
133
        up: Up direction vector (vec3)
134

135
    Returns:
136
        4×4 left-handed view matrix
137
    """
138
```
139

140
### Model Transformation
141

142
Functions for creating model transformation matrices that position, rotate, and scale objects in 3D space.
143

144
```python { .api }
145
def translate(m, v):
146
    """
147
    Create or apply a translation transformation.
148

149
    Args:
150
        m: Input matrix (typically mat4)
151
        v: Translation vector (vec3)
152

153
    Returns:
154
        Matrix with translation applied
155

156
    Example:
157
        # Translate by (1, 2, 3)
158
        translated = glm.translate(glm.mat4(), glm.vec3(1, 2, 3))
159
    """
160

161
def rotate(m, angle, axis):
162
    """
163
    Create or apply a rotation transformation.
164

165
    Args:
166
        m: Input matrix (typically mat4)
167
        angle: Rotation angle in radians
168
        axis: Rotation axis vector (vec3, should be normalized)
169

170
    Returns:
171
        Matrix with rotation applied
172

173
    Example:
174
        # Rotate 45 degrees around Z axis
175
        rotated = glm.rotate(glm.mat4(), glm.radians(45), glm.vec3(0,0,1))
176
    """
177

178
def rotateX(m, angle):
179
    """
180
    Create or apply a rotation around the X-axis.
181

182
    Args:
183
        m: Input matrix (typically mat4)
184
        angle: Rotation angle in radians
185

186
    Returns:
187
        Matrix with X-axis rotation applied
188

189
    Example:
190
        rotated = glm.rotateX(glm.mat4(), glm.radians(90))
191
    """
192

193
def rotateY(m, angle):
194
    """
195
    Create or apply a rotation around the Y-axis.
196

197
    Args:
198
        m: Input matrix (typically mat4)
199
        angle: Rotation angle in radians
200

201
    Returns:
202
        Matrix with Y-axis rotation applied
203

204
    Example:
205
        rotated = glm.rotateY(glm.mat4(), glm.radians(45))
206
    """
207

208
def rotateZ(m, angle):
209
    """
210
    Create or apply a rotation around the Z-axis.
211

212
    Args:
213
        m: Input matrix (typically mat4)
214
        angle: Rotation angle in radians
215

216
    Returns:
217
        Matrix with Z-axis rotation applied
218

219
    Example:
220
        rotated = glm.rotateZ(glm.mat4(), glm.radians(180))
221
    """
222

223
def scale(m, v):
224
    """
225
    Create or apply a scaling transformation.
226

227
    Args:
228
        m: Input matrix (typically mat4)
229
        v: Scaling factors (vec3)
230

231
    Returns:
232
        Matrix with scaling applied
233

234
    Example:
235
        # Scale by 2x in all directions
236
        scaled = glm.scale(glm.mat4(), glm.vec3(2, 2, 2))
237
    """
238
```
239

240
### Specialized Transformations
241

242
Additional transformation functions for specific graphics applications.
243

244
```python { .api }
245
def shearX(m, y, z):
246
    """
247
    Apply shear transformation along X axis.
248

249
    Args:
250
        m: Input matrix
251
        y: Shear factor for Y component
252
        z: Shear factor for Z component
253

254
    Returns:
255
        Matrix with X-axis shear applied
256
    """
257

258
def shearY(m, x, z):
259
    """
260
    Apply shear transformation along Y axis.
261

262
    Args:
263
        m: Input matrix
264
        x: Shear factor for X component
265
        z: Shear factor for Z component
266

267
    Returns:
268
        Matrix with Y-axis shear applied
269
    """
270

271
def shearZ(m, x, y):
272
    """
273
    Apply shear transformation along Z axis.
274

275
    Args:
276
        m: Input matrix
277
        x: Shear factor for X component
278
        y: Shear factor for Y component
279

280
    Returns:
281
        Matrix with Z-axis shear applied
282
    """
283
```
284

285
### Coordinate System Variants
286

287
PyGLM provides variants for different coordinate systems and clipping conventions.
288

289
```python { .api }
290
# Left-handed vs Right-handed coordinate systems
291
def perspectiveLH(fovy, aspect, near, far): ...  # Left-handed perspective
292
def perspectiveRH(fovy, aspect, near, far): ...  # Right-handed perspective
293

294
def orthoLH(left, right, bottom, top, near, far): ...  # Left-handed orthographic
295
def orthoRH(left, right, bottom, top, near, far): ...  # Right-handed orthographic
296

297
# Zero-to-one vs Negative-one-to-one depth range
298
def perspectiveZO(fovy, aspect, near, far): ...  # Zero to one depth
299
def perspectiveNO(fovy, aspect, near, far): ...  # Negative one to one depth
300

301
def orthoZO(left, right, bottom, top, near, far): ...  # Zero to one depth
302
def orthoNO(left, right, bottom, top, near, far): ...  # Negative one to one depth
303

304
# Combined variants (e.g., left-handed with zero-to-one depth)
305
def perspectiveLH_ZO(fovy, aspect, near, far): ...
306
def perspectiveLH_NO(fovy, aspect, near, far): ...
307
def perspectiveRH_ZO(fovy, aspect, near, far): ...
308
def perspectiveRH_NO(fovy, aspect, near, far): ...
309
```
310

311
### Usage Examples
312

313
```python
314
from pyglm import glm
315
import math
316

317
# === Projection Matrix Examples ===
318

319
# Perspective projection for 3D scene
320
fov = glm.radians(45.0)  # 45 degree field of view
321
aspect_ratio = 1920.0 / 1080.0  # 16:9 aspect ratio
322
near_plane = 0.1
323
far_plane = 100.0
324

325
perspective_matrix = glm.perspective(fov, aspect_ratio, near_plane, far_plane)
326

327
# Orthographic projection for 2D UI or technical drawings
328
ortho_matrix = glm.ortho(-10.0, 10.0, -10.0, 10.0, -1.0, 1.0)
329

330
# === View Matrix Examples ===
331

332
# First-person camera
333
camera_pos = glm.vec3(0.0, 2.0, 5.0)
334
target_pos = glm.vec3(0.0, 0.0, 0.0)
335
up_vector = glm.vec3(0.0, 1.0, 0.0)
336

337
view_matrix = glm.lookAt(camera_pos, target_pos, up_vector)
338

339
# Orbiting camera (rotating around target)
340
angle = math.radians(45)  # Python's math.radians
341
radius = 10.0
342
orbit_x = radius * math.cos(angle)
343
orbit_z = radius * math.sin(angle)
344
orbit_pos = glm.vec3(orbit_x, 5.0, orbit_z)
345

346
orbit_view = glm.lookAt(orbit_pos, glm.vec3(0, 0, 0), glm.vec3(0, 1, 0))
347

348
# === Model Transformation Examples ===
349

350
# Simple object transformation
351
model_matrix = glm.mat4()  # Start with identity
352

353
# Apply transformations in order: Scale -> Rotate -> Translate
354
model_matrix = glm.scale(model_matrix, glm.vec3(2.0, 2.0, 2.0))  # Scale 2x
355
model_matrix = glm.rotate(model_matrix, glm.radians(45), glm.vec3(0, 1, 0))  # Rotate around Y
356
model_matrix = glm.translate(model_matrix, glm.vec3(5, 0, 0))  # Move right
357

358
# Complex transformation chain
359
transform = glm.mat4()
360
transform = glm.translate(transform, glm.vec3(1, 2, 3))  # Position
361
transform = glm.rotate(transform, glm.radians(30), glm.vec3(1, 0, 0))  # Pitch
362
transform = glm.rotate(transform, glm.radians(45), glm.vec3(0, 1, 0))  # Yaw
363
transform = glm.rotate(transform, glm.radians(60), glm.vec3(0, 0, 1))  # Roll
364
transform = glm.scale(transform, glm.vec3(0.5, 2.0, 1.0))  # Non-uniform scale
365

366
# === Complete Graphics Pipeline ===
367

368
# Model-View-Projection matrix for rendering
369
model = glm.mat4()
370
model = glm.translate(model, glm.vec3(0, 0, -5))
371
model = glm.rotate(model, glm.radians(45), glm.vec3(1, 1, 0))
372

373
view = glm.lookAt(
374
    glm.vec3(0, 0, 3),    # Camera position
375
    glm.vec3(0, 0, 0),    # Look at origin
376
    glm.vec3(0, 1, 0)     # Up vector
377
)
378

379
projection = glm.perspective(
380
    glm.radians(45.0),    # FOV
381
    16.0/9.0,            # Aspect ratio
382
    0.1,                 # Near plane
383
    100.0                # Far plane
384
)
385

386
# Combined transformation (applied right to left: Model -> View -> Projection)
387
mvp_matrix = projection * view * model
388

389
# Transform vertex positions
390
vertex_position = glm.vec4(1.0, 1.0, 1.0, 1.0)  # Homogeneous coordinates
391
transformed_vertex = mvp_matrix * vertex_position
392

393
# === Coordinate System Specific Examples ===
394

395
# OpenGL (right-handed, -1 to 1 depth)
396
opengl_proj = glm.perspectiveRH_NO(glm.radians(45), 16.0/9.0, 0.1, 100.0)
397

398
# DirectX (left-handed, 0 to 1 depth)  
399
directx_proj = glm.perspectiveLH_ZO(glm.radians(45), 16.0/9.0, 0.1, 100.0)
400

401
# Vulkan (right-handed, 0 to 1 depth)
402
vulkan_proj = glm.perspectiveRH_ZO(glm.radians(45), 16.0/9.0, 0.1, 100.0)
403
```
404

405
### Transformation Order
406

407
**Important**: Matrix transformations are applied in reverse order of multiplication:
408

409
```python
410
# This code:
411
result = glm.translate(glm.mat4(), glm.vec3(5, 0, 0))
412
result = glm.rotate(result, glm.radians(45), glm.vec3(0, 1, 0))
413
result = glm.scale(result, glm.vec3(2, 2, 2))
414

415
# Applies transformations in the order: Scale -> Rotate -> Translate
416
# (The last transformation applied is the first to affect the vertex)
417
```
418

419
For predictable results, build transformation matrices step by step and be mindful of the order of operations based on your intended transformation sequence.