0
# Vector Operations
1

2
Comprehensive vector mathematics providing all the fundamental operations needed for graphics programming, physics simulations, and scientific computing. PyGLM supports vectors from 1 to 4 components in multiple precisions and data types.
3

4
## Capabilities
5

6
### Vector Types
7

8
PyGLM provides a complete set of vector types covering all common use cases in graphics and scientific computing.
9

10
```python { .api }
11
# Boolean vectors
12
class bvec1:
13
    x: bool
14
    def __init__(self, x: bool = False): ...
15

16
class bvec2:
17
    x: bool
18
    y: bool
19
    def __init__(self, x: bool = False, y: bool = False): ...
20

21
class bvec3:
22
    x: bool
23
    y: bool
24
    z: bool
25
    def __init__(self, x: bool = False, y: bool = False, z: bool = False): ...
26

27
class bvec4:
28
    x: bool
29
    y: bool
30
    z: bool
31
    w: bool
32
    def __init__(self, x: bool = False, y: bool = False, z: bool = False, w: bool = False): ...
33

34
# Float32 vectors (default precision)
35
class vec1:
36
    x: float
37
    def __init__(self, x: float = 0.0): ...
38

39
class vec2:
40
    x: float
41
    y: float
42
    def __init__(self, x: float = 0.0, y: float = 0.0): ...
43

44
class vec3:
45
    x: float
46
    y: float
47
    z: float
48
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0): ...
49

50
class vec4:
51
    x: float
52
    y: float
53
    z: float
54
    w: float
55
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 0.0): ...
56

57
# Double precision vectors
58
class dvec1:
59
    x: float
60
    def __init__(self, x: float = 0.0): ...
61

62
class dvec2:
63
    x: float
64
    y: float
65
    def __init__(self, x: float = 0.0, y: float = 0.0): ...
66

67
class dvec3:
68
    x: float
69
    y: float
70
    z: float
71
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0): ...
72

73
class dvec4:
74
    x: float
75
    y: float
76
    z: float
77
    w: float
78
    def __init__(self, x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 0.0): ...
79

80
# Signed integer vectors (32-bit)
81
class ivec1:
82
    x: int
83
    def __init__(self, x: int = 0): ...
84

85
class ivec2:
86
    x: int
87
    y: int
88
    def __init__(self, x: int = 0, y: int = 0): ...
89

90
class ivec3:
91
    x: int
92
    y: int
93
    z: int
94
    def __init__(self, x: int = 0, y: int = 0, z: int = 0): ...
95

96
class ivec4:
97
    x: int
98
    y: int
99
    z: int
100
    w: int
101
    def __init__(self, x: int = 0, y: int = 0, z: int = 0, w: int = 0): ...
102

103
# Unsigned integer vectors (32-bit)
104
class uvec1:
105
    x: int
106
    def __init__(self, x: int = 0): ...
107

108
class uvec2:
109
    x: int
110
    y: int
111
    def __init__(self, x: int = 0, y: int = 0): ...
112

113
class uvec3:
114
    x: int
115
    y: int
116
    z: int
117
    def __init__(self, x: int = 0, y: int = 0, z: int = 0): ...
118

119
class uvec4:
120
    x: int
121
    y: int
122
    z: int
123
    w: int
124
    def __init__(self, x: int = 0, y: int = 0, z: int = 0, w: int = 0): ...
125
```
126

127
# Additional Integer Precision Vectors
128
class i8vec1: ...   # 8-bit signed integer vectors
129
class i8vec2: ...
130
class i8vec3: ...
131
class i8vec4: ...
132

133
class i16vec1: ...  # 16-bit signed integer vectors
134
class i16vec2: ...
135
class i16vec3: ...
136
class i16vec4: ...
137

138
class i64vec1: ...  # 64-bit signed integer vectors
139
class i64vec2: ...
140
class i64vec3: ...
141
class i64vec4: ...
142

143
class u8vec1: ...   # 8-bit unsigned integer vectors
144
class u8vec2: ...
145
class u8vec3: ...
146
class u8vec4: ...
147

148
class u16vec1: ...  # 16-bit unsigned integer vectors
149
class u16vec2: ...
150
class u16vec3: ...
151
class u16vec4: ...
152

153
class u64vec1: ...  # 64-bit unsigned integer vectors
154
class u64vec2: ...
155
class u64vec3: ...
156
class u64vec4: ...
157

158
# Mixed vectors for SSE optimization
159
class mvec2: ...    # 32-bit float mixed vectors
160
class mvec3: ...
161
class mvec4: ...
162

163
class dmvec2: ...   # Double precision mixed vectors
164
class dmvec3: ...
165
class dmvec4: ...
166

167
class imvec2: ...   # 32-bit integer mixed vectors
168
class imvec3: ...
169
class imvec4: ...
170

171
class umvec2: ...   # 32-bit unsigned mixed vectors
172
class umvec3: ...
173
class umvec4: ...
174
```
175
176
**Type Aliases**: PyGLM provides convenient aliases for common vector types:
177
- `f32vec*` = `fvec*` = `vec*` - 32-bit float vectors
178
- `f64vec*` = `dvec*` - 64-bit double vectors  
179
- `i32vec*` = `ivec*` - 32-bit signed integer vectors
180
- `u32vec*` = `uvec*` - 32-bit unsigned integer vectors
181

182
### Geometric Operations
183

184
Essential geometric operations for graphics programming including dot products, cross products, normalization, and distance calculations.
185

186
```python { .api }
187
def dot(x, y):
188
    """
189
    Calculate the dot product of two vectors.
190

191
    Args:
192
        x: Vector of any type and dimension
193
        y: Vector of same type and dimension as x
194

195
    Returns:
196
        Scalar value representing the dot product
197
    """
198

199
def cross(x, y):
200
    """
201
    Calculate the cross product of two 3D vectors.
202

203
    Args:
204
        x: 3-component vector 
205
        y: 3-component vector of same type
206

207
    Returns:
208
        3-component vector perpendicular to both input vectors
209
    """
210

211
def normalize(x):
212
    """
213
    Normalize a vector to unit length.
214

215
    Args:
216
        x: Vector of any type and dimension
217

218
    Returns:
219
        Vector of same type with length = 1.0
220
    """
221

222
def length(x):
223
    """
224
    Calculate the Euclidean length of a vector.
225

226
    Args:
227
        x: Vector of any type and dimension
228

229
    Returns:
230
        Scalar representing the vector's magnitude
231
    """
232

233
def distance(p0, p1):
234
    """
235
    Calculate the distance between two points.
236

237
    Args:
238
        p0: First point as vector
239
        p1: Second point as vector of same type
240

241
    Returns:
242
        Scalar distance between the points
243
    """
244

245
def faceforward(N, I, Nref):
246
    """
247
    Orient a vector to point away from a surface.
248

249
    Args:
250
        N: Vector to orient
251
        I: Incident vector  
252
        Nref: Reference vector
253

254
    Returns:
255
        N if dot(Nref, I) < 0, else -N
256
    """
257

258
def reflect(I, N):
259
    """
260
    Calculate the reflection direction for an incident vector.
261

262
    Args:
263
        I: Incident vector
264
        N: Normal vector (should be normalized)
265

266
    Returns:
267
        Reflection vector
268
    """
269

270
def refract(I, N, eta):
271
    """
272
    Calculate the refraction direction for an incident vector.
273

274
    Args:
275
        I: Incident vector (should be normalized)
276
        N: Normal vector (should be normalized)  
277
        eta: Ratio of indices of refraction
278

279
    Returns:
280
        Refraction vector, or zero vector for total internal reflection
281
    """
282
```
283

284
### Vector Comparison Functions
285

286
Component-wise comparison operations that return boolean vectors for element-wise testing.
287

288
```python { .api }
289
def lessThan(x, y):
290
    """
291
    Component-wise less than comparison.
292

293
    Args:
294
        x: First vector
295
        y: Second vector of same type
296

297
    Returns:
298
        Boolean vector where each component is True if x[i] < y[i]
299
    """
300

301
def lessThanEqual(x, y):
302
    """
303
    Component-wise less than or equal comparison.
304

305
    Args:
306
        x: First vector
307
        y: Second vector of same type
308

309
    Returns:
310
        Boolean vector where each component is True if x[i] <= y[i]
311
    """
312

313
def greaterThan(x, y):
314
    """
315
    Component-wise greater than comparison.
316

317
    Args:
318
        x: First vector
319
        y: Second vector of same type
320

321
    Returns:
322
        Boolean vector where each component is True if x[i] > y[i]
323
    """
324

325
def greaterThanEqual(x, y):
326
    """
327
    Component-wise greater than or equal comparison.
328

329
    Args:
330
        x: First vector
331
        y: Second vector of same type
332

333
    Returns:
334
        Boolean vector where each component is True if x[i] >= y[i]
335
    """
336

337
def equal(x, y):
338
    """
339
    Component-wise equality comparison.
340

341
    Args:
342
        x: First vector
343
        y: Second vector of same type
344

345
    Returns:
346
        Boolean vector where each component is True if x[i] == y[i]
347
    """
348

349
def notEqual(x, y):
350
    """
351
    Component-wise inequality comparison.
352

353
    Args:
354
        x: First vector
355
        y: Second vector of same type
356

357
    Returns:
358
        Boolean vector where each component is True if x[i] != y[i]
359
    """
360
```
361

362
### Boolean Vector Operations
363

364
Logical operations for boolean vectors including any, all, and component-wise NOT operations.
365

366
```python { .api }
367
def any(x):
368
    """
369
    Test if any component of a boolean vector is True.
370

371
    Args:
372
        x: Boolean vector of any dimension
373

374
    Returns:
375
        True if any component is True, False otherwise
376
    """
377

378
def all(x):
379
    """
380
    Test if all components of a boolean vector are True.
381

382
    Args:
383
        x: Boolean vector of any dimension
384

385
    Returns:
386
        True if all components are True, False otherwise
387
    """
388

389
def not_(x):
390
    """
391
    Component-wise logical NOT operation.
392

393
    Args:
394
        x: Boolean vector of any dimension
395

396
    Returns:
397
        Boolean vector with each component logically inverted
398
    """
399
```
400

401
### Vector Interpolation
402

403
Linear and smooth interpolation functions for blending between vectors and creating smooth transitions.
404

405
```python { .api }
406
def mix(x, y, a):
407
    """
408
    Linear interpolation between two vectors.
409

410
    Args:
411
        x: First vector
412
        y: Second vector of same type
413
        a: Interpolation factor (0.0 returns x, 1.0 returns y)
414

415
    Returns:
416
        Interpolated vector: x * (1-a) + y * a
417
    """
418

419
def smoothstep(edge0, edge1, x):
420
    """
421
    Smooth Hermite interpolation with smooth transitions.
422

423
    Args:
424
        edge0: Lower edge of interpolation range
425
        edge1: Upper edge of interpolation range
426
        x: Vector to interpolate
427

428
    Returns:
429
        Vector with smooth interpolation applied component-wise
430
    """
431

432
def step(edge, x):
433
    """
434
    Step function returning 0.0 or 1.0 based on comparison.
435

436
    Args:
437
        edge: Threshold value
438
        x: Vector to compare
439

440
    Returns:
441
        Vector where each component is 0.0 if x[i] < edge, 1.0 otherwise
442
    """
443
```
444

445
### Vector Arithmetic
446

447
All vector types support standard arithmetic operations through operator overloading:
448

449
- **Addition**: `v1 + v2` - Component-wise addition
450
- **Subtraction**: `v1 - v2` - Component-wise subtraction  
451
- **Multiplication**: `v * scalar` or `v1 * v2` - Scalar or component-wise multiplication
452
- **Division**: `v / scalar` or `v1 / v2` - Scalar or component-wise division
453
- **Negation**: `-v` - Component-wise negation
454
- **Indexing**: `v[i]` - Access individual components
455
- **Length**: `len(v)` - Number of components
456

457
### Usage Examples
458

459
```python
460
from pyglm import glm
461

462
# Vector creation and basic operations
463
v1 = glm.vec3(1.0, 2.0, 3.0)
464
v2 = glm.vec3(4.0, 5.0, 6.0)
465
v3 = v1 + v2  # vec3(5.0, 7.0, 9.0)
466

467
# Geometric operations
468
cross_prod = glm.cross(v1, v2)  # Cross product
469
dot_prod = glm.dot(v1, v2)      # Dot product (32.0)
470
unit_v1 = glm.normalize(v1)     # Unit vector in direction of v1
471
dist = glm.distance(v1, v2)     # Distance between points
472

473
# Vector comparisons
474
comparison = glm.lessThan(v1, v2)  # bvec3(True, True, True)
475
any_less = glm.any(comparison)     # True
476
all_less = glm.all(comparison)     # True
477

478
# Interpolation
479
midpoint = glm.mix(v1, v2, 0.5)   # Halfway between v1 and v2
480
smooth = glm.smoothstep(glm.vec3(0), glm.vec3(10), v1)
481

482
# Integer vectors for array indices or discrete calculations
483
indices = glm.ivec3(0, 1, 2)
484
colors = glm.uvec4(255, 128, 64, 255)  # RGBA color
485

486
# Boolean vectors for masking
487
mask = glm.bvec3(True, False, True)
488
```