ncca-ngl 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

ncca/ngl/pyside_event_handling_mixin.py

@@ -1,318 +0,0 @@
-#!/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

@@ -1,112 +0,0 @@
-"""
-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

@@ -1,167 +0,0 @@
-"""
-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