transforms.py

# transforms.py
# =============================================================================
# Centralized 2D and 3D transformation utilities for the rasterization engine.
# Matrices are column major. Vectors are column vectors.
#
# author Zhen Lai
# date Oct 2025

from pyglm import glm
import math

# =============================================================================
# 2D (homogeneous) transforms: mat3
# =============================================================================

class T2:
    """
    2D homogeneous transformation constructors (mat3).

    Notes:
    Returned matrices are intended to be used as: out = M * v.
    Compose as: M_total = M3 * M2 * M1; then out = M_total * v.
    Follow openGL convention.
    """

    @staticmethod
    def identity() -> glm.mat3:
        """Return 3×3 identity matrix.

        Returns
        -------
        glm.mat3
            Identity matrix.
        """
        return glm.mat3(1.0)

    @staticmethod
    def translate(x: float, y: float) -> glm.mat3:
        """Return a 2D translation matrix.

        Parameters
        ----------
        x : float
            Translation along +X in object units.
        y : float
            Translation along +Y in object units.

        Returns
        -------
        glm.mat3
            3×3 homogeneous translation matrix.
        """
        return glm.translate(glm.mat3(1.0), glm.vec2(x, y))

    @staticmethod
    def scale(x: float, y: float)-> glm.mat3:
        """Return a 2D scaling matrix.

        Parameters
        ----------
        x : float
            Scale factor along X.
        y : float
            Scale factor along Y.

        Returns
        -------
        glm.mat3
            3×3 homogeneous scale matrix.
        """
        return glm.scale(glm.mat3(1.0), glm.vec2(x, y))

    @staticmethod
    def rotate(angle: float) -> glm.mat3:
        """Return a 2D CCW rotation about the origin.

        Parameters
        ----------
        angle : float
            Rotation angle in degrees (counter-clockwise).

        Returns
        -------
        glm.mat3
            3×3 homogeneous rotation matrix.
        """
        angle_radians = math.radians(angle)
        return glm.mat3(math.cos(angle_radians), -math.sin(angle_radians), 0,
                        math.sin(angle_radians), math.cos(angle_radians), 0,
                        0, 0, 1)

    @staticmethod
    def normalize(top: float, bottom: float, right: float, left: float) -> glm.mat3:
        """Map world rect [left, right] × [bottom, top] to NDC [-1, 1] × [-1, 1].

        Parameters
        ----------
        left, right : float
            World-space left and right bounds.
        bottom, top : float
            World-space bottom and top bounds.

        Returns
        -------
        glm.mat3
            Matrix that converts world→NDC.

        Notes
        -----
        • Use this before viewport mapping.
        """
        # Map [l,r]x[b,t] -> [-1,1]x[-1,1]
        sx = 2.0 / (right - left)
        sy = 2.0 / (top - bottom)
        tx = -(right + left) / (right - left)
        ty = -(top + bottom) / (top - bottom)
        return glm.mat3(
            sx, 0.0, 0.0,
            0.0, sy, 0.0,
            tx,  ty, 1.0
        )

    @staticmethod
    def viewport(left: int, right: int, bottom: int, top: int) -> glm.mat3:
        """
        Map NDC [-1,1]² to integer screen rectangle [left, right] × [bottom, top].
        """
        scale_x = (right - left) * 0.5
        scale_y = (top   - bottom) * 0.5
        offset_x = (right + left) * 0.5
        offset_y = (top   + bottom) * 0.5

        return glm.mat3(
            scale_x, 0.0,    0.0,
            0.0,     scale_y,0.0,
            offset_x,offset_y,1.0
        )


# =============================================================================
# 3D (homogeneous) transforms: mat4
# =============================================================================
class T3:
    """
    3D homogeneous transformation constructors (mat4) plus camera & projection
    """

    @staticmethod
    def identity3D() -> glm.mat4:
        """Return 4x4 identity matrix.

        Returns
        -------
        glm.mat4
            Identity matrix.
        """
        return glm.mat4(1.0)

    @staticmethod
    def translate3D(x: float, y: float, z:float) -> glm.mat4:
        """Return a 3D translation matrix.

        Parameters
        ----------
        x : float
            Translation along +X in object units.
        y : float
            Translation along +Y in object units.
        z : float
            Translation along +Z in object units.

        Returns
        -------
        glm.mat4
            4x4 homogeneous translation matrix.
        """
        return glm.translate(glm.mat4(1.0), glm.vec3(x, y, z))

    @staticmethod
    def scale3D(x: float, y: float, z: float)-> glm.mat4:
        """Return a 3D scaling matrix.

        Parameters
        ----------
        x : float
            Scale factor along X.
        y : float
            Scale factor along Y.

        Returns
        -------
        glm.mat3
            3×3 homogeneous scale matrix.
        """
        return glm.scale(glm.mat4(1.0), glm.vec3(x, y, z))

    @staticmethod
    def rotateX(angle:float) -> glm.mat4:
        """
        Return rotation about +X axis (right-handed, CCW when looking from +X).

        Parameters
        ----------
        angle : float
            Angle in degrees.

        Returns
        -------
        glm.mat4
            4×4 rotation matrix.

        """
        return glm.rotate(glm.mat4(1.0), math.radians(angle), glm.vec3(1,0,0))

    @staticmethod
    def rotateY(angle:float) -> glm.mat4:
        """
        Return rotation about +Y axis (right-handed, CCW when looking from +Y).

        Parameters
        ----------
        angle : float
            Angle in degrees.

        Returns
        -------
        glm.mat4
            4×4 rotation matrix.

        """
        return glm.rotate(glm.mat4(1.0), math.radians(angle), glm.vec3(0,1,0))

    @staticmethod
    def rotateZ(angle:float) -> glm.mat4:
        """
        Return rotation about +Z axis (right-handed, CCW when looking from +Z).

        Parameters
        ----------
        angle : float
            Angle in degrees.

        Returns
        -------
        glm.mat4
            4×4 rotation matrix.

        """
        return glm.rotate(glm.mat4(1.0), math.radians(angle), glm.vec3(0,0,1))

    @staticmethod
    def rotate_axis(axis: glm.vec3, angle: float) -> glm.mat4:
        """Return rotation about an arbitrary axis.

        Parameters
        ----------
        axis : glm.vec3
            Rotation axis (does not need to be pre-normalized; GLM will normalize).
        a_deg : float
            Angle in degrees.

        Returns
        -------
        glm.mat4
            4×4 rotation matrix.
        """
        return glm.rotate(glm.mat4(1.0), math.radians(angle), glm.normalize(axis))

    # Camera & Projections

    @staticmethod
    def lookAt(eye: glm.vec3, lookat: glm.vec3, up: glm.vec3) -> glm.mat4:
        """
        Return a right-handed view matrix (camera transform).

        Parameters
        ----------
        eye : glm.vec3
            Camera position in world space.
        lookat : glm.vec3
            Look-at target in world space.
        up : glm.vec3
            World-space up direction (need not be unit length).

        Returns
        -------
        glm.mat4
            View matrix that transforms world → view space.
        """
        return glm.lookAtRH(eye, lookat, up)

    @staticmethod
    def frustum3D(l, r, b, t, n, f) -> glm.mat4:
        """
        Return right-handed perspective projection matrix.

        Parameters
        ----------
        Parameters
        ----------
        l, r : float
            Left and right planes.
        b, t : float
            Bottom and top planes.
        n, f : float
            Near and far planes.

        Returns
        ----------
        glm.mat4
            Projection matrix mapping view space -> clip space
        """
        return glm.frustumRH_NO(l, r, b, t, n, f)

    @staticmethod
    def ortho3D(left: float, right: float, bottom: float, top: float, near: float, far: float):
        """
        Return right-handed orthographic projection matrix.

        Parameters
        ----------
        l, r : float
            Left and right planes.
        b, t : float
            Bottom and top planes.
        n, f : float
            Near and far planes.

        Returns
        -------
        glm.mat4
            Orthographic projection matrix from view space to clip space.
        """
        return glm.orthoRH_NO(left, right, bottom, top, near, far)