e2D 1.4.19__tar.gz → 1.4.23__tar.gz

{e2d-1.4.19 → e2d-1.4.23}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Riccardo Mariani
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Riccardo Mariani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{e2d-1.4.19 → e2d-1.4.23}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: e2D
-Version: 1.4.19
+Version: 1.4.23
 Summary: Python library for 2D games. Streamlines dev with keyboard/mouse input, vector calculations, color manipulation, and collision detection. Simplify game creation and unleash creativity!
 Home-page: https://github.com/marick-py/e2D
 Author: Riccardo Mariani
@@ -13,6 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: pygame
+Dynamic: license-file
 
 # e2D
 ## A Python Game Development Library

{e2d-1.4.19 → e2d-1.4.23}/e2D/__init__.py

@@ -10,6 +10,7 @@ PI_QUARTER = PI/4
 PI_DOUBLE = PI*2
 
 sign = lambda val: -1 if val < 0 else (1 if val > 0 else 0)
+clamp = lambda x, minn, maxx: x if x > minn and x < maxx else (minn if x < minn else maxx)
 
 class Vector2D:
     round_values_on_print = 2
@@ -34,29 +35,71 @@ class Vector2D:
     @angle.setter
     def angle(self, new_angle) -> None:
         self.rotate(new_angle - self.angle)
+    
+    @property
+    def aspect_x(self) -> float:
+        return self.x / self.y if self.y != 0 else 0
+
+    @aspect_x.setter
+    def aspect_x(self, new_aspect) -> None:
+        self.x = self.y * new_aspect
 
     @property
+    def aspect_y(self) -> float:
+        return self.y / self.x if self.x != 0 else 0
+
+    @aspect_y.setter
+    def aspect_y(self, new_aspect) -> None:
+        self.y = self.x * new_aspect
+
     def copy(self) -> "Vector2D":
         return Vector2D(self.x, self.y)
 
     @property
     def sign(self) -> "Vector2D":
         return Vector2D(sign(self.x), sign(self.y))
+    
+    def clamp(self, min_val: Vector2D, max_val: Vector2D) -> "Vector2D":
+        return Vector2D(clamp(self.x, min_val.x, max_val.x), clamp(self.y, min_val.y, max_val.y))
+
+    def iclamp(self, min_val: Vector2D, max_val: Vector2D) -> None:
+        self.x = clamp(self.x, min_val.x, max_val.x)
+        self.y = clamp(self.y, min_val.y, max_val.y)
 
     @property
-    def normalize(self) -> "Vector2D":
+    def normalized(self) -> "Vector2D":
         if (mag:=self.length) == 0:
-            return self.copy
+            return self.copy()
         return Vector2D(self.x / mag, self.y / mag)
 
     @property
     def length(self) -> float:
         return (self.x ** 2 + self.y ** 2) ** .5
-    
+
+    @length.setter
+    def length(self, new_length: float) -> None:
+        current_length = self.length
+        if current_length == 0:
+            self.x = new_length
+            self.y = 0
+        else:
+            self.x *= new_length / current_length
+            self.y *= new_length / current_length
+
     @property
     def length_sqrd(self) -> float:
         return self.x ** 2 + self.y ** 2
-    
+
+    @length_sqrd.setter
+    def length_sqrd(self, new_length_sqrd: float) -> None:
+        current_length = self.length
+        if current_length == 0:
+            self.x = _mt.sqrt(new_length_sqrd)
+            self.y = 0
+        else:
+            self.x *= _mt.sqrt(new_length_sqrd) / current_length
+            self.y *= _mt.sqrt(new_length_sqrd) / current_length
+
     @property
     def inverse(self) -> "Vector2D":
         return self.mult(-1)
@@ -111,6 +154,13 @@ class Vector2D:
     def complex_to_cartesian(cls, complex_n) -> "Vector2D":
         return cls(complex_n.real, complex_n.imag)
 
+    def cartesian_to_linear(self, size) -> int:
+        return int(self.x + self.y * size)
+
+    @classmethod
+    def linear_to_cartesian(cls, linear, size) -> "Vector2D":
+        return cls(linear % size, linear // size)
+
     def lerp(self, other, t=.1) -> "Vector2D":
         return Vector2D(self.x + (other.x - self.x) * t, self.y + (other.y - self.y) * t)
 
@@ -420,47 +470,47 @@ class Vector2D:
     def down_left_norm(cls) -> "Vector2D": return V2down_left_norm
 
     @classmethod
-    def new_zero(cls) -> "Vector2D": return V2zero.copy
+    def new_zero(cls) -> "Vector2D": return V2zero.copy()
     @classmethod
-    def new_one(cls) -> "Vector2D": return V2one.copy
+    def new_one(cls) -> "Vector2D": return V2one.copy()
     @classmethod
-    def new_two(cls) -> "Vector2D": return V2two.copy
+    def new_two(cls) -> "Vector2D": return V2two.copy()
     @classmethod
-    def new_pi(cls) -> "Vector2D": return V2pi.copy
+    def new_pi(cls) -> "Vector2D": return V2pi.copy()
     @classmethod
-    def new_inf(cls) -> "Vector2D": return V2inf.copy
+    def new_inf(cls) -> "Vector2D": return V2inf.copy()
     @classmethod
-    def new_neg_one(cls) -> "Vector2D": return V2neg_one.copy
+    def new_neg_one(cls) -> "Vector2D": return V2neg_one.copy()
     @classmethod
-    def new_neg_two(cls) -> "Vector2D": return V2neg_two.copy
+    def new_neg_two(cls) -> "Vector2D": return V2neg_two.copy()
     @classmethod
-    def new_neg_pi(cls) -> "Vector2D": return V2neg_pi.copy
+    def new_neg_pi(cls) -> "Vector2D": return V2neg_pi.copy()
     @classmethod
-    def new_neg_inf(cls) -> "Vector2D": return V2neg_inf.copy
+    def new_neg_inf(cls) -> "Vector2D": return V2neg_inf.copy()
     @classmethod
-    def new_up(cls) -> "Vector2D": return V2up.copy
+    def new_up(cls) -> "Vector2D": return V2up.copy()
     @classmethod
-    def new_right(cls) -> "Vector2D": return V2right.copy
+    def new_right(cls) -> "Vector2D": return V2right.copy()
     @classmethod
-    def new_down(cls) -> "Vector2D": return V2down.copy
+    def new_down(cls) -> "Vector2D": return V2down.copy()
     @classmethod
-    def new_left(cls) -> "Vector2D": return V2left.copy
+    def new_left(cls) -> "Vector2D": return V2left.copy()
     @classmethod
-    def new_up_right(cls) -> "Vector2D": return V2up_right.copy
+    def new_up_right(cls) -> "Vector2D": return V2up_right.copy()
     @classmethod
-    def new_down_right(cls) -> "Vector2D": return V2down_right.copy
+    def new_down_right(cls) -> "Vector2D": return V2down_right.copy()
     @classmethod
-    def new_up_left(cls) -> "Vector2D": return V2up_left.copy
+    def new_up_left(cls) -> "Vector2D": return V2up_left.copy()
     @classmethod
-    def new_down_left(cls) -> "Vector2D": return V2down_left.copy
+    def new_down_left(cls) -> "Vector2D": return V2down_left.copy()
     @classmethod
-    def new_up_right_norm(cls) -> "Vector2D": return V2up_right_norm.copy
+    def new_up_right_norm(cls) -> "Vector2D": return V2up_right_norm.copy()
     @classmethod
-    def new_down_right_norm(cls) -> "Vector2D": return V2down_right_norm.copy
+    def new_down_right_norm(cls) -> "Vector2D": return V2down_right_norm.copy()
     @classmethod
-    def new_up_left_norm(cls) -> "Vector2D": return V2up_left_norm.copy
+    def new_up_left_norm(cls) -> "Vector2D": return V2up_left_norm.copy()
     @classmethod
-    def new_down_left_norm(cls) -> "Vector2D": return V2down_left_norm.copy
+    def new_down_left_norm(cls) -> "Vector2D": return V2down_left_norm.copy()
 
 
 V2 = Vector2D
@@ -487,10 +537,10 @@ V2down_right = Vector2D(1, -1)
 V2up_left = Vector2D(-1, 1)
 V2down_left = Vector2D(-1, -1)
 
-V2up_right_norm = V2up_right.normalize
-V2down_right_norm = V2down_right.normalize
-V2up_left_norm = V2up_left.normalize
-V2down_left_norm = V2down_left.normalize
+V2up_right_norm = V2up_right.normalized
+V2down_right_norm = V2down_right.normalized
+V2up_left_norm = V2up_left.normalized
+V2down_left_norm = V2down_left.normalized
 
 VECTORS_4_DIRECTIONS = (V2right, V2down, V2left, V2up)
 VECTORS_4_SEMIDIRECTIONS = (V2down_right, V2down_left, V2up_left, V2up_right)

{e2d-1.4.19 → e2d-1.4.23}/e2D/__init__.pyi

@@ -12,6 +12,7 @@ PI_DOUBLE : float
 # 
 
 sign : Callable[[int|float], Literal[-1,0,1]]
+clamp: Callable[[int|float, int|float, int|float], int|float]
 
 class Vector2D:
     round_values_on_print : int|float
@@ -140,12 +141,60 @@ class Vector2D:
         ...
 
     @property
-    def angle(self:"Vector2D") -> int|float: ...
+    def angle(self:"Vector2D") -> int|float:
+        """
+        # Vector Angle
+        ## Returns:
+            float: The angle (in radians) of the vector from the positive x-axis.
+        ## Example:
+            v = Vector2D(1, 1)
+            angle = v.angle
+            print(angle)  # Output: 0.7853981633974483
+        ## Explanation:
+            This property calculates the angle of the vector from the positive x-axis using the `atan2` function.
+        """
+        ...
 
     @angle.setter
-    def angle(self:"Vector2D", argv) -> None: ...
+    def angle(self:"Vector2D", argv) -> None:
+        ...
+
+    @property
+    def aspect_x(self: "Vector2D") -> float:
+        """
+        # Aspect Ratio (X over Y)
+        ## Returns:
+            float: The aspect ratio of the vector, calculated as the x component divided by the y component. Returns 0 if the y component is zero.
+        ## Example:
+            v = Vector2D(4, 2)
+            aspect = v.aspect_x
+            print(aspect)  # Output: 2.0
+        ## Explanation:
+            This property computes the ratio of the x component to the y component of the vector. If the y component is zero, it returns 0 to avoid division by zero.
+        """
+        ...
+
+    @aspect_x.setter
+    def aspect_x(self: "Vector2D", new_aspect) -> None: ...
 
     @property
+    def aspect_y(self: "Vector2D") -> float:
+        """
+        # Aspect Ratio (Y over X)
+        ## Returns:
+            float: The aspect ratio of the vector, calculated as the y component divided by the x component. Returns 0 if the x component is zero.
+        ## Example:
+            v = Vector2D(2, 4)
+            aspect = v.aspect_y
+            print(aspect)  # Output: 2.0
+        ## Explanation:
+            This property computes the ratio of the y component to the x component of the vector. If the x component is zero, it returns 0 to avoid division by zero.
+        """
+        ...
+
+    @aspect_y.setter
+    def aspect_y(self: "Vector2D", new_aspect) -> None: ...
+
     def copy(self:"Vector2D") -> "Vector2D":
         """
         # Create a copy of the current Vector2D other.
@@ -211,8 +260,56 @@ class Vector2D:
         """
         ...
     
+    def clamp(self, min_val: Vector2D, max_val: Vector2D) -> "Vector2D":
+        """
+        # Clamp the vector's components between the corresponding components of two other vectors.
+
+        ## Parameters:
+            min_val (Vector2D): The minimum vector for clamping.
+            max_val (Vector2D): The maximum vector for clamping.
+
+        ## Returns:
+            Vector2D: A new vector with its components clamped between the corresponding components of `min_val` and `max_val`.
+
+        ## Example:
+            v = Vector2D(5, 10)
+            min_val = Vector2D(0, 8)
+            max_val = Vector2D(6, 12)
+            clamped_v = v.clamp(min_val, max_val)
+            print(clamped_v)  # Output: (5, 10)
+
+        ## Explanation:
+            This method clamps the x and y components of the current vector between the corresponding x and y components
+            of the `min_val` and `max_val` vectors. The resulting vector is returned as a new Vector2D instance.
+        """
+        ...
+
+    def iclamp(self, min_val: Vector2D, max_val: Vector2D) -> None:
+        """
+        # Clamp the vector's components in place between the corresponding components of two other vectors.
+
+        ## Parameters:
+            min_val (Vector2D): The minimum vector for clamping.
+            max_val (Vector2D): The maximum vector for clamping.
+
+        ## Returns:
+            None
+
+        ## Example:
+            v = Vector2D(5, 10)
+            min_val = Vector2D(0, 8)
+            max_val = Vector2D(6, 12)
+            v.iclamp(min_val, max_val)
+            print(v)  # Output: (5, 10)
+
+        ## Explanation:
+            This method clamps the x and y components of the current vector in place between the corresponding x and y components
+            of the `min_val` and `max_val` vectors. The method modifies the current vector directly.
+        """
+        ...
+    
     @property
-    def normalize(self:"Vector2D") -> "Vector2D":
+    def normalized(self:"Vector2D") -> "Vector2D":
         """
         # Vector Normalization
 
@@ -224,7 +321,7 @@ class Vector2D:
 
         ## Example:
             v = Vector2D(3, 4)
-            normalized_v = v.normalize()  # Normalize the vector (3, 4)
+            normalized_v = v.normalized()  # Normalize the vector (3, 4)
             print(normalized_v)  # Output: (0.6, 0.8)
 
         ## Explanation:
@@ -244,23 +341,123 @@ class Vector2D:
     
     @property
     def length(self:"Vector2D") -> float:
+        """
+        # Vector Length
+
+        ## Returns:
+            float: The length (magnitude) of the vector.
+
+        ## Example:
+            v = Vector2D(3, 4)
+            length = v.length
+            print(length)  # Output: 5.0
+
+        ## Explanation:
+            This property calculates the length (magnitude) of the vector using the Pythagorean theorem.
+        """
         ...
 
     @property
     def length_sqrd(self:"Vector2D") -> float:
+        """
+        # Vector Length Squared
+
+        ## Returns:
+            float: The squared length (magnitude) of the vector.
+
+        ## Example:
+            v = Vector2D(3, 4)
+            length_sqrd = v.length_sqrd
+            print(length_sqrd)  # Output: 25
+
+        ## Explanation:
+            This property calculates the squared length (magnitude) of the vector.
+            It is more efficient than calculating the actual length, as it avoids the
+            square root calculation.
+        """
         ...
     
     @property
     def inverse(self:"Vector2D") -> "Vector2D":
+        """
+        # Vector Inversion
+
+        ## Returns:
+            Vector2D: A new vector with inverted components.
+
+        ## Example:
+            v = Vector2D(3, 4)
+            inverted_v = v.inverse()
+            print(inverted_v)  # Output: (-3, -4)
+
+        ## Explanation:
+            This method calculates the inverted version of the current vector, which means a new vector with the same magnitude
+            but opposite direction.
+
+            The inverted vector is obtained by negating each component of the current vector.
+
+            The resulting inverted vector is returned.
+        """
         ...
 
     def floor(self:"Vector2D", n:"int|float|Vector2D"=1) -> "Vector2D":
+        """
+        # Round the Vector2D components down to the nearest integer or specified decimal place.
+
+        ## Parameters:
+            n (int|float|Vector2D, optional): The decimal place to round down to. Default is 1.
+
+        ## Returns:
+            Vector2D: A new vector with rounded-down components.
+
+        ## Example:
+            v = Vector2D(3.14159, 2.71828)
+            rounded_v = v.floor(2)
+            print(rounded_v)  # Output: (3.14, 2.71)
+
+        ## Explanation:
+            This method rounds each component of the vector down to the nearest integer or specified decimal place.
+        """
         ...
 
     def ceil(self:"Vector2D", n:"int|float|Vector2D"=1) -> "Vector2D":
+        """
+        # Round the Vector2D components up to the nearest integer or specified decimal place.
+
+        ## Parameters:
+            n (int|float|Vector2D, optional): The decimal place to round up to. Default is 1.
+
+        ## Returns:
+            Vector2D: A new vector with rounded-up components.
+
+        ## Example:
+            v = Vector2D(3.14159, 2.71828)
+            rounded_v = v.ceil(2)
+            print(rounded_v)  # Output: (3.15, 2.72)
+
+        ## Explanation:
+            This method rounds each component of the vector up to the nearest integer or specified decimal place.
+        """
         ...
     
     def round(self:"Vector2D", n:"int|float|Vector2D"=1) -> "Vector2D":
+        """
+        # Round the Vector2D components to the nearest integer or specified decimal place.
+
+        ## Parameters:
+            n (int|float|Vector2D, optional): The decimal place to round to. Default is 1.
+
+        ## Returns:
+            Vector2D: A new vector with rounded components.
+
+        ## Example:
+            v = Vector2D(3.14159, 2.71828)
+            rounded_v = v.round(2)
+            print(rounded_v)  # Output: (3.14, 2.72)
+
+        ## Explanation:
+            This method rounds each component of the vector to the nearest integer or specified decimal place.
+        """
         ...
 
     @classmethod
@@ -451,7 +648,65 @@ class Vector2D:
     def cartesian_to_complex(self:"Vector2D") -> complex: ...
 
     @classmethod
-    def complex_to_cartesian(cls, complex_n: complex) -> "Vector2D": ...
+    def complex_to_cartesian(cls, complex_n: complex) -> "Vector2D":
+        """
+        # Convert a Complex Number to Cartesian Coordinates
+
+        ## Parameters:
+            complex_n (complex): The complex number to convert.
+
+        ## Returns:
+            Vector2D: The corresponding (x, y) coordinates as a Vector2D.
+
+        ## Example:
+            v = Vector2D.complex_to_cartesian(3 + 4j)  # v = Vector2D(3, 4)
+
+        ## Explanation:
+            This class method converts a complex number (a + bi) to Cartesian coordinates (x, y).
+            The real part 'a' becomes the x-coordinate, and the imaginary part 'b' becomes the y-coordinate.
+        """
+        ...
+
+    def cartesian_to_linear(self:"Vector2D", size:int|float) -> int:
+        """
+        # Convert 2D Cartesian coordinates to a linear index.
+
+        ## Parameters:
+            size (int|float): The width of the grid (number of columns).
+
+        ## Returns:
+            int: The linear index corresponding to the (x, y) coordinates.
+
+        ## Example:
+            v = Vector2D(3, 2)
+            idx = v.cartesian_to_linear(5)  # idx = 3 + 2*5 = 13
+
+        ## Explanation:
+            This method converts the (x, y) coordinates of the vector to a single linear index,
+            assuming row-major order in a 2D grid of the given width.
+        """
+        ...
+
+    @classmethod
+    def linear_to_cartesian(cls, linear:int, size:int|float) -> "Vector2D":
+        """
+        # Convert a linear index to 2D Cartesian coordinates.
+
+        ## Parameters:
+            linear (int): The linear index.
+            size (int|float): The width of the grid (number of columns).
+
+        ## Returns:
+            Vector2D: The corresponding (x, y) coordinates as a Vector2D.
+
+        ## Example:
+            v = Vector2D.linear_to_cartesian(13, 5)  # v = Vector2D(3, 2)
+
+        ## Explanation:
+            This class method converts a linear index to (x, y) coordinates,
+            assuming row-major order in a 2D grid of the given width.
+        """
+        ...
 
     def lerp(self:"Vector2D", other:"int|float|Vector2D|list|tuple", t:float=.1) -> "Vector2D":
         """
@@ -1046,4 +1301,37 @@ def distance_line_point(line_point_a:Vector2D, line_point_b:Vector2D, point_c:Ve
     ...
 
 def optimize_value_string(value: int|float, precision: int) -> str:
+    """
+    # Optimize the string representation of a numeric value based on its magnitude and the specified precision.
+
+    ## Parameters:
+        value (int | float): The numeric value to be formatted.
+        precision (int): The number of decimal places or significant digits to use in the formatted string.
+
+    ## Returns:
+        str: The optimized string representation of the value.
+
+    ## Example:
+        value = 0.000012345
+        precision = 3
+        result = optimize_value_string(value, precision)
+        print(result)
+        # Output: '1.235e-05'
+
+        value = 123.456789
+        precision = 2
+        result = optimize_value_string(value, precision)
+        print(result)
+        # Output: '123.46'
+
+    ## Explanation:
+        The function formats the input value as a string, choosing between fixed-point and scientific notation
+        based on the magnitude of the value relative to the specified precision:
+            - If the absolute value is very small (less than 1 divided by 10 to the power of precision, but not zero),
+                scientific notation is used.
+            - If the absolute value is less than 10 to the power of precision, fixed-point notation is used,
+                with trailing zeros and decimal points removed for brevity.
+            - Otherwise, scientific notation is used.
+        This ensures that the string representation is concise and readable, while maintaining the requested precision.
+    """
     ...