simvx.core.math.matrices

Pure NumPy matrix utilities.

All matrices use NumPy’s native row-major layout. When sending to GLSL, matrices must be transposed (GLSL expects column-major); this transpose happens only at GPU boundary points, keeping the rest of the engine free of row-major vs column-major ambiguity.

Module Contents

Functions

quat_to_mat4	Convert a quaternion to a 4x4 rotation matrix.
identity	Create 4x4 identity matrix.
perspective	Create perspective projection matrix.
oblique_near_plane	Replace proj’s near clip plane with an arbitrary world-space plane.
look_at	Create view matrix using look-at vectors.
translate	Create translation matrix.
rotate	Create rotation matrix using axis-angle representation.
scale	Create scale matrix.
orthographic	Create orthographic projection matrix.
mat4_from_trs	Build model matrix from position, rotation quaternion, and scale.
batch_mat4_from_trs	Build N model matrices from arrays of positions, quaternions, and scales.
mat4_to_bytes	Convert mat4 to bytes for GPU upload (64 bytes, row-major float32).
halton_jitter	Sub-pixel jitter offset in [-0.5, 0.5] from the Halton(base_x, base_y) sequence.
apply_jitter	Return a copy of proj translated by a sub-pixel jitter in clip space.

Data

log
__all__

API

simvx.core.math.matrices.log

‘getLogger(…)’

simvx.core.math.matrices.__all__

[‘identity’, ‘perspective’, ‘oblique_near_plane’, ‘look_at’, ‘translate’, ‘rotate’, ‘scale’, ‘orthog…

simvx.core.math.matrices.quat_to_mat4(q, dtype: numpy.dtype = np.float32) → numpy.ndarray

Convert a quaternion to a 4x4 rotation matrix.

Args: q: Quaternion: any object with .w, .x, .y, .z attributes (e.g. Quat) or a 4-element array [w, x, y, z]. dtype: NumPy data type (default float32)

Returns: 4x4 rotation matrix as numpy array

simvx.core.math.matrices.identity(dtype: numpy.dtype = np.float32) → numpy.ndarray

Create 4x4 identity matrix.

Args: dtype: NumPy data type (default float32)

Returns: 4x4 identity matrix as numpy array

simvx.core.math.matrices.perspective(fov: float, aspect: float, near: float, far: float, dtype: numpy.dtype = np.float32) → numpy.ndarray

Create perspective projection matrix.

Args: fov: Field of view in radians aspect: Aspect ratio (width / height) near: Near clipping plane far: Far clipping plane dtype: NumPy data type (default float32)

Returns: 4x4 perspective projection matrix

Note: Does NOT include Y-flip for Vulkan. Caller must do: proj[1, 1] *= -1 # Flip Y-axis for Vulkan

simvx.core.math.matrices.oblique_near_plane(proj: numpy.ndarray, view: numpy.ndarray, plane: tuple[float, float, float, float] | numpy.ndarray, dtype: numpy.dtype = np.float32) → numpy.ndarray

Replace proj’s near clip plane with an arbitrary world-space plane.

The oblique-frustum technique (Lengyel, “Oblique View Frustum Depth Projection and Clipping”): the projection’s z row is rewritten so the GPU’s fixed 0 <= z_clip <= w_clip near clip coincides with plane, scaled so the new far plane still touches the corner of the original frustum that lies deepest on the kept side. Used by planar reflections: the mirrored camera must not render geometry behind the reflection plane.

Args: proj: 4x4 projection matrix (row-major, any convention whose hardware clip volume is 0 <= z_clip <= w_clip; both backends qualify). view: 4x4 view matrix of the camera the projection belongs to. plane: World-space plane (nx, ny, nz, d) with the equation n . x + d = 0; geometry on the n . x + d > 0 side is kept.

Returns: A new 4x4 projection matrix (input is not modified). Depth values are redistributed (inherent to the technique); depth testing within the pass stays consistent. Returns proj unchanged when the plane does not face any part of the view frustum (degenerate input).

simvx.core.math.matrices.look_at(eye: numpy.ndarray | tuple[float, float, float], center: numpy.ndarray | tuple[float, float, float], up: numpy.ndarray | tuple[float, float, float], dtype: numpy.dtype = np.float32) → numpy.ndarray

Create view matrix using look-at vectors.

Args: eye: Camera position center: Point to look at up: Up vector (should be normalized) dtype: NumPy data type (default float32)

Returns: 4x4 view matrix

simvx.core.math.matrices.translate(t: numpy.ndarray | tuple[float, float, float], dtype: numpy.dtype = np.float32) → numpy.ndarray

Create translation matrix.

Args: t: Translation vector (x, y, z) dtype: NumPy data type (default float32)

Returns: 4x4 translation matrix

simvx.core.math.matrices.rotate(axis: numpy.ndarray | tuple[float, float, float], angle: float, dtype: numpy.dtype = np.float32) → numpy.ndarray

Create rotation matrix using axis-angle representation.

Args: axis: Rotation axis (should be normalized) angle: Rotation angle in radians dtype: NumPy data type (default float32)

Returns: 4x4 rotation matrix

Uses Rodrigues’ rotation formula.

simvx.core.math.matrices.scale(s: numpy.ndarray | tuple[float, float, float] | float, dtype: numpy.dtype = np.float32) → numpy.ndarray

Create scale matrix.

Args: s: Scale factors (x, y, z) or uniform scale factor dtype: NumPy data type (default float32)

Returns: 4x4 scale matrix

simvx.core.math.matrices.orthographic(left: float, right: float, bottom: float, top: float, near: float, far: float, dtype: numpy.dtype = np.float32) → numpy.ndarray

Create orthographic projection matrix.

Args: left: Left plane right: Right plane bottom: Bottom plane top: Top plane near: Near plane far: Far plane dtype: NumPy data type (default float32)

Returns: 4x4 orthographic projection matrix

Note: For Vulkan, you may need to flip Y: proj[1, 1] *= -1

simvx.core.math.matrices.mat4_from_trs(pos: tuple[float, float, float] | numpy.ndarray, rot, scl: tuple[float, float, float] | numpy.ndarray) → numpy.ndarray

Build model matrix from position, rotation quaternion, and scale.

Args: pos: Position (x, y, z) rot: Rotation quaternion: Quat or any object with .w/.x/.y/.z scl: Scale (x, y, z)

Returns: 4x4 model matrix as numpy array (Translate * Rotate * Scale)

simvx.core.math.matrices.batch_mat4_from_trs(positions: numpy.ndarray, rotations: numpy.ndarray, scales: numpy.ndarray) → numpy.ndarray

Build N model matrices from arrays of positions, quaternions, and scales.

Args: positions: (N, 3) float32 positions rotations: (N, 4) float32 quaternions [w, x, y, z] scales: (N, 3) float32 scale factors

Returns: (N, 4, 4) float32 model matrices (Translate * Rotate * Scale)

simvx.core.math.matrices.mat4_to_bytes(m: numpy.ndarray) → bytes

Convert mat4 to bytes for GPU upload (64 bytes, row-major float32).

simvx.core.math.matrices.halton_jitter(index: int, base_x: int = 2, base_y: int = 3) → tuple[float, float]

Sub-pixel jitter offset in [-0.5, 0.5] from the Halton(base_x, base_y) sequence.

Used for TAA: each frame samples a different sub-pixel location so the temporal accumulation reconstructs detail below one pixel. index is the frame counter (callers typically cycle it modulo the history length, e.g. 8). Mirrors the web runtime’s TAAPass.haltonJitter exactly so desktop and web jitter identically.

Returns: (jx, jy) offsets in pixels, each in [-0.5, 0.5].

simvx.core.math.matrices.apply_jitter(proj: numpy.ndarray, jx: float, jy: float, width: float, height: float) → numpy.ndarray

Return a copy of proj translated by a sub-pixel jitter in clip space.

proj is a row-major Vulkan projection matrix (post Y-flip). The pixel-space jitter (jx, jy) is converted to NDC (2 / dim per pixel) and added to the clip-x/clip-y rows of the third column (proj[0, 2] / proj[1, 2]), the same slots the renderer transposes to the GPU’s column-2 rows 0/1. The original matrix is left untouched so callers keep an unjittered copy for culling and motion-vector reprojection.