ncca-ngl 0.3.5__py3-none-any.whl → 0.5.1__py3-none-any.whl

ncca/ngl/vec3.py

@@ -1,410 +1,120 @@
 """
 Simple float only Vec3 class for 3D graphics, very similar to the pyngl ones
+NumPy-based implementation with VectorBase inheritance for code reuse.
 """
 
-import ctypes
 import math
+from typing import Union
 
 import numpy as np
 
-from .util import clamp, hash_combine
+from .util import clamp
+from .vector_base import VectorBase, _create_properties
 
 
-class Vec3:
+class Vec3(VectorBase["Vec3"]):
     """
-    A simple 3D vector class for 3D graphics, I use slots to fix the attributes to x,y,z
+    A simple 3D vector class for 3D graphics, using numpy for efficient operations.
+
     Attributes:
         x (float): The x-coordinate of the vector.
         y (float): The y-coordinate of the vector.
         z (float): The z-coordinate of the vector.
-
     """
 
-    __slots__ = ["_x", "_y", "_z"]  # fix the attributes to x,y,z
-
-    def __init__(self, x=0.0, y=0.0, z=0.0):
-        """
-        Initializes a new instance of the Vec3 class.
-
-        Args:
-            x (float, optional): The x-coordinate of the vector. Defaults to 0.0.
-            y (float, optional): The y-coordinate of the vector. Defaults to 0.0.
-            z (float, optional): The z-coordinate of the vector. Defaults to 0.0.
-        """
-        self._x = x  # x component of vector : float
-        self._y = y  # y component of vector : float
-        self._z = z  # z component of vector : float
-
-    @classmethod
-    def sizeof(cls):
-        return 3 * ctypes.sizeof(ctypes.c_float)
-
-    def __hash__(self):
-        # Use 32-bit float element hashes, then combine
-        seed = 0
-        for v in (self.x, self.y, self.z):
-            # ensure 32-bit float semantics
-            h = hash(float(np.float32(v)))
-            seed = hash_combine(seed, h)
-        return seed
-
-    def __iter__(self):
-        """
-        Make the Vec3 class iterable.
-        Yields:
-            float: The x, y, and z components of the vector.
-        """
-        yield self.x
-        yield self.y
-        yield self.z
-
-    def __getitem__(self, index):
-        """
-        Get the component of the vector at the given index.
-        Args:
-            index (int): The index of the component (0 for x, 1 for y, 2 for z).
-        Returns:
-            float: The value of the component at the given index.
-        Raises:
-            IndexError: If the index is out of range.
-        """
-        components = [self.x, self.y, self.z]
-        try:
-            return components[index]
-        except IndexError:
-            raise IndexError("Index out of range. Valid indices are 0, 1, and 2.")
-
-    def _validate_and_set(self, v, name):
-        """
-        check if v is a float or int
-        Args:
-            v (number): The value to check.
-        Raises:
-            ValueError: If v is not a float or int.
-        """
-        if not isinstance(v, (int, float, np.float32)):
-            raise ValueError("need float or int")
-        else:
-            setattr(self, name, v)
-
-    def copy(self) -> "Vec3":
-        """
-        Create a copy of the current vector.
-        Returns:
-            Vec3: A new instance of Vec3 with the same x, y, and z values.
-        """
-        return Vec3(self.x, self.y, self.z)
-
-    def __add__(self, rhs):
-        """
-        vector addition a+b
-
-        Args:
-            rhs (Vec3): The right-hand side vector to add.
-        Returns:
-            Vec3: A new vector that is the result of adding this vector and the rhs vector.
-        """
-        r = Vec3()
-        r.x = self.x + rhs.x
-        r.y = self.y + rhs.y
-        r.z = self.z + rhs.z
-        return r
-
-    def __iadd__(self, rhs):
-        """
-        vector addition a+=b
+    DIMENSION = 3
+    COMPONENT_NAMES = ("x", "y", "z")
+    DEFAULT_VALUES = (0.0, 0.0, 0.0)
 
-        Args:
-            rhs (Vec3): The right-hand side vector to add.
-        Returns:
-            Vec3: returns this vector after adding the rhs vector.
-        """
-        self.x += rhs.x
-        self.y += rhs.y
-        self.z += rhs.z
-        return self
+    __slots__ = ["_data"]
 
-    def __sub__(self, rhs):
+    def cross(self, rhs: "Vec3") -> "Vec3":
         """
-        vector subtraction a-b
+        Cross product of two vectors a x b.
 
-        Args:
-            rhs (Vec3): The right-hand side vector to subtract.
-        Returns:
-            Vec3: A new vector that is the result of subtracting this vector and the rhs vector.
-        """
-        r = Vec3()
-        r.x = self.x - rhs.x
-        r.y = self.y - rhs.y
-        r.z = self.z - rhs.z
-        return r
-
-    def __isub__(self, rhs):
-        """
-        vector subtraction a-=b
-
-        Args:
-            rhs (Vec3): The right-hand side vector to add.
-        Returns:
-            Vec3: returns this vector after subtracting the rhs vector.
-        """
-        self.x -= rhs.x
-        self.y -= rhs.y
-        self.z -= rhs.z
-        return self
-
-    def __eq__(self, rhs):
-        """
-        vector comparison a==b using math.isclose not we only compare to 6 decimal places
-        Args:
-            rhs (Vec3): The right-hand side vector to compare.
-        Returns:
-            bool: True if the vectors are close, False otherwise.
-            NotImplemented: If the right-hand side is not a Vec3.
-        """
-
-        if not isinstance(rhs, Vec3):
-            return NotImplemented
-        return math.isclose(self.x, rhs.x) and math.isclose(self.y, rhs.y) and math.isclose(self.z, rhs.z)
-
-    def __neq__(self, rhs):
-        """
-        vector comparison a!=b using math.isclose not we only compare to 6 decimal places
-        Args:
-            rhs (Vec3): The right-hand side vector to compare.
-        Returns:
-            bool: True if the vectors are not close, False otherwise.
-            NotImplemented: If the right-hand side is not a Vec3.
-        """
-        if not isinstance(rhs, Vec3):
-            return NotImplemented
-        return not (math.isclose(self.x, rhs.x) and math.isclose(self.y, rhs.y) and math.isclose(self.z, rhs.z))
-
-    def __neg__(self):
-        """
-        negate a vector -a
-        """
-        self.x = -self.x
-        self.y = -self.y
-        self.z = -self.z
-        return self
-
-    def set(self, x, y, z):
-        """
-        set the x,y,z values of the vector
-        Args:
-            x (float): The x-coordinate of the vector.
-            y (float): The y-coordinate of the vector.
-            z (float): The z-coordinate of the vector.
-        Raises :
-            ValueError: if x,y,z are not float
-        """
-        try:
-            self.x = float(x)
-            self.y = float(y)
-            self.z = float(z)
-        except ValueError:
-            raise ValueError(f"Vec3.set {x=} {y=} {z=} all need to be float")
-
-    def dot(self, rhs):
-        """
-        dot product of two vectors a.b
-        Args:
-            rhs (Vec3): The right-hand side vector to dot product with.
-        """
-        return self.x * rhs.x + self.y * rhs.y + self.z * rhs.z
-
-    def length(self):
-        """
-        length of vector
-        Returns:
-            float: The length of the vector.
-        """
-        return math.sqrt(self.x**2 + self.y**2 + self.z**2)
-
-    def length_squared(self):
-        """
-        length of vector squared sometimes used to avoid the sqrt for performance
-        Returns:
-            float: The length of the vector squared
-        """
-        return self.x**2 + self.y**2 + self.z**2
-
-    def inner(self, rhs):
-        """
-        inner product of two vectors a.b
-        Args:
-            rhs (Vec3): The right-hand side vector to inner product with.
-        Returns:
-            float: The inner product of the two vectors.
-        """
-        return (self.x * rhs.x) + (self.y * rhs.y) + (self.z * rhs.z)
-
-    def null(self):
-        """
-        set the vector to zero
-        """
-        self.x = 0.0
-        self.y = 0.0
-        self.z = 0.0
-
-    def cross(self, rhs):
-        """
-        cross product of two vectors a x b
         Args:
             rhs (Vec3): The right-hand side vector to cross product with.
+
         Returns:
             Vec3: A new vector that is the result of the cross product.
         """
-        return Vec3(
-            self.y * rhs.z - self.z * rhs.y,
-            self.z * rhs.x - self.x * rhs.z,
-            self.x * rhs.y - self.y * rhs.x,
-        )
+        result = Vec3()
+        result._data = np.cross(self._data, rhs._data)
+        return result
 
-    def normalize(self):
+    def reflect(self, n: "Vec3") -> "Vec3":
         """
-        normalize the vector to unit length
-        Returns:
-            Vec3: A new vector that is the result of normalizing this vector.
-        Raises:
-            ZeroDivisionError: If the length of the vector is zero.
-        """
-        vector_length = self.length()
-        try:
-            self.x /= vector_length
-            self.y /= vector_length
-            self.z /= vector_length
-        except ZeroDivisionError:
-            raise ZeroDivisionError(
-                f"Vec3.normalize {vector_length} length is zero most likely calling normalize on a zero vector"
-            )
-        return self
+        Reflect a vector about a normal.
 
-    def reflect(self, n):
-        """
-        reflect a vector about a normal
         Args:
             n (Vec3): The normal to reflect about.
+
         Returns:
             Vec3: A new vector that is the result of reflecting this vector about the normal.
         """
         d = self.dot(n)
-        #  I - 2.0 * dot(N, I) * N
-        return Vec3(self.x - 2.0 * d * n.x, self.y - 2.0 * d * n.y, self.z - 2.0 * d * n.z)
+        # I - 2.0 * dot(N, I) * N
+        result = Vec3()
+        result._data = self._data - 2.0 * d * n._data
+        return result
 
-    def clamp(self, low, high):
+    def outer(self, rhs: "Vec3"):
         """
-        clamp the vector to a range
-        Args:
-            low (float): The low end of the range.
-            high (float): The high end of the range.
+        Outer product of two vectors a x b.
 
-        """
-        self.x = clamp(self.x, low, high)
-        self.y = clamp(self.y, low, high)
-        self.z = clamp(self.z, low, high)
-
-    def __repr__(self):
-        "object representation for debugging"
-        return f"Vec3 [{self.x},{self.y},{self.z}]"
-
-    def __str__(self):
-        "object representation for debugging"
-        return f"[{self.x},{self.y},{self.z}]"
-
-    def outer(self, rhs):
-        """
-        outer product of two vectors a x b
         Args:
             rhs (Vec3): The right-hand side vector to outer product with.
+
         Returns:
             Mat3: A new 3x3 matrix that is the result of the outer product.
         """
         from .mat3 import Mat3
 
-        return Mat3.from_list([
-            [self.x * rhs.x, self.x * rhs.y, self.x * rhs.z],
-            [self.y * rhs.x, self.y * rhs.y, self.y * rhs.z],
-            [self.z * rhs.x, self.z * rhs.y, self.z * rhs.z],
-        ])
-
-    def __mul__(self, rhs):
-        """
-        piecewise scalar multiplication
-        Args:
-            rhs (float): The scalar to multiply by.
-        Returns:
-            Vec3: A new vector that is the result of multiplying this vector by the scalar.
-        Raises:
-            ValueError: If the right-hand side is not a float.
-        """
-        if isinstance(rhs, (float, int)):
-            return Vec3(self.x * rhs, self.y * rhs, self.z * rhs)
-        else:
-            raise ValueError(f"can only do piecewise multiplication with a scalar {rhs=}")
-
-    def __rmul__(self, rhs):
-        """
-        piecewise scalar multiplication
-        Args:
-            rhs (float): The scalar to multiply by.
-        Returns:
-            Vec3: A new vector that is the result of multiplying this vector by the scalar.
-        Raises:
-            ValueError: If the right-hand side is not a float.
-        """
-        return self * rhs
-
-    def __truediv__(self, rhs):
-        """
-        piecewise scalar division
-        Args:
-            rhs (float): The scalar to divide by.
-        Returns:
-            Vec3: A new vector that is the result of dividing this vector by the scalar.
-        Raises:
-            ValueError: If the right-hand side is not a float.
-        """
-        if isinstance(rhs, (float, int)):
-            return Vec3(self.x / rhs, self.y / rhs, self.z / rhs)
-        elif isinstance(rhs, Vec3):
-            return Vec3(self.x / rhs.x, self.y / rhs.y, self.z / rhs.z)
-        else:
-            raise ValueError(f"can only do piecewise division with a scalar {rhs=}")
+        result = Mat3()
+        result.m = np.outer(self._data, rhs._data).astype(np.float64)
+        return result
 
     def __matmul__(self, rhs):
         """
-        "Vec3 @ Mat3 matrix multiplication"
+        Vec3 @ Mat3 matrix multiplication.
+
         Args:
             rhs (Mat3): The matrix to multiply by.
+
         Returns:
             Vec3: A new vector that is the result of multiplying this vector by the matrix.
         """
-        return Vec3(
-            self.x * rhs.m[0][0] + self.y * rhs.m[1][0] + self.z * rhs.m[2][0],
-            self.x * rhs.m[0][1] + self.y * rhs.m[1][1] + self.z * rhs.m[2][1],
-            self.x * rhs.m[0][2] + self.y * rhs.m[1][2] + self.z * rhs.m[2][2],
-        )
-
-    def to_list(self):
-        return [self.x, self.y, self.z]
+        result = Vec3()
+        result._data = rhs.m.T @ self._data  # More efficient
+        return result
 
-    def to_numpy(self):
-        return np.array([self.x, self.y, self.z])
+    def set(self, *args: float) -> None:
+        """
+        Set the x,y,z values of the vector.
 
+        Args:
+            *args: Component values (x, y, z).
 
-# Helper function to create properties
-def _create_property(attr_name):
-    def getter(self):
-        return getattr(self, f"_{attr_name}")
+        Raises:
+            ValueError: If wrong number of arguments or they are not floats.
+        """
+        if len(args) != 3:
+            raise ValueError(f"Vec3.set requires 3 arguments, got {len(args)}")
+        try:
+            self._data[0] = float(args[0])
+            self._data[1] = float(args[1])
+            self._data[2] = float(args[2])
+        except ValueError:
+            raise ValueError(f"Vec3.set {args=} all need to be float")
 
-    def setter(self, value):
-        self._validate_and_set(value, f"_{attr_name}")
+    def __repr__(self) -> str:
+        """Object representation for debugging."""
+        return f"Vec3 [{self._data[0]},{self._data[1]},{self._data[2]}]"
 
-    return property(getter, setter)
+    def __str__(self) -> str:
+        """String representation of the vector."""
+        return f"[{self._data[0]},{self._data[1]},{self._data[2]}]"
 
 
-# Dynamically add properties for x, y, z
-for attr in ["x", "y", "z"]:
-    setattr(Vec3, attr, _create_property(attr))
+# Add properties for x, y, z components
+_create_properties(Vec3)

ncca/ngl/vec3_array.py

@@ -1,5 +1,6 @@
 """
 A container for ngl.Vec3 objects that mimics some of the behavior of a std::vector
+Optimized for graphics APIs with contiguous numpy storage
 """
 
 import numpy as np
@@ -9,7 +10,8 @@ from .vec3 import Vec3
 
 class Vec3Array:
     """
-    A class to hold a list of Vec3 objects and perform operations on them.
+    A class to hold Vec3 data in contiguous memory for efficient GPU transfer.
+    Internally uses a numpy array of shape (N, 3) for optimal performance.
     """
 
     def __init__(self, values=None):
@@ -22,27 +24,41 @@ class Vec3Array:
                 If an iterable, it's initialized with the Vec3s from the iterable.
                 Defaults to None (an empty array).
         """
-        self._data = []
-        if values is not None:
-            if isinstance(values, int):
-                self._data = [Vec3() for _ in range(values)]
-            else:
-                for v in values:
-                    if not isinstance(v, Vec3):
-                        raise TypeError("All elements must be of type Vec3")
-                    self._data.append(v)
+        if values is None:
+            # Empty array - start with shape (0, 3)
+            self._data = np.zeros((0, 3), dtype=np.float64)
+        elif isinstance(values, int):
+            # Initialize N default Vec3s (0, 0, 0)
+            self._data = np.zeros((values, 3), dtype=np.float64)
+        else:
+            # Initialize from iterable of Vec3 objects
+            vec_list = []
+            for v in values:
+                if not isinstance(v, Vec3):
+                    raise TypeError("All elements must be of type Vec3")
+                vec_list.append([v.x, v.y, v.z])
+            self._data = np.array(vec_list, dtype=np.float64)
 
     def __getitem__(self, index):
         """
         Get the Vec3 at the specified index.
 
         Args:
-            index (int): The index of the element.
+            index (int | slice): The index or slice of the element(s).
 
         Returns:
             Vec3: The Vec3 object at the given index.
-        """
-        return self._data[index]
+            Vec3Array: A new Vec3Array if slicing.
+        """
+        if isinstance(index, slice):
+            # Return a new Vec3Array with sliced data
+            result = Vec3Array()
+            result._data = self._data[index].copy()
+            return result
+        else:
+            # Return a single Vec3
+            row = self._data[index]
+            return Vec3(row[0], row[1], row[2])
 
     def __setitem__(self, index, value):
         """
@@ -54,7 +70,7 @@ class Vec3Array:
         """
         if not isinstance(value, Vec3):
             raise TypeError("Only Vec3 objects can be assigned")
-        self._data[index] = value
+        self._data[index] = [value.x, value.y, value.z]
 
     def __len__(self):
         """
@@ -64,9 +80,25 @@ class Vec3Array:
 
     def __iter__(self):
         """
-        Return an iterator for the array.
+        Return an iterator that yields Vec3 objects.
+        """
+        for i in range(len(self._data)):
+            row = self._data[i]
+            yield Vec3(row[0], row[1], row[2])
+
+    def __eq__(self, other):
+        """
+        Compare two Vec3Array instances for equality.
+
+        Args:
+            other: Another Vec3Array instance to compare with.
+
+        Returns:
+            bool: True if the arrays contain the same data, False otherwise.
         """
-        return iter(self._data)
+        if not isinstance(other, Vec3Array):
+            return NotImplemented
+        return np.array_equal(self._data, other._data)
 
     def append(self, value):
         """
@@ -77,7 +109,8 @@ class Vec3Array:
         """
         if not isinstance(value, Vec3):
             raise TypeError("Only Vec3 objects can be appended")
-        self._data.append(value)
+        new_row = np.array([[value.x, value.y, value.z]], dtype=np.float64)
+        self._data = np.vstack([self._data, new_row])
 
     def extend(self, values):
         """
@@ -89,10 +122,17 @@ class Vec3Array:
         Raises:
             TypeError: If any element in values is not a Vec3.
         """
+        vec_list = []
         for v in values:
             if not isinstance(v, Vec3):
                 raise TypeError("All elements must be of type Vec3")
-            self._data.append(v)
+            vec_list.append([v.x, v.y, v.z])
+
+        new_rows = np.array(vec_list, dtype=np.float64)
+        if len(self._data) == 0:
+            self._data = new_rows
+        else:
+            self._data = np.vstack([self._data, new_rows])
 
     def to_list(self):
         """
@@ -101,22 +141,35 @@ class Vec3Array:
         Returns:
             list: A list of x, y, z components concatenated.
         """
-        return [comp for vec in self._data for comp in vec]
+        return self._data.flatten().tolist()
 
     def to_numpy(self):
         """
         Convert the array of Vec3 objects to a numpy array.
+        This is the primary method for GPU data transfer.
+
+        Returns:
+            numpy.ndarray: A float32 numpy array of shape (N*3,) for GPU transfer.
+        """
+        return self._data.astype(np.float32).flatten()
+
+    def get_array(self):
+        """
+        Get the underlying numpy array in shape (N, 3).
+        Useful for vectorized operations.
 
         Returns:
-            numpy.ndarray: A numpy array of the vector data.
+            numpy.ndarray: The internal float64 array of shape (N, 3).
         """
-        return np.array(self.to_list(), dtype=np.float32)
+        return self._data
 
     def __repr__(self):
-        return f"Vec3Array({self._data!r})"
+        vec_list = [Vec3(row[0], row[1], row[2]) for row in self._data]
+        return f"Vec3Array({vec_list!r})"
 
     def __str__(self):
-        return str(self._data)
+        vec_list = [Vec3(row[0], row[1], row[2]) for row in self._data]
+        return str(vec_list)
 
     def sizeof(self):
         """