0
# PyGLM
1

2
OpenGL Mathematics (GLM) library for Python providing comprehensive vector and matrix manipulation capabilities specifically designed for graphics programming, 3D graphics applications, and physics computations. PyGLM is a Python extension written in C++ that brings the power of the OpenGL Mathematics library to Python with GLSL-compatible operations and high performance.
3

4
## Package Information
5

6
- **Package Name**: pyglm
7
- **Language**: Python
8
- **Installation**: `pip install pyglm`
9
- **Documentation**: https://github.com/Zuzu-Typ/PyGLM/wiki
10
- **License**: zlib/libpng
11

12
## Core Imports
13

14
```python
15
from pyglm import glm
16
```
17

18
Typing support (optional):
19

20
```python
21
from pyglm import glm_typing
22
```
23

24
## Basic Usage
25

26
```python
27
from pyglm import glm
28

29
# Create 3D vectors
30
v1 = glm.vec3(1, 2, 3)
31
v2 = glm.vec3(4, 5, 6)
32

33
# Vector operations
34
v3 = v1 + v2  # Vector addition
35
cross_product = glm.cross(v1, v2)  # Cross product
36
dot_product = glm.dot(v1, v2)  # Dot product
37
normalized = glm.normalize(v1)  # Normalize vector
38

39
# Create 4x4 identity matrix
40
matrix = glm.mat4()
41

42
# Transformation matrices
43
angle = glm.radians(45)  # Convert degrees to radians
44
rotation_matrix = glm.rotate(matrix, angle, glm.vec3(0, 0, 1))
45
translation_matrix = glm.translate(matrix, glm.vec3(1, 2, 3))
46
scaling_matrix = glm.scale(matrix, glm.vec3(2, 2, 2))
47

48
# Quaternions for rotations
49
axis = glm.vec3(0, 0, 1)
50
angle = glm.radians(45)
51
quat = glm.angleAxis(angle, axis)
52
quat_matrix = glm.mat4_cast(quat)
53

54
# Projection matrices for 3D graphics
55
projection = glm.perspective(glm.radians(45), 16.0/9.0, 0.1, 100.0)
56
view = glm.lookAt(glm.vec3(0, 0, 3), glm.vec3(0, 0, 0), glm.vec3(0, 1, 0))
57
```
58

59
## Architecture
60

61
PyGLM provides a comprehensive linear algebra library structured around several key components:
62

63
- **Vector Types**: Comprehensive collection of vectors with different precisions and component counts (1-4 components) for boolean, integer (signed/unsigned), and floating-point (32/64-bit) data
64
- **Matrix Types**: Full range of matrices from 2×2 to 4×4 in various precisions, supporting both row-major and column-major operations
65
- **Quaternions**: Efficient 3D rotation representation with seamless matrix conversion
66
- **Mathematical Functions**: Complete GLSL-compatible function library covering trigonometry, exponentials, interpolation, and geometric operations
67
- **Transformation System**: High-level functions for creating projection, view, and model transformation matrices common in 3D graphics
68
- **Type System**: Extensive type aliases and polymorphic function support for flexible usage patterns
69

70
The library maintains compatibility with OpenGL's GLSL shader language while providing Python-friendly interfaces including operator overloading, buffer protocol support, and seamless integration with numpy arrays.
71

72
## Capabilities
73

74
### Vector Operations
75

76
Comprehensive vector mathematics including creation, arithmetic, geometric operations, and comparison functions. Supports vectors from 1 to 4 components in multiple precisions (boolean, 8/16/32/64-bit integers, 32/64-bit floats).
77

78
```python { .api }
79
# Vector types (examples - full list includes all precision variants)
80
class vec1: ...
81
class vec2: ...  
82
class vec3: ...
83
class vec4: ...
84
class dvec2: ...  # Double precision
85
class ivec3: ...  # Integer
86
class uvec4: ...  # Unsigned integer
87
class bvec2: ...  # Boolean
88

89
# Geometric operations
90
def dot(x, y): ...
91
def cross(x, y): ...  
92
def normalize(x): ...
93
def length(x): ...
94
def distance(x, y): ...
95
def reflect(I, N): ...
96
def refract(I, N, eta): ...
97
```
98

99
[Vector Operations](./vectors.md)
100

101
### Matrix Operations
102

103
Complete matrix mathematics including creation, arithmetic, linear algebra operations, and transformation utilities. Supports matrices from 2×2 to 4×4 in multiple precisions.
104

105
```python { .api }
106
# Matrix types (examples - full list includes all precision variants)
107
class mat2: ...    # 2×2 matrix
108
class mat3: ...    # 3×3 matrix  
109
class mat4: ...    # 4×4 matrix
110
class dmat3: ...   # Double precision 3×3
111
class imat4x3: ... # Integer 4×3 matrix
112

113
# Matrix operations
114
def transpose(m): ...
115
def inverse(m): ...
116
def determinant(m): ...
117
def matrixCompMult(x, y): ...
118
def outerProduct(c, r): ...
119
```
120

121
[Matrix Operations](./matrices.md)
122

123
### Transformation Functions
124

125
High-level transformation matrix creation for 3D graphics including projection, view, and model transformations. Essential for OpenGL and DirectX applications.
126

127
```python { .api }
128
# Projection matrices
129
def perspective(fovy, aspect, near, far): ...
130
def perspectiveFov(fov, width, height, near, far): ...
131
def ortho(left, right, bottom, top, near, far): ...
132
def frustum(left, right, bottom, top, near, far): ...
133

134
# View matrices  
135
def lookAt(eye, center, up): ...
136
def lookAtLH(eye, center, up): ...
137
def lookAtRH(eye, center, up): ...
138

139
# Model transformations
140
def translate(m, v): ...
141
def rotate(m, angle, axis): ...
142
def scale(m, v): ...
143
```
144

145
[Transformations](./transformations.md)
146

147
### Quaternion Operations
148

149
Efficient 3D rotation representation with comprehensive quaternion mathematics, conversions, and interpolation functions.
150

151
```python { .api }
152
# Quaternion types
153
class quat: ...   # Float precision
154
class dquat: ...  # Double precision
155

156
# Quaternion operations
157
def angleAxis(angle, axis): ...
158
def slerp(x, y, a): ...
159
def conjugate(q): ...
160
def mat4_cast(q): ...
161
def quat_cast(m): ...
162
def eulerAngles(q): ...
163
```
164

165
[Quaternions](./quaternions.md)
166

167
### Mathematical Functions
168

169
Complete GLSL-compatible mathematical function library covering trigonometry, exponentials, common functions, and interpolation with support for both scalar and vector inputs.
170

171
```python { .api }
172
# Basic math functions
173
def abs(x): ...
174
def min(x, y): ...
175
def max(x, y): ...
176
def clamp(x, minVal, maxVal): ...
177
def mix(x, y, a): ...
178
def smoothstep(edge0, edge1, x): ...
179

180
# Trigonometric functions
181
def sin(angle): ...
182
def cos(angle): ...  
183
def tan(angle): ...
184
def radians(degrees): ...
185
def degrees(radians): ...
186

187
# Exponential functions
188
def pow(x, y): ...
189
def exp(x): ...
190
def log(x): ...
191
def sqrt(x): ...
192
```
193

194
[Mathematical Functions](./math-functions.md)
195

196
### Random and Noise Functions
197

198
Random number generation and noise functions for procedural content generation and simulation applications.
199

200
```python { .api }
201
def linearRand(min, max): ...
202
def gaussRand(mean, deviation): ...
203
def circularRand(radius): ...
204
def sphericalRand(radius): ...
205
def perlin(p): ...
206
def simplex(p): ...
207
```
208

209
[Random and Noise](./random-noise.md)
210

211
### Utility and Conversion Functions
212

213
Type conversion, memory access, testing utilities, and packing/unpacking functions for interfacing with graphics APIs and external libraries.
214

215
```python { .api }
216
def value_ptr(x): ...
217
def sizeof(type): ...
218
def make_vec3(ptr): ...
219
def packHalf2x16(v): ...
220
def unpackHalf2x16(p): ...
221
def floatBitsToInt(value): ...
222
def isinf(x): ...
223
def isnan(x): ...
224
```
225

226
[Utilities](./utilities.md)
227

228
### Extension Functions
229

230
Advanced mathematical and utility functions that extend PyGLM's core capabilities with specialized algorithms for graphics programming, procedural generation, and scientific computing.
231

232
```python { .api }
233
# Color space conversion
234
def convertLinearToSRGB(color): ...
235
def convertSRGBToLinear(color): ...
236

237
# Rounding extensions  
238
def ceilMultiple(value, multiple): ...
239
def ceilPowerOfTwo(value): ...
240
def floorPowerOfTwo(value): ...
241

242
# Norm functions
243
def l1Norm(vec): ...
244
def l2Norm(vec): ...
245
def lMaxNorm(vec): ...
246

247
# Coordinate conversion
248
def euclidean(polar): ...
249
def polar(euclidean): ...
250

251
# Projection functions
252
def project(obj, model, proj, viewport): ...
253
def unProject(win, model, proj, viewport): ...
254

255
# Euler angles
256
def euler(angles): ...
257
def eulerAngles(quat): ...
258
```
259

260
[Extension Functions](./extensions.md)
261

262
## Types
263

264
### Core Types
265

266
```python { .api }
267
# Scalar type aliases
268
bool_ = ctypes.c_bool
269
int8 = ctypes.c_byte
270
int16 = ctypes.c_short  
271
int32 = ctypes.c_long
272
int64 = ctypes.c_longlong
273
uint8 = ctypes.c_ubyte
274
uint16 = ctypes.c_ushort
275
uint32 = ctypes.c_ulong
276
uint64 = ctypes.c_ulonglong
277
float32 = ctypes.c_float
278
float64 = ctypes.c_double
279
```
280

281
All vector, matrix, and quaternion types support:
282
- Multiple constructor overloads for flexible initialization
283
- Array-style indexing with `[i]` access and assignment
284
- Python iteration protocol with `for` loops
285
- Complete arithmetic operator overloading (`+`, `-`, `*`, `/`, etc.)
286
- Comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=`)
287
- Built-in functions (`len()`, `abs()`, etc.)
288
- Buffer protocol support for numpy integration
289
- Conversion methods (`to_list()`, `to_tuple()`, `to_bytes()`)
290

291
## Constants
292

293
```python { .api }
294
# Mathematical constants
295
e = 2.71828...           # Euler's number
296
euler = 2.71828...       # Alias for e
297
pi = 3.14159...          # Pi
298
half_pi = 1.57079...     # π/2
299
quarter_pi = 0.78539...  # π/4
300
two_pi = 6.28318...      # 2π
301
three_over_two_pi = 4.71238... # 3π/2
302
one_over_pi = 0.31830...  # 1/π
303
two_over_pi = 0.63661...  # 2/π
304
four_over_pi = 1.27323... # 4/π
305
one_over_two_pi = 0.15915... # 1/(2π)
306

307
# Root constants
308
root_two = 1.41421...    # √2
309
root_three = 1.73205... # √3
310
root_five = 2.23606...  # √5
311
root_pi = 1.77245...    # √π
312
root_half_pi = 1.25331... # √(π/2)
313
root_ln_four = 1.32934... # √(ln(4))
314
root_two_pi = 2.50662...  # √(2π)
315
one_over_root_two = 0.70710... # 1/√2
316
two_over_root_pi = 1.12837...  # 2/√π
317

318
# Logarithmic constants
319
ln_two = 0.69314...      # ln(2)
320
ln_ten = 2.30258...      # ln(10)
321
ln_ln_two = -0.36651...  # ln(ln(2))
322

323
# Other mathematical constants
324
golden_ratio = 1.61803... # φ (golden ratio)
325
epsilon = 1.19209e-07    # Machine epsilon
326
zero = 0.0               # Zero constant
327
one = 1.0                # One constant
328
third = 0.33333...       # 1/3
329
two_thirds = 0.66666...  # 2/3
330
```