nodebpy 0.16.0__tar.gz → 0.17.0__tar.gz

{nodebpy-0.16.0 → nodebpy-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nodebpy
-Version: 0.16.0
+Version: 0.17.0
 Summary: Build nodes trees in Blender more elegantly with code
 Author: Brady Johnston
 Author-email: Brady Johnston <brady.johnston@me.com>

{nodebpy-0.16.0 → nodebpy-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nodebpy"
-version = "0.16.0"
+version = "0.17.0"
 description = "Build nodes trees in Blender more elegantly with code"
 readme = "README.md"
 authors = [

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/builder/accessor.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal, overload
+from typing import TYPE_CHECKING, Iterator, Literal, overload
 
 import bpy
 from bpy.types import NodeSocket
@@ -200,7 +200,7 @@ class SocketAccessor:
     def __len__(self) -> int:
         return len(self._items())
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator["Socket"]:
         return iter(self._values())
 
     def __getattr__(self, name: str) -> "Socket":

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/builder/mixins.py

@@ -11,7 +11,7 @@ from ._utils import SocketError, _resolve_promotion, _SocketLike
 _RShiftT = TypeVar("_RShiftT")
 
 if TYPE_CHECKING:
-    from ..nodes.geometry import Compare, Math, MultiplyMatrices, TransformPoint
+    from ..nodes.geometry import Compare
     from ..types import InputLinkable
     from .node import BaseNode
     from .socket import (

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/builder/socket.py

@@ -3,9 +3,13 @@ from __future__ import annotations
 from typing import (
     TYPE_CHECKING,
     Any,
+    Generic,
     Iterable,
     Iterator,
+    Literal,
     Mapping,
+    NamedTuple,
+    TypeVar,
     cast,
     overload,
 )
@@ -68,14 +72,45 @@ if TYPE_CHECKING:
         IntegerMath,
         MatchString,
         Math,
-        MultiplyMatrices,
-        TransformPoint,
     )
     from ..nodes.geometry.manual import Compare
     from ..nodes.geometry.vector import VectorMath
     from .node import BaseNode
     from .tree import TreeBuilder
 
+_T = TypeVar("_T")
+
+
+class QuaternionComponents(NamedTuple):
+    """Quaternion components returned by `RotationSocket.to_quaternion()`."""
+
+    w: "FloatSocket"
+    x: "FloatSocket"
+    y: "FloatSocket"
+    z: "FloatSocket"
+
+
+class AxisAngle(NamedTuple):
+    """Axis-angle components returned by `RotationSocket.to_axis_angle()`."""
+
+    axis: "VectorSocket"
+    angle: "FloatSocket"
+
+
+class FindResult(NamedTuple):
+    """Result of `StringSocket.find()`."""
+
+    first_found: "IntegerSocket"
+    count: "IntegerSocket"
+
+
+class SVDResult(NamedTuple):
+    """SVD components returned by `MatrixSocket.svd()`."""
+
+    u: "MatrixSocket"
+    s: "VectorSocket"
+    v: "MatrixSocket"
+
 
 class BaseSocket:
     def __init__(self, socket: NodeSocket):
@@ -243,6 +278,89 @@ class Socket(BaseSocket, _SocketLike, OperatorMixin, LinkingMixin):
 # ---------------------------------------------------------------------------
 
 
+class _FieldDomain(Generic[_T]):
+    """Domain-bound factory available on all socket types.
+
+    Access via a domain property (e.g. ``socket.point``). Provides field
+    evaluation methods; subclasses add statistics for numeric socket types.
+    """
+
+    def __init__(self, socket: NodeSocket, dtype: str, domain: str) -> None:
+        self._socket = socket
+        self._dtype = dtype
+        self._domain = domain
+
+    def evaluate(self) -> "_T":
+        """Force evaluation of this field on the bound domain via ``EvaluateOnDomain``."""
+        from ..nodes.geometry import EvaluateOnDomain
+
+        return getattr(getattr(EvaluateOnDomain, self._domain), self._dtype)(
+            self._socket
+        ).o.value
+
+    def at(self, index: InputInteger = 0) -> "_T":
+        """Evaluate this field's value at *index* on the bound domain via ``EvaluateAtIndex``."""
+        from ..nodes.geometry import EvaluateAtIndex
+
+        return getattr(getattr(EvaluateAtIndex, self._domain), self._dtype)(
+            self._socket, index
+        ).o.value
+
+
+class _MinMaxDomain(_FieldDomain[_T]):
+    """Extends ``_FieldDomain`` with min/max aggregation for Integer sockets."""
+
+    def _minmax(self, field: str, group_index: InputInteger) -> "_T":
+        from ..nodes.geometry import FieldMinAndMax
+
+        node = getattr(getattr(FieldMinAndMax, self._domain), self._dtype)(
+            self._socket, group_index
+        )
+        return getattr(node.o, field)
+
+    def min(self, group_index: InputInteger = None) -> "_T":
+        return self._minmax("min", group_index)
+
+    def max(self, group_index: InputInteger = None) -> "_T":
+        return self._minmax("max", group_index)
+
+
+class _StatsDomain(_MinMaxDomain[_T]):
+    """Extends ``_MinMaxDomain`` with full statistics for Float and Vector sockets."""
+
+    def mean(self, group_index: InputInteger = None) -> "_T":
+        from ..nodes.geometry import FieldAverage
+
+        node = getattr(getattr(FieldAverage, self._domain), self._dtype)(
+            self._socket, group_index
+        )
+        return node.o.mean
+
+    def median(self, group_index: InputInteger = None) -> "_T":
+        from ..nodes.geometry import FieldAverage
+
+        node = getattr(getattr(FieldAverage, self._domain), self._dtype)(
+            self._socket, group_index
+        )
+        return node.o.median
+
+    def std_dev(self, group_index: InputInteger = None) -> "_T":
+        from ..nodes.geometry import FieldVariance
+
+        node = getattr(getattr(FieldVariance, self._domain), self._dtype)(
+            self._socket, group_index
+        )
+        return node.o.standard_deviation
+
+    def variance(self, group_index: InputInteger = None) -> "_T":
+        from ..nodes.geometry import FieldVariance
+
+        node = getattr(getattr(FieldVariance, self._domain), self._dtype)(
+            self._socket, group_index
+        )
+        return node.o.variance
+
+
 class _VectorMixin(BaseSocket):
     """Vector-specific properties (.x, .y, .z) and dispatch."""
 
@@ -286,6 +404,34 @@ class _VectorMixin(BaseSocket):
         else:
             return self._combine().i.z
 
+    @property
+    def point(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "point")
+
+    @property
+    def edge(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "edge")
+
+    @property
+    def face(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "face")
+
+    @property
+    def corner(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "corner")
+
+    @property
+    def spline(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "spline")
+
+    @property
+    def instance(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "instance")
+
+    @property
+    def layer(self) -> "_StatsDomain[VectorSocket]":
+        return _StatsDomain(self.socket, "vector", "layer")
+
     def dot(self, vector: InputVector) -> "FloatSocket":
         """Dot product with another vector. The other vector can be a Socket, a NodeSocket, or a 3-tuple of floats.
 
@@ -307,6 +453,61 @@ class _VectorMixin(BaseSocket):
         """
         return self._vmath.normalize(self.socket).o.vector
 
+    def cross(self, other: InputVector) -> "VectorSocket":
+        """Cross product of this vector with *other*. Returns a vector perpendicular to both."""
+        return self._vmath.cross_product(self.socket, other).o.vector
+
+    def distance(self, other: InputVector) -> "FloatSocket":
+        """Euclidean distance between this vector and *other*."""
+        return self._vmath.distance(self.socket, other).o.value
+
+    def project(self, other: InputVector) -> "VectorSocket":
+        """Project this vector onto *other*."""
+        return self._vmath.project(self.socket, other).o.vector
+
+    def reflect(self, normal: InputVector) -> "VectorSocket":
+        """Reflect this vector around *normal*. *normal* does not need to be normalised."""
+        return self._vmath.reflect(self.socket, normal).o.vector
+
+    def map_range(
+        self,
+        from_min: InputVector = (0.0, 0.0, 0.0),
+        from_max: InputVector = (1.0, 1.0, 1.0),
+        to_min: InputVector = (0.0, 0.0, 0.0),
+        to_max: InputVector = (1.0, 1.0, 1.0),
+        *,
+        clamp: bool = True,
+        interpolation_type: Literal[
+            "LINEAR", "STEPPED", "SMOOTHSTEP", "SMOOTHERSTEP"
+        ] = "LINEAR",
+        steps: InputVector = (4.0, 4.0, 4.0),
+    ) -> "VectorSocket":
+        """Convenience method to remap a vector socket using the `MapRange.vector()` node with this socket as input"""
+        from ..nodes.geometry import MapRange
+
+        node = MapRange.vector(self.socket, from_min, from_max, to_min, to_max)
+        node.clamp = clamp
+        node.interpolation_type = interpolation_type
+        if interpolation_type == "STEPPED":
+            kwargs = {"Steps_FLOAT3": steps}
+            node._establish_links(**kwargs)
+        return node.o.vector
+
+    def rotate(
+        self,
+        rotation: InputRotation,
+    ) -> "VectorSocket":
+        "Rotate this vector by the given rotation."
+        from ..nodes.geometry import RotateVector
+
+        return RotateVector(self.socket, rotation).o.vector
+
+    def transform(self, matrix: InputMatrix) -> "VectorSocket":
+        "Transform this vector by the given matrix."
+        from ..nodes.geometry import TransformPoint
+
+        return TransformPoint(self.socket, matrix).o.vector
+
     @property
     def default_value(self) -> list[float]:
         return list(self.socket.default_value)
@@ -428,10 +629,10 @@ class _VectorMixin(BaseSocket):
         def __rfloordiv__(self, other: Any) -> "VectorSocket": ...
         def __neg__(self) -> "VectorSocket": ...
         def __abs__(self) -> "VectorSocket": ...
-        def __lt__(self, other: Any) -> "Compare[NodeSocketVector]": ...
-        def __gt__(self, other: Any) -> "Compare[NodeSocketVector]": ...
-        def __le__(self, other: Any) -> "Compare[NodeSocketVector]": ...
-        def __ge__(self, other: Any) -> "Compare[NodeSocketVector]": ...
+        def __lt__(self, other: Any) -> "Compare[VectorSocket]": ...
+        def __gt__(self, other: Any) -> "Compare[VectorSocket]": ...
+        def __le__(self, other: Any) -> "Compare[VectorSocket]": ...
+        def __ge__(self, other: Any) -> "Compare[VectorSocket]": ...
 
 
 _SEPARATE_COLOR_IDNAMES = (
@@ -710,9 +911,37 @@ class _BooleanMixin(BaseSocket):
 
         return _BooleanSwitchSocketFactory(self.socket)
 
+    @property
+    def point(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "point")
+
+    @property
+    def edge(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "edge")
+
+    @property
+    def face(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "face")
+
+    @property
+    def corner(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "corner")
+
+    @property
+    def spline(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "spline")
+
+    @property
+    def instance(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "instance")
+
+    @property
+    def layer(self) -> "_FieldDomain[BooleanSocket]":
+        return _FieldDomain(self.socket, "boolean", "layer")
+
 
 class _RotationMixin(BaseSocket):
-    """Rotation-specific properties (.w, .x, .y, .z) via RotationToQuaternion."""
+    """Rotation-specific methods."""
 
     socket: NodeSocketRotation
 
@@ -724,43 +953,101 @@ class _RotationMixin(BaseSocket):
     def default_value(self, value: Euler) -> None:
         self.socket.default_value = value
 
-    @property
-    def _quaternion(self) -> "geometry.RotationToQuaternion":
+    def invert(self) -> "RotationSocket":
+        "Invert the rotation of the socket."
+        from ..nodes.geometry import InvertRotation
+
+        return InvertRotation._find_or_create_linked(self.socket).o.rotation
+
+    def rotate(
+        self,
+        rotation: InputRotation,
+        rotation_space: Literal["GLOBAL", "LOCAL"] = "GLOBAL",
+    ) -> "RotationSocket":
+        "Rotate this rotation by the given rotation in the specified rotation space."
+        from ..nodes.geometry import RotateRotation
+
+        return RotateRotation(
+            self.socket, rotation, rotation_space=rotation_space
+        ).o.rotation
+
+    def to_euler(self) -> "VectorSocket":
+        "Convert the rotation to an XYZ euler rotation and return `VectorSocket`."
+        from ..nodes.geometry.converter import RotationToEuler
+
+        return RotationToEuler._find_or_create_linked(self.socket).o.euler
+
+    def to_quaternion(self) -> QuaternionComponents:
+        "Decompose the rotation into quaternion components `(w, x, y, z)`."
         from ..nodes.geometry import RotationToQuaternion
 
-        return RotationToQuaternion._find_or_create_linked(self.socket)
+        o = RotationToQuaternion._find_or_create_linked(self.socket).o
+        return QuaternionComponents(o.w, o.x, o.y, o.z)
+
+    def to_axis_angle(self) -> AxisAngle:
+        "Decompose the rotation into axis-angle components `(axis, angle)`."
+        from ..nodes.geometry import RotationToAxisAngle
+
+        o = RotationToAxisAngle(self.socket).o
+        return AxisAngle(o.axis, o.angle)
 
     @property
-    def w(self) -> FloatSocket:
-        "Separate the rotation into a quaternion and return the `w` component"
-        return self._quaternion.o.w
+    def point(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "point")
 
     @property
-    def x(self) -> FloatSocket:
-        "Separate the rotation into a quaternion and return the `x` component"
-        return self._quaternion.o.x
+    def edge(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "edge")
 
     @property
-    def y(self) -> FloatSocket:
-        "Separate the rotation into a quaternion and return the `y` component"
-        return self._quaternion.o.y
+    def face(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "face")
 
     @property
-    def z(self) -> FloatSocket:
-        "Separate the rotation into a quaternion and return the `z` component"
-        return self._quaternion.o.z
+    def corner(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "corner")
 
-    def euler(self) -> "VectorSocket":
-        "Convert the rotation to an XYZ euler rotation and return `VectorSocket`."
-        from ..nodes.geometry.converter import RotationToEuler
+    @property
+    def spline(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "spline")
 
-        return RotationToEuler._find_or_create_linked(self.socket).o.euler
+    @property
+    def instance(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "instance")
 
-    def invert(self) -> "RotationSocket":
-        "Invert the rotation of the socket."
-        from ..nodes.geometry import InvertRotation
+    @property
+    def layer(self) -> "_FieldDomain[RotationSocket]":
+        return _FieldDomain(self.socket, "quaternion", "layer")
 
-        return InvertRotation._find_or_create_linked(self.socket).o.rotation
+
+class _FloatMixDataTypeFactory:
+    """Factory for typed Mix nodes driven by a float factor socket.
+
+    Access via ``FloatSocket.mix``. Each method creates a ``Mix`` node using
+    this socket as the factor and returns the corresponding output socket.
+    """
+
+    def __init__(self, socket: NodeSocket):
+        self._socket = socket
+        from ..nodes.geometry import Mix
+
+        self._mix = Mix
+
+    def float(self, a: InputFloat, b: InputFloat) -> "FloatSocket":
+        "Mix two float values, returning a ``FloatSocket``."
+        return self._mix.float(self._socket, a, b).o.result_float
+
+    def vector(self, a: InputVector, b: InputVector) -> "VectorSocket":
+        "Mix two vectors, returning a ``VectorSocket``."
+        return self._mix.vector(self._socket, a, b).o.result_vector
+
+    def color(self, a: InputColor, b: InputColor) -> "ColorSocket":
+        "Mix two colors, returning a ``ColorSocket``."
+        return self._mix.color(self._socket, a, b).o.result_color
+
+    def rotation(self, a: InputRotation, b: InputRotation) -> "RotationSocket":
+        "Mix two rotations, returning a ``RotationSocket``."
+        return self._mix.rotation(self._socket, a, b).o.result_rotation
 
 
 class _FloatMixin(BaseSocket):
@@ -782,6 +1069,106 @@ class _FloatMixin(BaseSocket):
 
         return Math
 
+    @property
+    def mix(self) -> _FloatMixDataTypeFactory:
+        "Create a ``Mix`` node using this socket as the factor."
+        return _FloatMixDataTypeFactory(self.socket)
+
+    @property
+    def point(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "point")
+
+    @property
+    def edge(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "edge")
+
+    @property
+    def face(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "face")
+
+    @property
+    def corner(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "corner")
+
+    @property
+    def spline(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "spline")
+
+    @property
+    def instance(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "instance")
+
+    @property
+    def layer(self) -> "_StatsDomain[FloatSocket]":
+        return _StatsDomain(self.socket, "float", "layer")
+
+    def map_range(
+        self,
+        from_min: InputFloat = 0.0,
+        from_max: InputFloat = 1.0,
+        to_min: InputFloat = 0.0,
+        to_max: InputFloat = 1.0,
+        *,
+        clamp=True,
+        interpolation_type: Literal[
+            "LINEAR", "STEPPED", "SMOOTHSTEP", "SMOOTHERSTEP"
+        ] = "LINEAR",
+        steps: InputFloat = 4.0,
+    ) -> "FloatSocket":
+        """Remap the values on the float socket using the MapRange node."""
+        from ..nodes.geometry import MapRange
+
+        node = MapRange.float(self.socket, from_min, from_max, to_min, to_max)
+        node.clamp = clamp
+        node.interpolation_type = interpolation_type
+        if interpolation_type == "STEPPED":
+            node._establish_links(steps=steps)
+        return node.o.result
+
+    def clamp(self, min: InputFloat = 0.0, max: InputFloat = 1.0) -> "FloatSocket":
+        """Clamp the value to *[min, max]*. Defaults to the unit interval ``[0, 1]``."""
+        from ..nodes.geometry import Clamp
+
+        return Clamp.min_max(self.socket, min, max).o.result
+
+    def sqrt(self) -> "FloatSocket":
+        """Return the square root of this value."""
+        return self._math.square_root(self.socket).o.value
+
+    def power(self, exponent: InputFloat) -> "FloatSocket":
+        """Raise this value to *exponent*."""
+        return self._math.power(self.socket, exponent).o.value
+
+    def floor(self) -> "FloatSocket":
+        """Round down to the nearest integer."""
+        return self._math.floor(self.socket).o.value
+
+    def ceil(self) -> "FloatSocket":
+        """Round up to the nearest integer."""
+        return self._math.ceil(self.socket).o.value
+
+    def round(self) -> "FloatSocket":
+        """Round to the nearest integer."""
+        return self._math.round(self.socket).o.value
+
+    def modulo(self, divisor: InputFloat) -> "FloatSocket":
+        """Floored modulo — remainder after dividing by *divisor*, always non-negative."""
+        return self._math.floored_modulo(self.socket, divisor).o.value
+
+    def wrap(self, min: InputFloat, max: InputFloat) -> "FloatSocket":
+        """Wrap the value into the *[min, max]* range, repeating cyclically."""
+        # the wrap method has different order of arguments with max being first
+        # compared to other nodes that are defined.
+        return self._math.wrap(self.socket, value_001=max, value_002=min).o.value
+
+    def to_radians(self) -> "FloatSocket":
+        """Convert degrees to radians."""
+        return self._math.to_radians(self.socket).o.value
+
+    def to_degrees(self) -> "FloatSocket":
+        """Convert radians to degrees."""
+        return self._math.to_degrees(self.socket).o.value
+
     def sign(self) -> "FloatSocket":
         "Return the sign of the FloatSocket, eithe `-1`, `0` or `1`."
         return self._math.sign(self.socket).o.value
@@ -796,6 +1183,14 @@ class _FloatMixin(BaseSocket):
 
         return ValueToString.float(self.socket, decimals).o.string
 
+    def to_integer(
+        self, rounding_mode: Literal["ROUND", "FLOOR", "CEILING", "TRUNCATE"] = "ROUND"
+    ) -> "IntegerSocket":
+        "Convert the `FloatSocket` to an `IntegerSocket` by truncating the decimal part."
+        from ..nodes.geometry import FloatToInteger
+
+        return FloatToInteger(self.socket, rounding_mode=rounding_mode).o.integer
+
 
 class _IntegerMixin(BaseSocket):
     """Integer-specific dispatch — uses IntegerMath in geometry trees."""
@@ -812,6 +1207,34 @@ class _IntegerMixin(BaseSocket):
     def default_value(self, value: int) -> None:
         self.socket.default_value = value
 
+    @property
+    def point(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "point")
+
+    @property
+    def edge(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "edge")
+
+    @property
+    def face(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "face")
+
+    @property
+    def corner(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "corner")
+
+    @property
+    def spline(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "spline")
+
+    @property
+    def instance(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "instance")
+
+    @property
+    def layer(self) -> "_MinMaxDomain[IntegerSocket]":
+        return _MinMaxDomain(self.socket, "integer", "layer")
+
     @property
     def _imath(self) -> "type[IntegerMath]":
         from ..nodes.geometry import IntegerMath
@@ -824,6 +1247,16 @@ class _IntegerMixin(BaseSocket):
 
         return ValueToString.integer(self.socket).o.string
 
+    def clamp(self, min: InputInteger = 0, max: InputInteger = 1) -> "IntegerSocket":
+        """Clamp the value to *[min, max]*."""
+        return self._imath.minimum(
+            self._imath.maximum(self.socket, min).o.value, max
+        ).o.value
+
+    def modulo(self, divisor: InputInteger) -> "IntegerSocket":
+        """Remainder after dividing by *divisor* (always non-negative)."""
+        return self._imath.modulo(self.socket, divisor).o.value
+
     def sign(self) -> "IntegerSocket":
         "Return the sign of the IntegerSocket, either `-1`, `0`, or `1`."
         return self._imath.sign(self.socket).o.value
@@ -894,10 +1327,10 @@ class _IntegerMixin(BaseSocket):
         def __rfloordiv__(self, other: Any) -> "IntegerSocket": ...
         def __neg__(self) -> "IntegerSocket": ...
         def __abs__(self) -> "IntegerSocket": ...
-        def __lt__(self, other: Any) -> "Compare[NodeSocketInt]": ...
-        def __gt__(self, other: Any) -> "Compare[NodeSocketInt]": ...
-        def __le__(self, other: Any) -> "Compare[NodeSocketInt]": ...
-        def __ge__(self, other: Any) -> "Compare[NodeSocketInt]": ...
+        def __lt__(self, other: Any) -> "Compare[IntegerSocket]": ...
+        def __gt__(self, other: Any) -> "Compare[IntegerSocket]": ...
+        def __le__(self, other: Any) -> "Compare[IntegerSocket]": ...
+        def __ge__(self, other: Any) -> "Compare[IntegerSocket]": ...
 
 
 class _StringMixin(BaseSocket):
@@ -959,15 +1392,12 @@ class _StringMixin(BaseSocket):
 
         return StringLength(self.socket).o.length
 
-    def find(self, search: InputString) -> tuple["IntegerSocket", "IntegerSocket"]:
-        """Find where in a string a pattern occurs.
-
-        Returns a tuple(IntegerSocket, IntegerSocket), corresponding to (index_of_first_match, count_of_matches)."""
+    def find(self, search: InputString) -> FindResult:
+        "Find where in a string a pattern occurs. Returns `(first_found, count)`."
         from ..nodes.geometry import FindInString
 
-        node = FindInString(self.socket, search)
-
-        return (node.o.first_found, node.o.count)
+        o = FindInString(self.socket, search).o
+        return FindResult(o.first_found, o.count)
 
     def join(
         self, strings: Iterable[str | "StringSocket" | NodeSocketString | BaseNode]
@@ -1035,11 +1465,50 @@ class _MatrixMixin(BaseSocket):
 
         return TransposeMatrix._find_or_create_linked(self.socket).o.matrix
 
-    def svd(self) -> tuple[MatrixSocket, VectorSocket, MatrixSocket]:
-        "Compute the 'Single Value Decomposition' and return output sockets of the MatrixSVD node, `tuple[u, s, v]`"
+    def svd(self) -> SVDResult:
+        "Decompose the matrix via SVD. Returns `(u, s, v)`."
         from ..nodes.geometry import MatrixSVD
 
-        return tuple(MatrixSVD(self.socket).o)
+        o = MatrixSVD(self.socket).o
+        return SVDResult(o.u, o.s, o.v)
+
+    def transform_direction(self, direction: InputVector) -> "VectorSocket":
+        """Apply this matrix to *direction*, ignoring translation.
+
+        Use this instead of ``transform()`` when transforming a direction vector
+        (e.g. a normal) where translation must not affect the result.
+        """
+        from ..nodes.geometry import TransformDirection
+
+        return TransformDirection(direction, self.socket).o.direction
+
+    @property
+    def point(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "point")
+
+    @property
+    def edge(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "edge")
+
+    @property
+    def face(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "face")
+
+    @property
+    def corner(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "corner")
+
+    @property
+    def spline(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "spline")
+
+    @property
+    def instance(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "instance")
+
+    @property
+    def layer(self) -> "_FieldDomain[MatrixSocket]":
+        return _FieldDomain(self.socket, "matrix", "layer")
 
     @overload
     def __getitem__(self, key: slice) -> "list[FloatSocket]": ...
@@ -1071,10 +1540,12 @@ class _MatrixMixin(BaseSocket):
 
         if self.socket.is_output:
             node = SeparateMatrix._find_or_create_linked(self.socket)
-            return iter(node.o)
+            for i in node.o:
+                yield cast(FloatSocket, i)
         else:
             node = CombineMatrix._find_or_create_linked(self.socket)
-            return iter(node.i)
+            for i in node.i:
+                yield cast(FloatSocket, i)
 
     def __len__(self) -> int:
         return 16

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/nodes/geometry/groups.py

@@ -14,12 +14,10 @@ from ...builder import (
 from . import (
     AxesToRotation,
     CombineMatrix,
+    Compare,
     EdgesOfVertex,
     EdgeVertices,
-    EvaluateAtIndex,
-    FieldAverage,
     Frame,
-    Switch,
 )
 
 
@@ -60,13 +58,15 @@ class OtherVertex(CustomGeometryGroup):
         vertex_index = tree.inputs.integer("Vertex Index", default_input="INDEX")
         edge_number = tree.inputs.integer("Edge Number")
 
-        eov = EdgesOfVertex(vertex_index, sort_index=edge_number)
+        eov = EdgesOfVertex(vertex_index, sort_index=edge_number).o.edge_index
         ev = EdgeVertices()
-        vert_1 = EvaluateAtIndex.edge.integer(ev.o.vertex_index_1, eov)
-        vert_2 = EvaluateAtIndex.edge.integer(ev.o.vertex_index_2, eov)
-        switch = (vert_1 != vertex_index) >> Switch.integer(..., vert_1, vert_2)
+        vert_1 = ev.o.vertex_index_1.edge.at(eov)
+        vert_2 = ev.o.vertex_index_2.edge.at(eov)
+        index = Compare.integer.not_equal(vert_1, vertex_index).o.result.switch.integer(
+            vert_1, vert_2
+        )
 
-        _ = switch >> tree.outputs.integer("Other Vertex")
+        index >> tree.outputs.integer("Other Vertex")
 
 
 class OffsetVector(CustomGeometryGroup):
@@ -110,7 +110,7 @@ class OffsetVector(CustomGeometryGroup):
         vector = tree.inputs.vector("Vector", default_input="POSITION")
         offset = tree.inputs.integer("Offset")
 
-        value = EvaluateAtIndex.point.vector(vector, index + offset)
+        value = vector.point.at(index + offset)
 
         _ = value >> tree.outputs.vector("Vector")
 
@@ -177,7 +177,7 @@ class PrincipalComponents(CustomGeometryGroup):
             out_short = tree.outputs.vector("Shortest Axis")
 
         with Frame("Centroid"):
-            centroid = FieldAverage.point.vector(position, group_id)
+            centroid = position.point.mean(group_id)
             centroid >> out_centroid
 
         with Frame("Covariance Matrix"):
@@ -185,8 +185,8 @@ class PrincipalComponents(CustomGeometryGroup):
             matrix = CombineMatrix()
 
             for i, axis1 in enumerate(diff):
-                mean = FieldAverage.point.vector(diff * axis1, group_id)
-                for j, axis2 in enumerate(mean.o.mean):
+                mean = (diff * axis1).point.mean(group_id)
+                for j, axis2 in enumerate(mean):
                     axis2 >> matrix.i[int(i * 4 + j)]
 
         with Frame("SVD"):

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/nodes/geometry/manual.py

@@ -14,6 +14,7 @@ from bpy.types import (
 )
 
 from nodebpy.builder._registry import _get_socket_linker
+from nodebpy.builder.socket import BaseSocket
 
 from ...builder import (
     BaseNode,
@@ -88,7 +89,7 @@ from .zone import (
     _sync_closure_items,
 )
 
-_T = TypeVar("_T")
+_T = TypeVar("_T", bound=BaseSocket)
 _S = TypeVar("_S")
 
 __all__ = (
@@ -1441,7 +1442,7 @@ class JoinGeometry(BaseNode):
 
     def __init__(self, geometry: Iterable[InputGeometry] = ()):
         super().__init__()
-        for source in reversed(geometry):
+        for source in reversed(list(geometry)):
             assert source
             self._link(*self._find_best_socket_pair(source, self))
 
@@ -2493,20 +2494,6 @@ class FieldAverage(BaseNode, Generic[_T]):
     instance = _FieldAverageDomainFactory("INSTANCE")
     layer = _FieldAverageDomainFactory("LAYER")
 
-    def __init__(
-        self,
-        value: InputFloat | InputVector = None,
-        group_index: InputFloat | InputVector = 0,
-        *,
-        data_type: Literal["FLOAT", "FLOAT_VECTOR"] = "FLOAT",
-        domain: _AttributeDomains = "POINT",
-    ):
-        super().__init__()
-        key_args = {"Value": value, "Group Index": group_index}
-        self.data_type = data_type
-        self.domain = domain
-        self._establish_links(**key_args)
-
     class _Inputs(SocketAccessor, Generic[_S]):
         value: _S
         """The field value to average."""
@@ -2527,6 +2514,20 @@ class FieldAverage(BaseNode, Generic[_T]):
         @property
         def o(self) -> "_Outputs[_T]": ...
 
+    def __init__(
+        self,
+        value: InputFloat | InputVector = None,
+        group_index: InputFloat | InputVector = 0,
+        *,
+        data_type: Literal["FLOAT", "FLOAT_VECTOR"] = "FLOAT",
+        domain: _AttributeDomains = "POINT",
+    ):
+        super().__init__()
+        key_args = {"Value": value, "Group Index": group_index}
+        self.data_type = data_type
+        self.domain = domain
+        self._establish_links(**key_args)
+
     @property
     def data_type(self) -> Literal["FLOAT", "FLOAT_VECTOR"]:
         return self.node.data_type
@@ -2597,20 +2598,6 @@ class FieldMinAndMax(BaseNode, Generic[_T]):
     instance = _FieldMinAndMaxDomainFactory("INSTANCE")
     layer = _FieldMinAndMaxDomainFactory("LAYER")
 
-    def __init__(
-        self,
-        value: InputFloat | InputVector | InputInteger = 1.0,
-        group_index: InputInteger = 0,
-        *,
-        data_type: Literal["FLOAT", "INT", "FLOAT_VECTOR"] = "FLOAT",
-        domain: _AttributeDomains = "POINT",
-    ):
-        super().__init__()
-        key_args = {"Value": value, "Group Index": group_index}
-        self.data_type = data_type
-        self.domain = domain
-        self._establish_links(**key_args)
-
     class _Inputs(SocketAccessor, Generic[_S]):
         value: _S
         """The field value to find the min/max of."""
@@ -2631,6 +2618,20 @@ class FieldMinAndMax(BaseNode, Generic[_T]):
         @property
         def o(self) -> "_Outputs[_T]": ...
 
+    def __init__(
+        self,
+        value: InputFloat | InputVector | InputInteger = 1.0,
+        group_index: InputInteger = 0,
+        *,
+        data_type: Literal["FLOAT", "INT", "FLOAT_VECTOR"] = "FLOAT",
+        domain: _AttributeDomains = "POINT",
+    ):
+        super().__init__()
+        key_args = {"Value": value, "Group Index": group_index}
+        self.data_type = data_type
+        self.domain = domain
+        self._establish_links(**key_args)
+
     @property
     def data_type(self) -> Literal["FLOAT", "INT", "FLOAT_VECTOR"]:
         return self.node.data_type
@@ -2681,7 +2682,7 @@ class EvaluateOnDomain(BaseNode, Generic[_T]):
                 value, domain=self._domain, data_type="FLOAT_VECTOR"
             )
 
-        def rotation(
+        def quaternion(
             self, value: InputRotation = None
         ) -> "EvaluateOnDomain[RotationSocket]":
             return EvaluateOnDomain(value, domain=self._domain, data_type="QUATERNION")

{nodebpy-0.16.0 → nodebpy-0.17.0}/src/nodebpy/types.py

@@ -100,7 +100,7 @@ InputColor = typing.Union[
     InputLinkable,
     "ColorSocket",
 ]
-InputString = typing.Union[str, NodeSocketString, EllipsisType, "StringSocket"]
+InputString = typing.Union[None, str, NodeSocketString, EllipsisType, "StringSocket"]
 InputGeometry = typing.Union[NodeSocketGeometry, InputLinkable, "GeometrySocket"]
 InputObject = typing.Union[NodeSocketObject, Object, InputLinkable, "ObjectSocket"]
 InputMaterial = typing.Union[