GLM offers a set of objects and functions to ease the design of 3D applications while taking advantage of the numpy library. The main objects are vectors (vec2, vec3, vec4), matrices (mat2, mat3, mat4) and vectorized lists (vlist). Vectors and matrices possess several variants depending on the base type (see below) and are memory tracked. This means it is possible to know anytime the smallest contiguous block of memory that has changed. This can be used to maintain a GPU copy up-to-date.
This is the code to get the 3D bunny display on the top-right corner. You'll need meshio to read the mesh file and matplotlib to display it.
import glm
import numpy as np
# Read mesh, get vertices (vec3) and face indices (int)
import meshio
mesh = meshio.read("bunny.obj")
vertices, indices = mesh.points, mesh.cells[0].data
# Transform: Model / View / Projection matrix (MVP)
MVP = glm.perspective(25, 1, 1, 100) @ glm.translate(0.1, -0.45, -2.5)
MVP = MVP @ glm.xrotate(20) @ glm.yrotate(45) @ glm.scale(5)
# Apply transform
vertices = glm.to_vec3(glm.to_vec4(vertices) @ M.T)
# Generate faces and sort them
faces = vertices[indices]
faces = faces[np.argsort(-faces[...,2].mean(axis=1))]
# Render faces using matplotlib
import matplotlib.pyplot as plt
from matplotlib.collections import PolyCollection
fig = plt.figure(figsize=(6,6))
ax = fig.add_axes([0,0,1,1], aspect=1, frameon=False, xlim=[-1,+1], ylim=[-1,+1])
ax.add_collection(PolyCollection(faces[...,:2], alpha=0.85, linewidth = 0.5,
facecolor="white", edgecolor="black"))
plt.show()The generic notation is:
TvecNfor vectorsTmatNfor matrices,
with T in [b, i , u, h, d, f, Ø] and N in [2,3,4].
| Symbol | Type | Size | Dtype |
|---|---|---|---|
b |
unsigned integer | 8 bits | np.uint8 |
i |
signed integer | 32 bits | np.int32 |
u |
unsigned integer | 32 bits | np.uint32 |
h |
float | 16 bits | np.float16 |
| Ø | float | 32 bits | np.float32 |
h |
float | 64 bits | np.float64 |
import glm
# 10 x 3-components vectors of integers (32 bits)
V = glm.ivec3(10)
V.xyz = 1,2,3
# 10 x 3-components vectors of float (32 bits)
V = glm.vec3(10)
# Conversion from vec3 to vec4 (w set to 1)
V = glm.vec4(V)
# Conversion from vec4 to vec3 (xyz divided by w)
V = glm.vec3(V)
# A 4x4 matrix of floats (32 bits)
M = glm.mat4()
M.xyzw = 1,2,3,1Vectorized lists (vlist) correspond to ragged arrays where items have the same type but different lengths. There are three way to declare a vectorized list.
import glm
# A list of 3 groups of vectors with size 3,3,4
V = glm.vlist([glm.vec4(3), glm.vec4(3), glm.vec4(3)])
# A list of 3 groups of vectors with size 3,3,4
V = glm.vlist(glm.vec4(10), [3,3,4])
# A list of 5 groups of vectors with size 2
V = glm.vlist(glm.vec4(10), 2)
# Display each item
for v in V: print(v)The underlying structure is a regular numpy array (vlist.data).
-
glm.viewport(x, y, width, height, dtype=np.float32, transpose=False)
Return a 4x4 matrix that transforms normalized device coordinates to window coordinates.
Parameters Type Description xfloat Viewport x origin (lower left) yfloat Viewport x origin (lower left) widthfloat Viewport width heightfloat Viewport height dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.ortho(left, right, bottom, top, znear, zfar, dtype=np.float32, transpose=False)
Return a 4x4 matrix that produces a parallel projection.
Parameters Type Description leftfloat Left clipping plane rightfloat Right clipping plane bottomfloat Bottom clipping plane topfloat Top clipping plane znearfloat Near clipping plane zfarfloat Far clipping plane dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.frustum(left, right, bottom, top, znear, zfar, dtype=np.float32, transpose=False)
Return a 4x4 matrix that produces a perspective projection.
Parameters Type Description leftfloat Left clipping plane rightfloat Right clipping plane bottomfloat Bottom clipping plane topfloat Top clipping plane znearfloat Near clipping plane zfarfloat Far clipping plane dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.perpective(fovy, aspect, znear, zfar, dtype=np.float32, transpose=False)
Return a 4x4 matrix corresponding to a viewing frustum into the world coordinate system. In general, the aspect ratio in perspective should match the aspect ratio of the associated viewport. For example, aspect = 2.0 means the viewer's angle of view is twice as wide in x as it is in y. If the viewport is twice as wide as it is tall, it displays the image without distortion.
Parameters Type Description fovyfloat Field of view angle (degrees in the y direction aspectfloat Aspect ratio that determines the field of view in the x direction znearfloat Near clipping plane zfarfloat Far clipping plane dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.scale(x, y, z, dtype=np.float32, transpose=False)
Return a 4x4 matrix for nonuniform scaling along the x, y, and z axes. The three parameters indicate the desired scale factor along each of the three axes.
Parameters Type Description xfloat x scale factor yfloat y scale factor zfloat z scale factor dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.fit(V)
Return vertices fitted to the normalized cube.
Parameters Type Description VvecN Vertices to fit -
glm.rotate(angle, x, y, z, dtype=np.float32, transpose=False)
Return a 4x4 matrix for a rotation of angle degrees around the vector (x,y,z).
Parameters Type Description anglefloat angle in degrees xfloat x scale factor yfloat y scale factor zfloat z scale factor dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.xrotate(angle, dtype=np.float32, transpose=False)
Return a 4x4 matrix for a rotation of angle degrees around the x axis
Parameters Type Description anglefloat angle in degrees dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.yrotate(angle, dtype=np.float32, transpose=False)
Return a 4x4 matrix for a rotation of angle degrees around the y axis
Parameters Type Description anglefloat angle in degrees dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.zrotate(angle, dtype=np.float32, transpose=False)
Return a 4x4 matrix for a rotation of angle degrees around the z axis
Parameters Type Description anglefloat angle in degrees dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.align(U, V, dtype=np.float32, transpose=False)
Return the rotation matrix M that aligns U to V such that V = U @ M.T
Parameters Type Description UvecN First vector VvecN Second vector dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.translate(x, y, z, dtype=np.float32, transpose=False)
Return a 4x4 matrix for a translation by (x,y,z).
Parameters Type Description xfloat x scale factor yfloat y scale factor zfloat z scale factor dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.center(V)
Return vertices centered aroung the origin
Parameters Type Description VvecN Vectices to center -
glm.lookat(eye, center, up, dtype=np.float32, transpose=False)
Return a 4x4 a viewing matrix derived from an eye point, a reference point indicating the center of the scene, and an UP vector.
The matrix maps the reference point to the negative z axis and the eye point to the origin. When a typical projection matrix is used, the center of the scene therefore maps to the center of the viewport. Similarly, the direction described by the UP vector projected onto the viewing plane is mapped to the positive y axis so that it points upward in the viewport. The UP vector must not be parallel to the line of sight from the eye point to the reference point.
Parameters Type Description eyevec3 Eye position centervec3 Reference point upvec3 Direction of the up vector dtypedtype Dtype of the resulting matrix transposeboolean Whether to transpose result -
glm.normalize(V)
Return the unit vector in the same direction as the original vector
Parameters Type Description VvecN Vector to normalize -
glm.clamp(value, vmin, vmax)
Return value bound between vmin and vmax
Parameters Type Description valuefloat or vecN Value to normalize vminfloat Minimum value vmaxfloat Maximum value