ncca-ngl 0.1.0__py3-none-any.whl

ncca/ngl/pyside_event_handling_mixin.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+Event Handling Mixin for PyNGL Applications
+
+This module provides a reusable mixin class that implements common event handling
+patterns used across PyNGL applications, including mouse-based camera control,
+keyboard shortcuts, and wheel-based zooming.
+
+Usage:
+    class MyWindow(EventHandlingMixin, QOpenGLWindow):
+        def __init__(self):
+            super().__init__()
+            self.setup_event_handling()  # Initialize mixin attributes
+            # ... rest of your initialization
+"""
+
+from typing import Protocol
+
+import OpenGL.GL as gl
+from PySide6.QtCore import Qt
+
+from .vec3 import Vec3
+
+
+class EventHandlingTarget(Protocol):
+    """
+    Protocol defining the interface that classes using EventHandlingMixin must implement.
+
+    This ensures that the mixin has access to the necessary methods and attributes.
+    """
+
+    def update(self) -> None:
+        """Trigger a redraw of the window."""
+        ...
+
+    def close(self) -> None:
+        """Close the window."""
+        ...
+
+
+class PySideEventHandlingMixin:
+    """
+    Mixin class providing standard event handling for PyNGL applications.
+
+    This mixin provides common functionality for:
+    - Mouse-based camera control (rotation with left button, translation with right button)
+    - Keyboard shortcuts (wireframe/solid mode, reset, escape)
+    - Mouse wheel zooming
+
+    Classes using this mixin should call setup_event_handling() in their __init__ method.
+    """
+
+    # Default sensitivity values
+    DEFAULT_ROTATION_SENSITIVITY = 0.5
+    DEFAULT_TRANSLATION_SENSITIVITY = 0.01
+    DEFAULT_ZOOM_SENSITIVITY = 0.1
+
+    def setup_event_handling(
+        self,
+        rotation_sensitivity: float = DEFAULT_ROTATION_SENSITIVITY,
+        translation_sensitivity: float = DEFAULT_TRANSLATION_SENSITIVITY,
+        zoom_sensitivity: float = DEFAULT_ZOOM_SENSITIVITY,
+        initial_position: Vec3 = None,
+    ) -> None:
+        """
+        Initialize event handling attributes.
+
+        Args:
+            rotation_sensitivity: Mouse sensitivity for rotation (default: 0.5)
+            translation_sensitivity: Mouse sensitivity for translation (default: 0.01)
+            zoom_sensitivity: Mouse wheel sensitivity for zooming (default: 0.1)
+            initial_position: Initial model position (default: Vec3(0,0,0))
+        """
+        # Mouse control state
+        self.rotate: bool = False
+        self.translate: bool = False
+
+        # Rotation state
+        self.spin_x_face: int = 0
+        self.spin_y_face: int = 0
+
+        # Mouse position tracking for rotation
+        self.original_x_rotation: float = 0.0
+        self.original_y_rotation: float = 0.0
+
+        # Mouse position tracking for translation
+        self.original_x_pos: float = 0.0
+        self.original_y_pos: float = 0.0
+
+        # Model position and sensitivity settings
+        self.model_position: Vec3 = initial_position or Vec3(0, 0, 0)
+        self.rotation_sensitivity: float = rotation_sensitivity
+        self.translation_sensitivity: float = translation_sensitivity
+        self.zoom_sensitivity: float = zoom_sensitivity
+
+        self.INCREMENT = self.translation_sensitivity
+        self.ZOOM = self.zoom_sensitivity
+
+    # def sync_legacy_attributes(self) -> None:
+    #     """
+    #     Synchronize legacy attribute names with new ones.
+    #     Call this if you modify the legacy attributes directly.
+    #     """
+    #     self.spin_x_face = self.spinXFace
+    #     self.spin_y_face = self.spinYFace
+    #     self.model_position = self.modelPos
+    #     self.original_x_rotation = self.origX
+    #     self.original_y_rotation = self.origY
+    #     self.original_x_pos = self.origXPos
+    #     self.original_y_pos = self.origYPos
+    #     self.translation_sensitivity = self.INCREMENT
+    #     self.zoom_sensitivity = self.ZOOM
+
+    def reset_camera(self) -> None:
+        """Reset camera rotation and model position to defaults."""
+        self.spin_x_face = 0
+        self.spin_y_face = 0
+        self.model_position.set(0, 0, 0)
+
+        # # Sync legacy attributes
+        # self.spinXFace = 0
+        # self.spinYFace = 0
+        # self.modelPos.set(0, 0, 0)
+
+    def keyPressEvent(self, event) -> None:
+        """
+        Handle keyboard press events with common shortcuts.
+
+        Shortcuts:
+        - Escape: Close application
+        - W: Switch to wireframe mode
+        - S: Switch to solid fill mode
+        - Space: Reset camera rotation and position
+
+        Args:
+            event: The QKeyEvent object
+        """
+        key = event.key()
+
+        if key == Qt.Key_Escape:
+            self.close()
+        elif key == Qt.Key_W:
+            gl.glPolygonMode(gl.GL_FRONT_AND_BACK, gl.GL_LINE)
+        elif key == Qt.Key_S:
+            gl.glPolygonMode(gl.GL_FRONT_AND_BACK, gl.GL_FILL)
+        elif key == Qt.Key_Space:
+            self.reset_camera()
+        else:
+            # Let subclasses handle other keys
+            super().keyPressEvent(event)
+            return
+
+        self.update()
+
+    def mouseMoveEvent(self, event) -> None:
+        """
+        Handle mouse movement for camera control.
+
+        - Left button: Rotate the scene
+        - Right button: Translate (pan) the scene
+
+        Args:
+            event: The QMouseEvent object
+        """
+        position = event.position()
+
+        # Handle rotation with left mouse button
+        if self.rotate and event.buttons() == Qt.LeftButton:
+            diff_x = position.x() - self.original_x_rotation
+            diff_y = position.y() - self.original_y_rotation
+
+            self.spin_x_face += int(self.rotation_sensitivity * diff_y)
+            self.spin_y_face += int(self.rotation_sensitivity * diff_x)
+
+            self.original_x_rotation = position.x()
+            self.original_y_rotation = position.y()
+
+            # # Sync legacy attributes
+            # self.spinXFace = self.spin_x_face
+            # self.spinYFace = self.spin_y_face
+            # self.origX = self.original_x_rotation
+            # self.origY = self.original_y_rotation
+
+            self.update()
+
+        # Handle translation with right mouse button
+        elif self.translate and event.buttons() == Qt.RightButton:
+            diff_x = int(position.x() - self.original_x_pos)
+            diff_y = int(position.y() - self.original_y_pos)
+
+            self.original_x_pos = position.x()
+            self.original_y_pos = position.y()
+
+            self.model_position.x += self.translation_sensitivity * diff_x
+            self.model_position.y -= self.translation_sensitivity * diff_y
+
+            # # Sync legacy attributes
+            # self.origXPos = self.original_x_pos
+            # self.origYPos = self.original_y_pos
+            # self.modelPos = self.model_position
+
+            self.update()
+
+    def mousePressEvent(self, event) -> None:
+        """
+        Handle mouse button press events to initiate rotation or translation.
+
+        - Left button: Start rotation mode
+        - Right button: Start translation mode
+
+        Args:
+            event: The QMouseEvent object
+        """
+        position = event.position()
+
+        if event.button() == Qt.LeftButton:
+            self.original_x_rotation = position.x()
+            self.original_y_rotation = position.y()
+            self.rotate = True
+
+            # # Sync legacy attributes
+            # self.origX = self.original_x_rotation
+            # self.origY = self.original_y_rotation
+
+        elif event.button() == Qt.RightButton:
+            self.original_x_pos = position.x()
+            self.original_y_pos = position.y()
+            self.translate = True
+
+            # # Sync legacy attributes
+            # self.origXPos = self.original_x_pos
+            # self.origYPos = self.original_y_pos
+
+    def mouseReleaseEvent(self, event) -> None:
+        """
+        Handle mouse button release events to stop rotation or translation.
+
+        Args:
+            event: The QMouseEvent object
+        """
+        if event.button() == Qt.LeftButton:
+            self.rotate = False
+        elif event.button() == Qt.RightButton:
+            self.translate = False
+
+    def wheelEvent(self, event) -> None:
+        """
+        Handle mouse wheel events for zooming.
+
+        Zooming is performed by adjusting the Z coordinate of the model position.
+
+        Args:
+            event: The QWheelEvent object
+        """
+        angle_delta = event.angleDelta()
+
+        # Handle both x and y wheel movement (some mice/trackpads use different axes)
+        delta = angle_delta.y() if angle_delta.y() != 0 else angle_delta.x()
+
+        if delta > 0:
+            self.model_position.z += self.zoom_sensitivity
+        elif delta < 0:
+            self.model_position.z -= self.zoom_sensitivity
+
+        # # Sync legacy attributes
+        # self.modelPos = self.model_position
+
+        self.update()
+
+    def get_camera_state(self) -> dict:
+        """
+        Get the current camera state for serialization or debugging.
+
+        Returns:
+            Dictionary containing current camera state
+        """
+        return {
+            "spin_x_face": self.spin_x_face,
+            "spin_y_face": self.spin_y_face,
+            "model_position": [
+                self.model_position.x,
+                self.model_position.y,
+                self.model_position.z,
+            ],
+            "rotation_sensitivity": self.rotation_sensitivity,
+            "translation_sensitivity": self.translation_sensitivity,
+            "zoom_sensitivity": self.zoom_sensitivity,
+        }
+
+    def set_camera_state(self, state: dict) -> None:
+        """
+        Restore camera state from a dictionary.
+
+        Args:
+            state: Dictionary containing camera state (from get_camera_state())
+        """
+        self.spin_x_face = state.get("spin_x_face", 0)
+        self.spin_y_face = state.get("spin_y_face", 0)
+
+        pos = state.get("model_position", [0, 0, 0])
+        # Handle cases where pos might have fewer than 3 elements
+        x = pos[0] if len(pos) > 0 else 0
+        y = pos[1] if len(pos) > 1 else 0
+        z = pos[2] if len(pos) > 2 else 0
+        self.model_position.set(x, y, z)
+
+        self.rotation_sensitivity = state.get(
+            "rotation_sensitivity", self.DEFAULT_ROTATION_SENSITIVITY
+        )
+        self.translation_sensitivity = state.get(
+            "translation_sensitivity", self.DEFAULT_TRANSLATION_SENSITIVITY
+        )
+        self.zoom_sensitivity = state.get(
+            "zoom_sensitivity", self.DEFAULT_ZOOM_SENSITIVITY
+        )
+
+        # # Sync legacy attributes
+        # self.sync_legacy_attributes()

ncca/ngl/quaternion.py

@@ -0,0 +1,112 @@
+"""
+A simple Quaternion class for use in NCCA Python
+Attributes:
+    s (float): The scalar part of the quaternion.
+    x (float): The x-coordinate of the vector part of the quaternion.
+    y (float): The y-coordinate of the vector part of the quaternion.
+    z (float): The z-coordinate of the vector part of the quaternion.
+"""
+
+import math
+
+from .mat4 import Mat4
+
+
+class Quaternion:
+    __slots__ = ["s", "x", "y", "z"]  # fix the attributes to s x,y,z
+
+    def __init__(self, s: float = 1.0, x: float = 0, y: float = 0, z: float = 0):
+        """
+        Initializes a new instance of the Quaternion class.
+
+        Args:
+            s (float): The scalar part of the quaternion.
+            x (float): The x-coordinate of the vector part of the quaternion.
+            y (float): The y-coordinate of the vector part of the quaternion.
+            z (float): The z-coordinate of the vector part of the quaternion.
+
+        """
+        self.s = float(s)
+        self.x = float(x)
+        self.y = float(y)
+        self.z = float(z)
+
+    @staticmethod
+    def from_mat4(mat: "Mat4") -> "Quaternion":
+        """
+        Creates a new Quaternion from a Mat4 rotation matrix.
+
+        Args:
+            mat (Mat4): The rotation matrix to convert.
+
+        Returns:
+            Quaternion: A new Quaternion representing the rotation matrix.
+
+        """
+        matrix = mat.get_matrix()
+        T = 1.0 + matrix[0] + matrix[5] + matrix[10]
+        if T > 0.00000001:  # to avoid large distortions!
+            scale = math.sqrt(T) * 2.0
+            x = (matrix[6] - matrix[9]) / scale
+            y = (matrix[8] - matrix[2]) / scale
+            z = (matrix[1] - matrix[4]) / scale
+            s = 0.25 * scale
+        elif matrix[0] > matrix[5] and matrix[0] > matrix[10]:
+            scale = math.sqrt(1.0 + matrix[0] - matrix[5] - matrix[10]) * 2.0
+            x = 0.25 * scale
+            y = (matrix[4] + matrix[1]) / scale
+            z = (matrix[2] + matrix[8]) / scale
+            s = (matrix[6] - matrix[9]) / scale
+
+        elif matrix[5] > matrix[10]:
+            scale = math.sqrt(1.0 + matrix[5] - matrix[0] - matrix[10]) * 2.0
+            x = (matrix[4] + matrix[1]) / scale
+            y = 0.25 * scale
+            z = (matrix[9] + matrix[6]) / scale
+            s = (matrix[8] - matrix[2]) / scale
+
+        else:
+            scale = math.sqrt(1.0 + matrix[10] - matrix[0] - matrix[5]) * 2.0
+            x = (matrix[8] + matrix[2]) / scale
+            y = (matrix[9] + matrix[6]) / scale
+            z = 0.25 * scale
+            s = (matrix[1] - matrix[4]) / scale
+
+        return Quaternion(s, x, y, z)
+
+    def __add__(self, rhs):
+        return Quaternion(self.s + rhs.s, self.x + rhs.x, self.y + rhs.y, self.z + rhs.z)
+
+    def __iadd__(self, rhs):
+        self.s += rhs.s
+        self.x += rhs.x
+        self.y += rhs.y
+        self.z += rhs.z
+        return self
+
+    def __sub__(self, rhs):
+        return Quaternion(self.s - rhs.s, self.x - rhs.x, self.y - rhs.y, self.z - rhs.z)
+
+    def __isub__(self, rhs):
+        return self.__sub__(rhs)
+
+    def __mul__(self, rhs):
+        return Quaternion(
+            self.s * rhs.s - self.x * rhs.x - self.y * rhs.y - self.z * rhs.z,
+            self.s * rhs.x + self.x * rhs.s + self.y * rhs.z - self.z * rhs.y,
+            self.s * rhs.y - self.x * rhs.z + self.y * rhs.s + self.z * rhs.x,
+            self.s * rhs.z + self.x * rhs.y - self.y * rhs.x + self.z * rhs.s,
+        )
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the Quaternion.
+
+        Returns:
+            str: A string representation of the Quaternion.
+
+        """
+        return f"Quaternion({self.s}, [{self.x}, {self.y}, {self.z}])"
+
+    def __repr__(self) -> str:
+        return f"Quaternion({self.s}, [{self.x}, {self.y}, {self.z}])"

ncca/ngl/random.py

@@ -0,0 +1,167 @@
+"""
+A module to replicate the functionality of the NGL C++ Random class.
+"""
+
+import random
+import time
+
+from .vec2 import Vec2
+from .vec3 import Vec3
+from .vec4 import Vec4
+
+
+class Random:
+    _float_generators = {
+        "RandomFloat": lambda: random.uniform(-1.0, 1.0),
+        "RandomPositiveFloat": lambda: random.uniform(0.0, 1.0),
+    }
+
+    _int_generators = {}
+
+    @staticmethod
+    def set_seed():
+        """set the seed using std::time(NULL)"""
+        random.seed(int(time.time()))
+
+    @staticmethod
+    def set_seed_value(value: int):
+        """set the seed using a param value
+        Args:
+            value (int): the seed value
+        """
+        random.seed(value)
+
+    @staticmethod
+    def get_float_from_generator_name(name: str) -> float:
+        """gets a pre-generated float value for a genetator
+        Args:
+            name (str): the name of the generator to use for the number
+        Returns:
+            a random number created by the generator or 0 if the generator is not found
+        """
+        if name in Random._float_generators:
+            return Random._float_generators[name]()
+        return 0.0
+
+    @staticmethod
+    def get_int_from_generator_name(name: str) -> int:
+        """gets a pre-generated int value for a genetator
+        Args:
+            name (str): the name of the generator to use for the number
+        Returns:
+            a random number created by the generator or 0 if the generator is not found
+        """
+        if name in Random._int_generators:
+            return Random._int_generators[name]()
+        return 0
+
+    @staticmethod
+    def add_int_generator(name: str, generator):
+        """add a generator to the int generators
+        Args:
+            name (str): the name of the generator to use for the number
+            generator : the generator to add should be a callable function
+        """
+        Random._int_generators[name] = generator
+
+    @staticmethod
+    def add_float_generator(name: str, generator):
+        """add a generator to the float generators
+        Args:
+            name (str): the name of the generator to use for the number
+            generator : the generator to add should be a callable function
+        """
+        Random._float_generators[name] = generator
+
+    @staticmethod
+    def get_random_vec4() -> Vec4:
+        """get a random vector with componets ranged from +/- 1"""
+        gen = Random._float_generators["RandomFloat"]
+        return Vec4(gen(), gen(), gen(), 0.0)
+
+    @staticmethod
+    def get_random_colour4() -> Vec4:
+        """get a random colour with components ranged from 0-1"""
+        gen = Random._float_generators["RandomPositiveFloat"]
+        return Vec4(gen(), gen(), gen(), 1.0)
+
+    @staticmethod
+    def get_random_colour3() -> Vec3:
+        """get a random colour with components ranged from 0-1"""
+        gen = Random._float_generators["RandomPositiveFloat"]
+        return Vec3(gen(), gen(), gen())
+
+    @staticmethod
+    def get_random_normalized_vec4() -> Vec4:
+        """get a random vector with componets ranged from +/- 1 and Normalized"""
+        gen = Random._float_generators["RandomFloat"]
+        v = Vec4(gen(), gen(), gen(), 0.0)
+        v.normalize()
+        return v
+
+    @staticmethod
+    def get_random_vec3() -> Vec3:
+        """get a random vector with componets ranged from +/- 1"""
+        gen = Random._float_generators["RandomFloat"]
+        return Vec3(gen(), gen(), gen())
+
+    @staticmethod
+    def get_random_normalized_vec3() -> Vec3:
+        """get a random vector with componets ranged from +/- 1 and Normalized"""
+        gen = Random._float_generators["RandomFloat"]
+        v = Vec3(gen(), gen(), gen())
+        v.normalize()
+        return v
+
+    @staticmethod
+    def get_random_vec2() -> Vec2:
+        """get a random vector with componets ranged from +/- 1"""
+        gen = Random._float_generators["RandomFloat"]
+        return Vec2(gen(), gen())
+
+    @staticmethod
+    def get_random_normalized_vec2() -> Vec2:
+        """get a random vector with componets ranged from +/- 1 and Normalized"""
+        gen = Random._float_generators["RandomFloat"]
+        v = Vec2(gen(), gen())
+        v.normalize()
+        return v
+
+    @staticmethod
+    def get_random_point(
+        x_range: float = 1.0, y_range: float = 1.0, z_range: float = 1.0
+    ) -> Vec3:
+        """get a random point in 3D space defaults to +/- 1 else user defined range
+        Args:
+            x_range (float): the +/-x range
+            y_range (float): the +/-y range
+            z_range (float): the +/-z range
+        Returns:
+            a random point
+        """
+        gen = Random._float_generators["RandomFloat"]
+        return Vec3(gen() * x_range, gen() * y_range, gen() * z_range)
+
+    @staticmethod
+    def random_number(mult: float = 1.0) -> float:
+        """a replacement for the old RandomNumber func
+        this is basically a convinience function
+        Args:
+            mult (float): an optional multiplyer for the output
+        Returns:
+            (uniform_random(-1-0-+1) * mult)
+        """
+        gen = Random._float_generators["RandomFloat"]
+        return gen() * mult
+
+    @staticmethod
+    def random_positive_number(mult: float = 1.0) -> float:
+        """a replacement for the old ReandomPosNum
+        this is basically a convinience function
+        Args:
+            mult (float): an optional multiplyer for the output
+        Returns:
+            (uniform_random(0-1) * mult)
+        """
+        gen = Random._float_generators["RandomPositiveFloat"]
+        return gen() * mult