ncca-ngl 0.3.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

ncca/ngl/vec4.py

@@ -1,229 +1,129 @@
 """
-Simple Float only Vec3 class for 3D graphics, very similar to the pyngl ones
+Simple Float only Vec4 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 .log import logger
+from .util import clamp
+from .vector_base import VectorBase, _create_properties
 
 
-class Vec4:
-    __slots__ = ["_x", "_y", "_z", "_w"]
-    "by using slots we fix our class attributes to x,y,z,w"
+class Vec4(VectorBase["Vec4"]):
+    """
+    A simple 4D vector class for graphics, using numpy for efficient operations.
 
-    def __init__(self, x=0.0, y=0.0, z=0.0, w=1.0):
-        """simple ctor"""
-        self._x = x  # x component of vector : float
-        self._y = y  # y component of vector : float
-        self._z = z  # z component of vector : float
-        self._w = w  # w component of vector : float
+    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.
+        w (float): The w-coordinate of the vector.
+    """
 
-    @classmethod
-    def sizeof(cls):
-        return 4 * ctypes.sizeof(ctypes.c_float)
+    DIMENSION = 4
+    COMPONENT_NAMES = ("x", "y", "z", "w")
+    DEFAULT_VALUES = (0.0, 0.0, 0.0, 1.0)
 
-    def _validate_and_set(self, v, name):
+    __slots__ = ["_data"]
+
+    def cross(self, rhs: "Vec4") -> "Vec4":
         """
-        check if v is a float or int
+        Cross product of two vectors a x b (4D version uses first 3 components).
+
         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)
+            rhs (Vec4): The right-hand side vector to cross product with.
 
-    def __iter__(self):
-        """
-        Make the Vec3 class iterable.
-        Yields:
-            float: The x, y, and z components of the vector.
+        Returns:
+            Vec4: A new vector that is the result of the cross product.
         """
-        yield self.x
-        yield self.y
-        yield self.z
-        yield self.w
+        result = Vec4()
+        # Cross product only makes sense for 3D vectors, use first 3 components
+        result._data[:3] = np.cross(self._data[:3], rhs._data[:3])
+        result._data[3] = 0.0
+        return result
 
-    def __getitem__(self, index):
+    def reflect(self, n: "Vec4") -> "Vec4":
         """
-        Get the component of the vector at the given index.
+        Reflect a vector about a normal.
+
         Args:
-            index (int): The index of the component (0 for x, 1 for y, 2 for z).
+            n (Vec4): The normal to reflect about.
+
         Returns:
-            float: The value of the component at the given index.
-        Raises:
-            IndexError: If the index is out of range.
+            Vec4: A new vector that is the result of reflecting this vector about the normal.
         """
-        components = [self.x, self.y, self.z, self.w]
-        try:
-            return components[index]
-        except IndexError:
-            raise IndexError("Index out of range. Valid indices are 0, 1, 2, and 3.")
+        d = self.dot(n)
+        # I - 2.0 * dot(N, I) * N
+        result = Vec4()
+        result._data = self._data - 2.0 * d * n._data
+        return result
 
-    def copy(self) -> "Vec4":
+    def outer(self, rhs: "Vec4"):
         """
-        Create a copy of the vector.
+        Outer product of two vectors a x b.
+
+        Args:
+            rhs (Vec4): The right-hand side vector to outer product with.
+
         Returns:
-            Vec4: A new Vec4 instance with the same values.
+            Mat4: A new 4x4 matrix that is the result of the outer product.
         """
-        return Vec4(self.x, self.y, self.z, self.w)
-
-    def __add__(self, rhs):
-        "return a+b vector addition"
-        r = Vec4()
-        r.x = self.x + rhs.x
-        r.y = self.y + rhs.y
-        r.z = self.z + rhs.z
-        r.w = self.w + rhs.w
-        return r
-
-    def __iadd__(self, rhs):
-        "return a+=b vector addition"
-        self.x += rhs.x
-        self.y += rhs.y
-        self.z += rhs.z
-        self.w += rhs.w
-
-        return self
-
-    def __sub__(self, rhs):
-        "return a+b vector addition"
-        r = Vec4()
-        r.x = self.x - rhs.x
-        r.y = self.y - rhs.y
-        r.z = self.z - rhs.z
-        r.w = self.w - rhs.w
-        return r
-
-    def __isub__(self, rhs):
-        "return a+=b vector addition"
-        self.x -= rhs.x
-        self.y -= rhs.y
-        self.z -= rhs.z
-        self.w -= rhs.w
-        return self
-
-    def set(self, x, y, z, w=1.0):
-        "set from x,y,z,w will convert to float an raise value error if problem"
-        try:
-            self.x = float(x)
-            self.y = float(y)
-            self.z = float(z)
-            self.w = float(w)
-        except ValueError:
-            logger.warning("need float values")
-            raise
+        from .mat4 import Mat4
 
-    def dot(self, rhs):
-        return (self.x * rhs.x) + (self.y * rhs.y) + (self.z * rhs.z) + (self.w * rhs.w)
+        result = Mat4()
+        result.m = np.outer(self._data, rhs._data).astype(np.float64)
+        return result
 
-    def length(self):
-        "length of vector"
-        return math.sqrt(self.x**2 + self.y**2 + self.z**2 + self.w**2)
-
-    def length_squared(self):
-        "square length of vector"
-        return self.x**2 + self.y**2 + self.z**2 + self.w**2
+    def __matmul__(self, rhs):
+        """
+        Vec4 @ Mat4 matrix multiplication.
 
-    def normalize(self):
-        "normalize this vector"
-        length = self.length()
-        try:
-            self.x /= length
-            self.y /= length
-            self.z /= length
-            self.w /= length
-        except ZeroDivisionError:
-            raise ZeroDivisionError("cannot normalize the zero vector")
-        return self
-
-    def __eq__(self, rhs):
-        "test a==b using math.isclose"
-        if not isinstance(rhs, Vec4):
-            return NotImplemented
-        return (
-            math.isclose(self.x, rhs.x)
-            and math.isclose(self.y, rhs.y)
-            and math.isclose(self.z, rhs.z)
-            and math.isclose(self.w, rhs.w)
-        )
-
-    def __neq__(self, rhs):
-        "test a!=b using math.isclose"
-        if not isinstance(rhs, Vec4):
-            return NotImplemented
-        return not (
-            math.isclose(self.x, rhs.x)
-            and math.isclose(self.y, rhs.y)
-            and math.isclose(self.z, rhs.z)
-            and math.isclose(self.w, rhs.w)
-        )
-
-    def __neg__(self):
-        self.x = -self.x
-        self.y = -self.y
-        self.z = -self.z
-        self.w = -self.w
-        return self
-
-    def __mul__(self, rhs):
-        if isinstance(rhs, (float, int)):
-            "Vec4 * scalar multiplication"
-            return Vec4(self.x * rhs, self.y * rhs, self.z * rhs, self.w * rhs)
-        else:
-            raise ValueError
-
-    def __rmul__(self, rhs):
-        return self * rhs
-
-    def __truediv__(self, rhs):
-        if isinstance(rhs, (float, int)):
-            return Vec4(self.x / rhs, self.y / rhs, self.z / rhs, self.w / rhs)
-        elif isinstance(rhs, Vec4):
-            return Vec4(self.x / rhs.x, self.y / rhs.y, self.z / rhs.z, self.w / rhs.w)
-        else:
-            raise ValueError(f"can only do piecewise division with a scalar {rhs=}")
+        Args:
+            rhs (Mat4): The matrix to multiply by.
 
-    def __matmul__(self, rhs):
-        "Vec4 @ Mat4 matrix multiplication"
-        return Vec4(
-            self.x * rhs.m[0][0] + self.y * rhs.m[1][0] + self.z * rhs.m[2][0] + self.w * rhs.m[3][0],
-            self.x * rhs.m[0][1] + self.y * rhs.m[1][1] + self.z * rhs.m[2][1] + self.w * rhs.m[3][1],
-            self.x * rhs.m[0][2] + self.y * rhs.m[1][2] + self.z * rhs.m[2][2] + self.w * rhs.m[3][2],
-            self.x * rhs.m[0][3] + self.y * rhs.m[1][3] + self.z * rhs.m[2][3] + self.w * rhs.m[3][3],
-        )
+        Returns:
+            Vec4: A new vector that is the result of multiplying this vector by the matrix.
+        """
+        return Vec4(*self._data @ rhs.m)
 
-    def __repr__(self):
-        "repr for debugging purposes"
-        return f"Vec4 [{self.x},{self.y},{self.z},{self.w}]"
+    def set(self, *args: float) -> None:
+        """
+        Set the x,y,z,w values of the vector.
 
-    def __str__(self):
-        "print out the vector as a string"
-        return f"[{self.x},{self.y},{self.z},{self.w}]"
+        Args:
+            *args: Component values (x, y, z, w). w defaults to 1.0 if not provided.
 
-    def to_list(self):
-        return [self.x, self.y, self.z, self.w]
+        Raises:
+            ValueError: If wrong number of arguments or they are not floats.
+        """
+        if len(args) == 3:
+            # Allow (x, y, z) with default w=1.0 for backward compatibility
+            args = args + (1.0,)
+        elif len(args) != 4:
+            raise ValueError(f"Vec4.set requires 3 or 4 arguments, got {len(args)}")
 
-    def to_numpy(self):
-        return np.array([self.x, self.y, self.z, self.w])
+        try:
+            for i in range(4):
+                self._data[i] = float(args[i])
+        except ValueError:
+            raise ValueError(f"Vec4.set {args=} all need to be float")
 
+    def __repr__(self) -> str:
+        """Object representation for debugging."""
+        return f"Vec4 [{self._data[0]},{self._data[1]},{self._data[2]},{self._data[3]}]"
 
-# Helper function to create properties
-def _create_property(attr_name):
-    def getter(self):
-        return getattr(self, f"_{attr_name}")
+    def __str__(self) -> str:
+        """String representation of the vector."""
 
-    def setter(self, value):
-        self._validate_and_set(value, f"_{attr_name}")
+        # Format numbers without decimal point if they're whole numbers
+        def fmt(val):
+            return str(int(val)) if val == int(val) else str(val)
 
-    return property(getter, setter)
+        return f"[{fmt(self._data[0])},{fmt(self._data[1])},{fmt(self._data[2])},{fmt(self._data[3])}]"
 
 
-# Dynamically add properties for x, y, z,w
-for attr in ["x", "y", "z", "w"]:
-    setattr(Vec4, attr, _create_property(attr))
+# Add properties for x, y, z, w components
+_create_properties(Vec4)

ncca/ngl/vec4_array.py

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