ncca-ngl 0.1.6__tar.gz → 0.2.2__tar.gz

{ncca_ngl-0.1.6 → ncca_ngl-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ncca-ngl
-Version: 0.1.6
+Version: 0.2.2
 Summary: A Python version of the NGL graphics library.
 Author: Jon Macey
 Author-email: Jon Macey <jmacey@bournemouth.ac.uk>

{ncca_ngl-0.1.6 → ncca_ngl-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ncca-ngl"
-version = "0.1.6"
+version = "0.2.2"
 description = "A Python version of the NGL graphics library."
 authors = [{ name = "Jon Macey", email = "jmacey@bournemouth.ac.uk" }]
 requires-python = ">=3.13"

{ncca_ngl-0.1.6 → ncca_ngl-0.2.2}/src/ncca/ngl/__init__.py

@@ -25,7 +25,8 @@ from .obj import (
     ObjParseVertexError,
 )
 from .plane import Plane
-from .primitives import Primitives, Prims
+from .prim_data import PrimData, Prims
+from .primitives import Primitives
 from .pyside_event_handling_mixin import PySideEventHandlingMixin
 from .quaternion import Quaternion
 from .random import Random
@@ -103,6 +104,7 @@ all = [
     logger,
     Primitives,
     Prims,
+    PrimData,
     FirstPersonCamera,
     PySideEventHandlingMixin,
 ]

ncca_ngl-0.1.6/src/ncca/ngl/primitives.py → ncca_ngl-0.2.2/src/ncca/ngl/prim_data.py

@@ -1,21 +1,9 @@
-"""
-OpenGL primitive generation and drawing functions
-In this class we can generate a pipeline for drawing our data for the most part it will be
-x,y,z nx,ny,nz and u,v data in a flat numpy array.
-We need to create the data first which is stored in a map as part of the class, we can then call draw
-which will generate a pipeline for this object and draw into the current context.
-"""
-
 import enum
 from pathlib import Path
-from typing import Dict, Union
+from typing import Union
 
 import numpy as np
-import OpenGL.GL as gl
 
-from .log import logger
-from .simple_vao import VertexData
-from .vao_factory import VAOFactory, VAOType  # noqa
 from .vec3 import Vec3
 
 
@@ -33,6 +21,14 @@ class Prims(enum.Enum):
     TEAPOT = "teapot"
     TETRAHEDRON = "tetrahedron"
     TROLL = "troll"
+    SPHERE = "sphere"
+    TORUS = "torus"
+    LINE_GRID = "line_grid"
+    TRIANGLE_PLANE = "triangle_plane"
+    CONE = "cone"
+    CAPSULE = "capsule"
+    CYLINDER = "cylinder"
+    DISK = "disk"
 
 
 def _circle_table(n: int) -> np.ndarray:
@@ -66,61 +62,13 @@ def _circle_table(n: int) -> np.ndarray:
     return cs
 
 
-class _primitive:
-    """A private class to hold VAO data for a primitive."""
-
-    def __init__(self, prim_data: np.ndarray):
-        """
-        Initializes the primitive with the given data.
-
-        Args:
-            prim_data: A numpy array containing the vertex data (x,y,z,nx,ny,nz,u,v).
-        """
-        self.vao = VAOFactory.create_vao(VAOType.SIMPLE, gl.GL_TRIANGLES)
-        with self.vao:
-            data = VertexData(data=prim_data.data, size=prim_data.size)
-            self.vao.set_data(data)
-            vert_data_size = 8 * 4  # 4 is sizeof float and 8 is x,y,z,nx,ny,nz,uv
-            self.vao.set_vertex_attribute_pointer(0, 3, gl.GL_FLOAT, vert_data_size, 0)
-            self.vao.set_vertex_attribute_pointer(
-                1, 3, gl.GL_FLOAT, vert_data_size, Vec3.sizeof()
-            )
-            self.vao.set_vertex_attribute_pointer(
-                2, 2, gl.GL_FLOAT, vert_data_size, 2 * Vec3.sizeof()
-            )
-            self.vao.set_num_indices(prim_data.size // 8)
-
-
-class Primitives:
-    """A static class for creating and drawing primitives."""
-
-    # this is effectively a static class so we can use it to store data
-    # and generate pipelines for drawing
-    _primitives: Dict[str, _primitive] = {}
-    _loaded: bool = False
-
-    @classmethod
-    def load_default_primitives(cls) -> None:
-        """Loads the default primitives from the PrimData directory."""
-        logger.info("Loading default primitives...")
-        if not cls._loaded:
-            prim_folder = Path(__file__).parent / "PrimData"
-            prims = np.load(prim_folder / "Primitives.npz")
-            for p in prims.items():
-                prim_data = p[1]
-                prim = _primitive(prim_data)
-                cls._primitives[p[0]] = prim
-            cls._loaded = True
-
-    @classmethod
-    def create_line_grid(
-        cls, name: str, width: float, depth: float, steps: int
-    ) -> None:
+class PrimData:
+    @staticmethod
+    def line_grid(width: float, depth: float, steps: int) -> np.ndarray:
         """
         Creates a line grid primitive.
 
         Args:
-            name: The name of the primitive to create.
             width: The width of the grid.
             depth: The depth of the grid.
             steps: The number of steps in the grid.
@@ -153,19 +101,14 @@ class Primitives:
             v2 += dstep
 
         # Convert the list to a NumPy array
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
-
-    @classmethod
-    def create_triangle_plane(
-        cls, name: str, width: float, depth: float, w_p: int, d_p: int, v_n: Vec3
-    ) -> None:
+        return np.array(data, dtype=np.float32)
+
+    @staticmethod
+    def triangle_plane(width: float, depth: float, w_p: int, d_p: int, v_n: Vec3) -> np.ndarray:
         """
         Creates a triangle plane primitive.
 
         Args:
-            name: The name of the primitive.
             width: The width of the plane.
             depth: The depth of the plane.
             w_p: The number of width partitions.
@@ -191,17 +134,13 @@ class Primitives:
                 # vert 1
                 data.extend([w, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u, v + dv])
                 # vert 2
-                data.extend(
-                    [w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv]
-                )
+                data.extend([w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv])
                 # vert 3
                 data.extend([w, 0.0, d, v_n.x, v_n.y, v_n.z, u, v])
 
                 # tri 2
                 # vert 1
-                data.extend(
-                    [w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv]
-                )
+                data.extend([w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv])
                 # vert 2
                 data.extend([w + w_step, 0.0, d, v_n.x, v_n.y, v_n.z, u + du, v])
                 # vert 3
@@ -211,34 +150,14 @@ class Primitives:
             v += dv
             d += d_step
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def draw(cls, name: Union[str, Prims]) -> None:
-        """
-        Draws the specified primitive.
-
-        Args:
-            name: The name of the primitive to draw, either as a string or a Prims enum.
-        """
-        key = name.value if isinstance(name, Prims) else name
-        try:
-            prim = cls._primitives[key]
-            with prim.vao:
-                prim.vao.draw()
-        except KeyError:
-            logger.error(f"Failed to draw primitive {key}")
-            return
-
-    @classmethod
-    def create_sphere(cls, name: str, radius: float, precision: int) -> None:
+    @staticmethod
+    def sphere(radius: float, precision: int) -> np.ndarray:
         """
         Creates a sphere primitive.
 
         Args:
-            name: The name of the primitive.
             radius: The radius of the sphere.
             precision: The precision of the sphere (number of slices).
         """
@@ -310,19 +229,14 @@ class Primitives:
                 data.append([x1, y1, z1, nx1, ny1, nz1, u1, v1])
                 data.append([x3, y3, z3, nx3, ny3, nz3, u3, v3])
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_cone(
-        cls, name: str, base: float, height: float, slices: int, stacks: int
-    ) -> None:
+    @staticmethod
+    def cone(base: float, height: float, slices: int, stacks: int) -> np.ndarray:
         """
         Creates a cone primitive.
 
         Args:
-            name: The name of the primitive.
             base: The radius of the cone's base.
             height: The height of the cone.
             slices: The number of divisions around the cone.
@@ -429,14 +343,10 @@ class Primitives:
             r0 = r1
             r1 -= r_step
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_capsule(
-        cls, name: str, radius: float, height: float, precision: int
-    ) -> None:
+    @staticmethod
+    def capsule(radius: float, height: float, precision: int) -> np.ndarray:
         """
         Creates a capsule primitive.
         The capsule is aligned along the y-axis.
@@ -510,14 +420,10 @@ class Primitives:
                     nx, ny, nz = sb * c1, cb, sb * s1
                     data.extend([nx, ny + o, nz, nx, ny, nz, 0.0, 0.0])
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_cylinder(
-        cls, name: str, radius: float, height: float, slices: int, stacks: int
-    ) -> None:
+    @staticmethod
+    def cylinder(radius: float, height: float, slices: int, stacks: int) -> np.ndarray:
         """
         Creates a cylinder primitive.
         The cylinder is aligned along the y-axis.
@@ -568,17 +474,14 @@ class Primitives:
                 data.extend(p_tl)
                 data.extend(p_tr)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_disk(cls, name: str, radius: float, slices: int) -> None:
+    @staticmethod
+    def disk(radius: float, slices: int) -> np.ndarray:
         """
         Creates a disk primitive.
 
         Args:
-            name: The name of the primitive.
             radius: The radius of the disk.
             slices: The number of slices to divide the disk into.
         """
@@ -618,24 +521,19 @@ class Primitives:
             data.extend(p2)
             data.extend(p1)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_torus(
-        cls,
-        name: str,
+    @staticmethod
+    def torus(
         minor_radius: float,
         major_radius: float,
         sides: int,
         rings: int,
-    ) -> None:
+    ) -> np.ndarray:
         """
         Creates a torus primitive.
 
         Args:
-            name: The name of the primitive.
             minor_radius: The minor radius of the torus.
             major_radius: The major radius of the torus.
             sides: The number of sides for each ring.
@@ -701,6 +599,13 @@ class Primitives:
                 data.extend(p3)
                 data.extend(p4)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
+
+    @staticmethod
+    def primitive(name: Union[str, enum]) -> np.ndarray:
+        prim_folder = Path(__file__).parent / "PrimData"
+        prims = np.load(prim_folder / "Primitives.npz")
+        try:
+            return prims[name]
+        except KeyError:
+            raise ValueError(f"Primitive '{name}' not found")

ncca_ngl-0.2.2/src/ncca/ngl/primitives.py

@@ -0,0 +1,121 @@
+"""
+OpenGL primitive generation and drawing functions
+In this class we can generate a pipeline for drawing our data for the most part it will be
+x,y,z nx,ny,nz and u,v data in a flat numpy array.
+We need to create the data first which is stored in a map as part of the class, we can then call draw
+which will generate a pipeline for this object and draw into the current context.
+"""
+
+from typing import Dict, Union
+
+import numpy as np
+import OpenGL.GL as gl
+
+from .log import logger
+from .prim_data import PrimData, Prims
+from .simple_vao import VertexData
+from .vao_factory import VAOFactory, VAOType  # noqa
+from .vec3 import Vec3
+
+
+class _primitive:
+    """A private class to hold VAO data for a primitive."""
+
+    def __init__(self, prim_data: np.ndarray):
+        """
+        Initializes the primitive with the given data.
+
+        Args:
+            prim_data: A numpy array containing the vertex data (x,y,z,nx,ny,nz,u,v).
+        """
+        self.vao = VAOFactory.create_vao(VAOType.SIMPLE, gl.GL_TRIANGLES)
+        with self.vao:
+            data = VertexData(data=prim_data.data, size=prim_data.size)
+            self.vao.set_data(data)
+            vert_data_size = 8 * 4  # 4 is sizeof float and 8 is x,y,z,nx,ny,nz,uv
+            self.vao.set_vertex_attribute_pointer(0, 3, gl.GL_FLOAT, vert_data_size, 0)
+            self.vao.set_vertex_attribute_pointer(1, 3, gl.GL_FLOAT, vert_data_size, Vec3.sizeof())
+            self.vao.set_vertex_attribute_pointer(2, 2, gl.GL_FLOAT, vert_data_size, 2 * Vec3.sizeof())
+            self.vao.set_num_indices(prim_data.size // 8)
+
+
+class Primitives:
+    """A static class for creating and drawing primitives."""
+
+    # this is effectively a static class so we can use it to store data
+    # and generate pipelines for drawing
+    _primitives: Dict[str, _primitive] = {}
+    _loaded: bool = False
+
+    @classmethod
+    def create(cls, type: str, name: str, *args: object, **kwargs: object) -> None:
+        """
+        Creates and stores a primitive object of the specified type from :-
+        Prims.SPHERE : (radius: float, precision: int).
+        Prims.TORUS : (radius: float, tube_radius: float, precision: int).
+        Prims.LINE_GRID : (width: float, depth: float, steps: int).
+        Prims.TRIANGLE_PLANE : ( width: float, depth: float, w_p: int, d_p: int, v_n: Vec3).
+        Prims.CYLINDER : (radius: float, height: float, slices: int, stacks: int).
+        Prims.CAPSULE : (radius: float, height: float, slices: int, stacks: int).
+        Prims.CONE : (radius: float, height: float, slices: int, stacks: int).
+
+        Args:
+            type (str): The primitive type, typically from the Prims enum (e.g., Prims.SPHERE).
+            name (str): The name to associate with the created primitive.
+            *args: Positional arguments to pass to the primitive creation function (e.g., radius, precision).
+            **kwargs: Keyword arguments to pass to the primitive creation function.
+
+        Raises:
+            ValueError: If the primitive type is not recognized.
+
+        Example:
+            Primitives.create(Prims.SPHERE, "sphere", 0.3, 32)
+            Primitives.create(Prims.SPHERE, "sphere", radius=0.3, precision=32)
+        """
+        prim_methods = {
+            Prims.SPHERE: PrimData.sphere,
+            Prims.TORUS: PrimData.torus,
+            Prims.LINE_GRID: PrimData.line_grid,
+            Prims.TRIANGLE_PLANE: PrimData.triangle_plane,
+            Prims.CYLINDER: PrimData.cylinder,
+            Prims.DISK: PrimData.disk,
+            Prims.CAPSULE: PrimData.capsule,
+            Prims.CONE: PrimData.cone,
+        }
+        try:
+            method = prim_methods[type]
+        except KeyError:
+            raise ValueError(f"Unknown primitive: {name}")
+
+        cls._primitives[name] = _primitive(method(*args, **kwargs))
+
+    @classmethod
+    def load_default_primitives(cls) -> None:
+        """Loads the default primitives from the PrimData directory."""
+        logger.info("Loading default primitives...")
+        if not cls._loaded:
+            for p in Prims:
+                try:
+                    prim_data = PrimData.primitive(p.value)
+                    prim = _primitive(prim_data)
+                    cls._primitives[p.value] = prim
+                except Exception:
+                    pass
+            cls._loaded = True
+
+    @classmethod
+    def draw(cls, name: Union[str, Prims]) -> None:
+        """
+        Draws the specified primitive.
+
+        Args:
+            name: The name of the primitive to draw, either as a string or a Prims enum.
+        """
+        key = name.value if isinstance(name, Prims) else name
+        try:
+            prim = cls._primitives[key]
+            with prim.vao:
+                prim.vao.draw()
+        except KeyError:
+            logger.error(f"Failed to draw primitive {key}")
+            return

{ncca_ngl-0.1.6 → ncca_ngl-0.2.2}/src/ncca/ngl/util.py

@@ -3,6 +3,7 @@
 Most of these functions are based on functions found in other libraries such as GLM, NGL or GLU
 """
 
+import enum
 import math
 
 from .mat4 import Mat4
@@ -44,7 +45,32 @@ def look_at(eye, look, up):
     return result
 
 
-def perspective(fov, aspect, near, far):
+class PerspMode(enum.Enum):
+    OpenGL = "OpenGL"
+    WebGPU = "WebGPU"
+    Vulkan = "Vulkan"
+
+
+def perspective(
+    fov: float,
+    aspect: float,
+    near: float,
+    far: float,
+    mode: PerspMode = PerspMode.OpenGL,
+) -> Mat4:
+    """
+    Calculate a perspective matrix for various 3D graphics API's default mode is OpenGL but will covert for Vulkan and Web GPU if
+    required.
+
+    Args :
+        fov : float - Field of view angle in degrees.
+        aspect : float - Aspect ratio of the viewport.
+        near : float - Near clipping plane distance.
+        far : float - Far clipping plane distance.
+
+    Returns:
+        Mat4 - The perspective matrix.
+    """
     m = Mat4.zero()  # as per glm
     _range = math.tan(math.radians(fov / 2.0)) * near
     left = -_range * aspect
@@ -53,34 +79,36 @@ def perspective(fov, aspect, near, far):
     top = _range
     m.m[0][0] = (2.0 * near) / (right - left)
     m.m[1][1] = (2.0 * near) / (top - bottom)
-    m.m[2][2] = -(far + near) / (far - near)
-    m.m[2][3] = -1.0
-    m.m[3][2] = -(2.0 * far * near) / (far - near)
+    match mode:
+        case PerspMode.OpenGL:
+            m.m[2][2] = -(far + near) / (far - near)
+            m.m[2][3] = -1.0
+            m.m[3][2] = -(2.0 * far * near) / (far - near)
+
+        # This ensures the clip space Z range is [0, 1] as required by Vulkan and WebGPU.
+        case PerspMode.WebGPU | PerspMode.Vulkan:
+            m.m[2][2] = -far / (far - near)
+            m.m[2][3] = -1.0
+            m.m[3][2] = -(far * near) / (far - near)
     return m
 
 
-def ortho(left, right, bottom, top, near, far):
-    """Create an orthographic projection matrix."""
+def ortho(left, right, bottom, top, near, far, mode=PerspMode.OpenGL):
     m = Mat4.identity()
     m.m[0][0] = 2.0 / (right - left)
     m.m[1][1] = 2.0 / (top - bottom)
-    m.m[2][2] = -2.0 / (far - near)
+    match mode:
+        case PerspMode.OpenGL:
+            m.m[2][2] = -2.0 / (far - near)
+            m.m[3][2] = -(far + near) / (far - near)
+        case PerspMode.WebGPU | PerspMode.Vulkan:
+            m.m[2][2] = -1.0 / (far - near)
+            m.m[3][2] = -near / (far - near)
     m.m[3][0] = -(right + left) / (right - left)
     m.m[3][1] = -(top + bottom) / (top - bottom)
-    m.m[3][2] = -(far + near) / (far - near)
     return m
 
 
-# Mat4 result(1.0f);
-#   result.m_00= 2.0f / (_right - _left);
-#   result.m_11= 2.0f / (_top - _bottom);
-#   result.m_22= - 2.0f / (_zFar - _zNear);
-#   result.m_30= - (_right + _left) / (_right - _left);
-#   result.m_31= - (_top + _bottom) / (_top - _bottom);
-#   result.m_32= - (_zFar + _zNear) / (_zFar - _zNear);
-#   return result;
-
-
 def frustum(left, right, bottom, top, near, far):
     """Create a frustum projection matrix."""
     m = Mat4.zero()