procfunc 0.33.0__tar.gz → 0.33.2__tar.gz

{procfunc-0.33.0/src/procfunc.egg-info → procfunc-0.33.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procfunc
-Version: 0.33.0
+Version: 0.33.2
 Summary: Function-Oriented Abstractions for Procedural 3D Generation in Python
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/princeton-vl/procfunc
@@ -24,7 +24,7 @@ Dynamic: license-file
 
 # ProcFunc: Function-Oriented Abstractions for Procedural 3D Generation in Python
 
-[**Documentation**](#documentation)
+[**Documentation**](https://procfunc.readthedocs.io)
 | [**Research Paper**](https://arxiv.org/abs/2604.26943)
 | [**Transpiling**](#transpile-a-blender-file-to-procfunc-code)
 | [**Experiments**](#experiments)

{procfunc-0.33.0 → procfunc-0.33.2}/README.md

@@ -1,6 +1,6 @@
 # ProcFunc: Function-Oriented Abstractions for Procedural 3D Generation in Python
 
-[**Documentation**](#documentation)
+[**Documentation**](https://procfunc.readthedocs.io)
 | [**Research Paper**](https://arxiv.org/abs/2604.26943)
 | [**Transpiling**](#transpile-a-blender-file-to-procfunc-code)
 | [**Experiments**](#experiments)

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/__init__.py

@@ -2,7 +2,7 @@
 # ensure this gets imported first so that mathutils etc is available even if later modules dont import bpy
 import bpy
 
-__version__ = "0.33.0"
+__version__ = "0.33.2"
 
 from numpy.random import Generator as RNG
 

procfunc-0.33.2/src/procfunc/cli/__init__.py

@@ -0,0 +1,3 @@
+from procfunc.cli.main import cli, get_parser
+
+__all__ = ["cli", "get_parser"]

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/color.py

@@ -10,6 +10,8 @@ def hsv_color(
     saturation: float | None = None,
     value: float | None = None,
 ) -> t.Color:
+    if hsv is None and (hue is None or saturation is None or value is None):
+        raise ValueError("provide hsv=... or all of hue/saturation/value")
     color = t.Color()
     if hsv is not None:
         color.hsv = hsv
@@ -27,6 +29,8 @@ def rgb_color(
     b: float | None = None,
     rgb: np.ndarray | None = None,
 ) -> t.Color:
+    if rgb is None and (r is None or g is None or b is None):
+        raise ValueError("provide rgb=... or all of r/g/b")
     color = t.Color()
     if rgb is not None:
         color.r, color.g, color.b = rgb

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/compute_graph/util.py

@@ -3,10 +3,21 @@ import logging
 from collections import defaultdict, deque
 from typing import Any, Callable, Generator, Literal, TypeVar
 
+import numpy as np
+
 from procfunc.util import pytree
 
 from .compute_graph import ComputeGraph
-from .node import Node, SubgraphCallNode
+from .node import (
+    ConstantNode,
+    FunctionCallNode,
+    GetAttributeNode,
+    InputPlaceholderNode,
+    MethodCallNode,
+    Node,
+    ProceduralNode,
+    SubgraphCallNode,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -40,6 +51,7 @@ def traverse_breadth_first(
 
     visited = set()
     frontier = deque((None, name, node) for name, node in graph.outputs.items())
+    visited.update(id(node) for _, _, node in frontier)
     # logger.debug(f"{traverse_breadth_first.__name__} {graph.name} {len(frontier)=}")
 
     def res(parent, name, child):
@@ -61,10 +73,6 @@ def traverse_breadth_first(
         if not isinstance(node, Node):
             continue
 
-        if id(node) in visited:
-            continue
-        visited.add(id(node))
-
         yield res(parent, name, node)
 
         children = list(pytree.PyTree(node.args).items()) + list(
@@ -75,6 +83,7 @@ def traverse_breadth_first(
                 continue
             if id(arg) in visited:
                 continue
+            visited.add(id(arg))
             frontier.append((node, key, arg))
 
 
@@ -201,22 +210,95 @@ def usages_per_node(
     return dict(usages)
 
 
-def graph_nodes_equal(graph1: ComputeGraph, graph2: ComputeGraph) -> bool:
-    nodes1 = list(traverse_depth_first(graph1))
-    nodes2 = list(traverse_depth_first(graph2))
-    if len(nodes1) != len(nodes2):
+def _value_equal(a: Any, b: Any) -> bool:
+    """Array-safe equality for non-node values (constants, attrs, defaults)."""
+    if a is b:
+        return True
+    if isinstance(a, np.ndarray) or isinstance(b, np.ndarray):
+        return np.array_equal(a, b)
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_value_equal(a[k], b[k]) for k in a)
+    if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)):
+        return (
+            type(a) is type(b)
+            and len(a) == len(b)
+            and all(_value_equal(x, y) for x, y in zip(a, b))
+        )
+    try:
+        return bool(a == b)
+    except (ValueError, TypeError):
+        return False
+
+
+def _args_equal(a: Any, b: Any, memo: dict[tuple[int, int], bool]) -> bool:
+    """Structural equality of an args/kwargs tree: same container shape, with
+    node-valued leaves compared recursively and other leaves by value."""
+    tree_a = pytree.PyTree(a)
+    tree_b = pytree.PyTree(b)
+    if tree_a.spec != tree_b.spec:
         return False
-    for node1, node2 in zip(nodes1, nodes2):
-        if type(node1) is not type(node2):
+    for leaf_a, leaf_b in zip(tree_a.values(), tree_b.values()):
+        a_is_node = isinstance(leaf_a, Node)
+        b_is_node = isinstance(leaf_b, Node)
+        if a_is_node != b_is_node:
             return False
-        if isinstance(node1, SubgraphCallNode):
-            if not graph_nodes_equal(node1.subgraph, node2.subgraph):
+        if a_is_node:
+            if not _nodes_equal(leaf_a, leaf_b, memo):
                 return False
-        elif node1.args != node2.args or node1.kwargs != node2.kwargs:
+        elif not _value_equal(leaf_a, leaf_b):
             return False
     return True
 
 
+def _nodes_equal(node1: Node, node2: Node, memo: dict[tuple[int, int], bool]) -> bool:
+    if node1 is node2:
+        return True
+    if type(node1) is not type(node2):
+        return False
+
+    key = (id(node1), id(node2))
+    cached = memo.get(key)
+    if cached is not None:
+        return cached
+    memo[key] = True  # optimistic, breaks cycles in shared DAGs
+
+    result = True
+    if isinstance(node1, SubgraphCallNode):
+        result = graph_nodes_equal(node1.subgraph, node2.subgraph)
+    if result and isinstance(node1, FunctionCallNode):
+        result = node1.func is node2.func
+    if result and isinstance(node1, MethodCallNode):
+        result = node1.method_name == node2.method_name
+    if result and isinstance(node1, GetAttributeNode):
+        result = node1.attribute_name == node2.attribute_name
+    if result and isinstance(node1, ProceduralNode):
+        result = node1.node_type == node2.node_type and _value_equal(
+            node1.attrs, node2.attrs
+        )
+    if result and isinstance(node1, ConstantNode):
+        result = _value_equal(node1.value, node2.value)
+    if result and isinstance(node1, InputPlaceholderNode):
+        result = node1.input_name == node2.input_name and _value_equal(
+            node1.default_value, node2.default_value
+        )
+    if result:
+        result = _args_equal(node1.args, node2.args, memo) and _args_equal(
+            node1.kwargs, node2.kwargs, memo
+        )
+
+    memo[key] = result
+    return result
+
+
+def graph_nodes_equal(graph1: ComputeGraph, graph2: ComputeGraph) -> bool:
+    nodes1 = list(traverse_depth_first(graph1))
+    nodes2 = list(traverse_depth_first(graph2))
+    if len(nodes1) != len(nodes2):
+        return False
+    memo: dict[tuple[int, int], bool] = {}
+    return all(_nodes_equal(node1, node2, memo) for node1, node2 in zip(nodes1, nodes2))
+
+
 def transform_nodetree(
     root: Node,
     transform_fn: Callable[[Node], Any],

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/nodes/color.py

@@ -39,7 +39,7 @@ def mix_rgb(
     clamp_factor: bool = True,
 ) -> nt.ProcNode[pt.Color]:
     """
-    Uses a Mix Node with datatype Color
+    Uses a Mix Shader Node with data_type='RGBA'.
 
     NOTE: separated from float/vector mix() due to extra arguments
 
@@ -80,7 +80,7 @@ def combine_rgb(
     blue: nt.SocketOrVal[float] = 0.0,
 ) -> nt.ProcNode[pt.Color]:
     """
-    Uses a CombineColor Shader Node.
+    Uses a CombineColor Shader Node in RGB mode.
 
     See: https://docs.blender.org/manual/en/4.2/render/shader_nodes/converter/combine_color.html
     """
@@ -97,7 +97,7 @@ def combine_hsv(
     value: nt.SocketOrVal[float] = 0.0,
 ) -> nt.ProcNode[pt.Color]:
     """
-    Uses a CombineColor Shader Node.
+    Uses a CombineColor Shader Node in HSV mode.
 
     See: https://docs.blender.org/manual/en/4.2/render/shader_nodes/converter/combine_color.html
     """
@@ -115,7 +115,7 @@ def combine_hsl(
     lightness: nt.SocketOrVal[float] = 0.0,
 ) -> nt.ProcNode[pt.Color]:
     """
-    Uses a CombineHSV Shader Node.
+    Uses a CombineColor Shader Node in HSL mode.
 
     See: https://docs.blender.org/manual/en/4.2/render/shader_nodes/converter/combine_color.html
     """

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/nodes/func.py

@@ -92,6 +92,7 @@ def boolean_or(
     a: nt.SocketOrVal[bool],
     b: nt.SocketOrVal[bool],
 ) -> nt.ProcNode[bool]:
+    """Uses a BooleanMath Function Node with operation='OR'."""
     return nt.ProcNode.from_nodetype(
         node_type="FunctionNodeBooleanMath",
         inputs={("Boolean", 0): a, ("Boolean", 1): b},
@@ -103,6 +104,7 @@ def boolean_and(
     a: nt.SocketOrVal[bool],
     b: nt.SocketOrVal[bool],
 ) -> nt.ProcNode[bool]:
+    """Uses a BooleanMath Function Node with operation='AND'."""
     return nt.ProcNode.from_nodetype(
         node_type="FunctionNodeBooleanMath",
         inputs={("Boolean", 0): a, ("Boolean", 1): b},
@@ -114,6 +116,7 @@ def boolean_xor(
     a: nt.SocketOrVal[bool],
     b: nt.SocketOrVal[bool],
 ) -> nt.ProcNode[bool]:
+    """Uses a BooleanMath Function Node with operation='XOR'."""
     return nt.ProcNode.from_nodetype(
         node_type="FunctionNodeBooleanMath",
         inputs={("Boolean", 0): a, ("Boolean", 1): b},
@@ -125,7 +128,7 @@ def boolean_not(
     a: nt.SocketOrVal[bool],
 ) -> nt.ProcNode[bool]:
     """
-    Uses a BooleanNot Function Node.
+    Uses a BooleanMath Function Node with operation='NOT'.
 
     See: https://docs.blender.org/manual/en/4.2/modeling/geometry_nodes/utilities/math/boolean_math.html
     """
@@ -275,6 +278,7 @@ def less_than(
     a: TCompareNumeric,
     b: TCompareNumeric,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='LESS_THAN'."""
     return _compare(a, b, operation="LESS_THAN")
 
 
@@ -282,6 +286,7 @@ def less_equal(
     a: TCompareNumeric,
     b: TCompareNumeric,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='LESS_EQUAL'."""
     return _compare(a, b, operation="LESS_EQUAL")
 
 
@@ -289,6 +294,7 @@ def greater_than(
     a: TCompareNumeric,
     b: TCompareNumeric,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='GREATER_THAN'."""
     return _compare(a, b, operation="GREATER_THAN")
 
 
@@ -296,6 +302,7 @@ def greater_equal(
     a: TCompareNumeric,
     b: TCompareNumeric,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='GREATER_EQUAL'."""
     return _compare(a, b, operation="GREATER_EQUAL")
 
 
@@ -311,6 +318,7 @@ def equal(
     b: TCompareEqual,
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='EQUAL'."""
     return _compare(a, b, epsilon, operation="EQUAL")
 
 
@@ -319,6 +327,7 @@ def not_equal(
     b: TCompareEqual,
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with operation='NOT_EQUAL'."""
     return _compare(a, b, epsilon, operation="NOT_EQUAL")
 
 
@@ -332,6 +341,7 @@ def vector_elementwise_less_than(
     a: nt.SocketOrVal[pt.Vector],
     b: nt.SocketOrVal[pt.Vector],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='LESS_THAN'."""
     return _compare(a, b, operation="LESS_THAN", data_type=NodeDataType.FLOAT_VECTOR)
 
 
@@ -339,6 +349,7 @@ def vector_elementwise_less_equal(
     a: nt.SocketOrVal[pt.Vector],
     b: nt.SocketOrVal[pt.Vector],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='LESS_EQUAL'."""
     return _compare(a, b, operation="LESS_EQUAL", data_type=NodeDataType.FLOAT_VECTOR)
 
 
@@ -346,6 +357,7 @@ def vector_elementwise_greater_than(
     a: nt.SocketOrVal[pt.Vector],
     b: nt.SocketOrVal[pt.Vector],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='GREATER_THAN'."""
     return _compare(a, b, operation="GREATER_THAN", data_type=NodeDataType.FLOAT_VECTOR)
 
 
@@ -353,6 +365,7 @@ def vector_elementwise_greater_equal(
     a: nt.SocketOrVal[pt.Vector],
     b: nt.SocketOrVal[pt.Vector],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='GREATER_EQUAL'."""
     return _compare(
         a, b, operation="GREATER_EQUAL", data_type=NodeDataType.FLOAT_VECTOR
     )
@@ -363,6 +376,7 @@ def vector_elementwise_equal(
     b: nt.SocketOrVal[pt.Vector],
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='EQUAL'."""
     return _compare(
         a, b, epsilon, operation="EQUAL", data_type=NodeDataType.FLOAT_VECTOR
     )
@@ -373,6 +387,7 @@ def vector_elementwise_not_equal(
     b: nt.SocketOrVal[pt.Vector],
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='VECTOR', mode='ELEMENT', operation='NOT_EQUAL'."""
     return _compare(
         a, b, epsilon, operation="NOT_EQUAL", data_type=NodeDataType.FLOAT_VECTOR
     )
@@ -383,6 +398,7 @@ def color_equal(
     b: nt.SocketOrVal[pt.Color],
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='RGBA', operation='EQUAL'."""
     return _compare(a, b, epsilon, operation="EQUAL", data_type=NodeDataType.RGBA)
 
 
@@ -391,6 +407,7 @@ def color_not_equal(
     b: nt.SocketOrVal[pt.Color],
     epsilon: nt.SocketOrVal[float] = COMPARE_EPSILON_DEFAULT,
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='RGBA', operation='NOT_EQUAL'."""
     return _compare(a, b, epsilon, operation="NOT_EQUAL", data_type=NodeDataType.RGBA)
 
 
@@ -398,6 +415,7 @@ def color_brighter(
     a: nt.SocketOrVal[pt.Color],
     b: nt.SocketOrVal[pt.Color],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='RGBA', operation='BRIGHTER'."""
     return _compare(a, b, operation="BRIGHTER", data_type=NodeDataType.RGBA)
 
 
@@ -405,6 +423,7 @@ def color_darker(
     a: nt.SocketOrVal[pt.Color],
     b: nt.SocketOrVal[pt.Color],
 ) -> nt.ProcNode[bool]:
+    """Uses a Compare Function Node with data_type='RGBA', operation='DARKER'."""
     return _compare(a, b, operation="DARKER", data_type=NodeDataType.RGBA)
 
 
@@ -693,7 +712,7 @@ def random_boolean(
     seed: nt.SocketOrVal[int] = 0,
 ) -> nt.ProcNode[bool]:
     """
-    Uses a RandomBoolean Function Node.
+    Uses a RandomValue Function Node with data_type='BOOLEAN'.
     """
     return nt.ProcNode.from_nodetype(
         node_type="FunctionNodeRandomValue",

{procfunc-0.33.0 → procfunc-0.33.2}/src/procfunc/nodes/geo.py

@@ -622,7 +622,7 @@ def curve_line(
     end: nt.SocketOrVal[nt.pt.Vector],
 ) -> nt.ProcNode[pt.CurveObject]:
     """
-    Uses a CurvePrimitiveLine Geometry Node.
+    Uses a CurvePrimitiveLine Geometry Node in POINTS mode.
 
     See: https://docs.blender.org/manual/en/4.2/modeling/geometry_nodes/curve/primitives/curve_line.html
     """
@@ -639,7 +639,7 @@ def curve_line_from_direction(
     length: nt.SocketOrVal[float] = 1.0,
 ) -> nt.ProcNode[pt.CurveObject]:
     """
-    Uses a CurveLineFromDirection Geometry Node.
+    Uses a CurvePrimitiveLine Geometry Node in DIRECTION mode.
 
     See: https://docs.blender.org/manual/en/4.2/modeling/geometry_nodes/curve/primitives/curve_line.html
     """
@@ -2633,6 +2633,7 @@ def mesh_line_from_endpoints(
     count: nt.SocketOrVal[int] = 10,
     count_mode: Literal["TOTAL", "RESOLUTION"] = "TOTAL",
 ) -> nt.ProcNode[pt.MeshObject]:
+    """Uses a MeshLine Geometry Node with mode='END_POINTS'."""
     return nt.ProcNode.from_nodetype(
         node_type="GeometryNodeMeshLine",
         inputs={
@@ -3227,7 +3228,7 @@ def sample_curve(
     data_type: NodeDataType | RuntimeResolveDataType | None = None,
 ) -> SampleCurveResult:
     """
-    Uses a SampleCurve Geometry Node.
+    Uses a SampleCurve Geometry Node with FACTOR mode.
 
     See: https://docs.blender.org/manual/en/4.2/modeling/geometry_nodes/curve/sample/sample_curve.html
     """
@@ -4306,7 +4307,7 @@ def transform(
     scale: nt.SocketOrVal[pt.Vector] = (1, 1, 1),
 ) -> nt.ProcNode[TMeshOrCurve]:
     """
-    Uses a Transform Geometry Node.
+    Uses a Transform Geometry Node with mode='COMPONENTS'.
 
     See: https://docs.blender.org/manual/en/4.2/modeling/geometry_nodes/geometry/operations/transform_geometry.html
     """
@@ -4326,6 +4327,7 @@ def transform_by_matrix(
     geometry: nt.ProcNode[TMeshOrCurve],
     matrix: nt.SocketOrVal[pt.Matrix],
 ):
+    """Uses a Transform Geometry Node with mode='MATRIX'."""
     return nt.ProcNode.from_nodetype(
         node_type="GeometryNodeTransform",
         inputs={