Python SDK: Release 2025.2.0

Author: mxn-ferdinand

plugins/py-ocio_node_2025/py-ocio_node_2025.pyp

@@ -24,7 +24,6 @@ import os
 import c4d
 import maxon
 
-c4d.DRAW_TEXTUREFLAGS_USE_PROFILE_COLOR = 16 # Temporary 2025.1 fix for botched symbol export.
 
 class OcioNode2025(c4d.plugins.ObjectData):
     """Realizes a NodeData plugin that is meant to operate in OCIO enabled scenes.

plugins/py-rounded_tube_r13/py-rounded_tube_r13.pyp

@@ -242,9 +242,9 @@ class RoundedTube(c4d.plugins.ObjectData, RoundedTubeHelper):
         num_seg = op[c4d.PY_TUBEOBJECT_SEG] if op[c4d.PY_TUBEOBJECT_SEG] is not None else 36
 
         # Calculates LOD for subdivision parameter
-        sub = c4d.utils.CalcLOD(num_sub, 1, 1, 1000)
-        rsub = c4d.utils.CalcLOD(num_rsub, 1, 1, 1000)
-        seg = c4d.utils.CalcLOD(num_seg, 1, 3, 1000)
+        sub = c4d.utils.CalcLOD(int(num_sub), 1., 1, 1000)
+        rsub = c4d.utils.CalcLOD(int(num_rsub), 1., 1, 1000)
+        seg = c4d.utils.CalcLOD(int(num_seg), 1., 3, 1000)
 
         # Defines list of vector position of points
         ptCount = 4 * (sub + rsub)

scripts/02_data_algorithms/basecontainer_iterates_r13.py

@@ -18,7 +18,7 @@ def main():
         raise ValueError("op is none, please select one object")
 
     # Retrieves the data stored into the BaseContainer of the object
-    bc = op.GetData()
+    bc = op.GetDataInstance()
     if bc is None:
         raise RuntimeError("Failed to retrieve bc")
 

scripts/04_3d_concepts/open_color_io_2025_2.py

@@ -13,8 +13,8 @@
 
 
 def main():
-    # Retrieves a copy of the current documents render settings
-    rd = doc.GetActiveRenderData().GetClone().GetData()
+    # Retrieves the current documents render settings
+    rd = doc.GetActiveRenderData().GetDataInstance()
     if rd is None:
         raise RuntimeError("Failed to retrieve the clone of the active Render Settings.")
 

scripts/04_3d_concepts/rendering/render_current_frame_r12.py

@@ -15,7 +15,7 @@
 
 def main():
     # Retrieves a copy of the current documents render settings
-    rd = doc.GetActiveRenderData().GetClone().GetData()
+    rd = doc.GetActiveRenderData().GetClone().GetDataInstance()
     if rd is None:
         raise RuntimeError("Failed to retrieve the clone of the active Render Settings.")
 

scripts/04_3d_concepts/rendering/render_ogl_half_size_r12.py

@@ -85,7 +85,7 @@ def main():
     bmp.AddChannel(True, True)
 
     # Renders the document
-    if c4d.documents.RenderDocument(doc, rd.GetData(), bmp, c4d.RENDERFLAGS_EXTERNAL, prog=PythonCallBack,
+    if c4d.documents.RenderDocument(doc, rd.GetDataInstance(), bmp, c4d.RENDERFLAGS_EXTERNAL, prog=PythonCallBack,
                                     wprog=PythonWriteCallBack) != c4d.RENDERRESULT_OK:
         raise RuntimeError("Failed to render the temporary document.")
 

scripts/04_3d_concepts/rendering/render_with_progress_hook_r21.py

@@ -40,7 +40,7 @@ def main():
         raise RuntimeError("Failed to initialize the bitmap.")
 
     # Renders the document
-    if c4d.documents.RenderDocument(tempDoc, rd.GetData(), bmp, c4d.RENDERFLAGS_EXTERNAL) != c4d.RENDERRESULT_OK:
+    if c4d.documents.RenderDocument(tempDoc, rd.GetDataInstance(), bmp, c4d.RENDERFLAGS_EXTERNAL) != c4d.RENDERRESULT_OK:
         raise RuntimeError("Failed to render the temporary document.")
 
     # Frees the temporary document, means that all objects from this document are no longer alive.

scripts/04_3d_concepts/scene_elements/scene_management/basedocument_creates_render_r13.py

@@ -0,0 +1,86 @@
+"""Demonstrates the technical aspects of #GraphDescription.ApplyDescription calls.
+
+To run the script, paste it into the Script Manager of Cinema 4D and execute it.
+
+Note:
+    This example is more about the technical aspects of #GraphDescription.ApplyDescription and
+    therefore less relevant for beginners.
+"""
+import c4d
+import maxon
+import mxutils
+
+__author__ = "Ferdinand Hoppe"
+__copyright__ = "Copyright (C) 2024 Maxon Computer GmbH"
+__version__ = "2025.0.0+"
+
+doc: c4d.documents.BaseDocument # The active document
+
+def main() -> None:
+    """Called when Cinema 4D runs this script.
+    """
+    # The graph description we are going to apply in the different #ApplyDescription calls, the
+    # content of the graph is here irrelevant for this example, other than it is intended for a
+    # Redshift material graph.
+    redshiftDescription: dict = {
+        "$type": "Output",
+        "Surface": {
+            "$type": "Standard Material",
+            "Base/Color": (1, 0, 0),
+            "Metalness": 1.0,
+            "Reflection/IOR": 1.1415
+        } 
+    }
+
+    # A Standard Renderer and Redshift material graph we are going to use in the example.
+    standardGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="Standard Material", nodeSpaceId=maxon.NodeSpaceIdentifiers.StandardMaterial)
+    redshiftGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="Redshift Material", nodeSpaceId=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+
+    # This is how we usually call #ApplyDescription, we just pass the graph to modify and the
+    # description to apply.
+    maxon.GraphDescription.ApplyDescription(redshiftGraph, redshiftDescription)
+
+    # A description that is not intended for the graph its is applied to will always fail at some
+    # point because the node types referenced in the description are then not contained in the node
+    # space of the graph. But because node spaces share some node types, as for example the value
+    # node, it can take some time until the graph description fails. But one can never end up with
+    # a half way executed graph description due to the transaction logic of the Nodes API. A graph
+    # description #ApplyDescription call either succeeds in its entirety or fails as a whole.
+    
+    # This cannot work, we are trying to apply a Redshift graph description to a standard graph.
+    try: 
+        maxon.GraphDescription.ApplyDescription(standardGraph, redshiftDescription)
+    except Exception as e:
+        print(e) # Will print :
+        # "The node type reference 'Output' (lang: 'en-US', space: 'net.maxon.nodespace.standard') 
+        #   is not associated with any IDs. [graphdescription_impl.cpp(1648)] ..."
+
+    # #ApplyDescription offers a node space ID argument which allows the user to manually state of
+    # which type the passed graph description is. There is no concrete technical advantage in doing
+    # this other than ending up with more verbose code and the fact that such calls for a mis-matching
+    # graph will fail right away and not only when already half of the description has been executed
+    # and the graph then having to be unwound for a failed graph transaction.
+
+    # Cannot work either, but might will a bit more gracefully for complex graph descriptions.
+    try: 
+        maxon.GraphDescription.ApplyDescription(
+            standardGraph, redshiftDescription, nodeSpace=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+    except Exception as e:
+        print(e) # Will print:
+        # "User defined node space 'com.redshift3d.redshift4c4d.class.nodespace' does not match 
+        #   passed graph."
+
+    # A more impactful option is the language of the graph description. Currently graph descriptions
+    # only support the English language for label references. When no language is given, Cinema 4D
+    # assumes the system language (because at its core graph descriptions are already designed for
+    # other languages environments than en the English language). By passing "en-US" we can force
+    # force a non-English interface labels Cinema 4D instance to resolve the graph description as if
+    # it were English.
+
+    maxon.GraphDescription.ApplyDescription(
+            standardGraph, redshiftDescription, nodeSpace=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+    
+if __name__ == "__main__":
+    main()

scripts/05_modules/node/graph_descriptions/applying_descriptions.py

@@ -0,0 +1,86 @@
+"""Demonstrates how to retrieve graphs from scene elements.
+
+To run the script, paste it into the Script Manager of Cinema 4D and execute it.
+"""
+import c4d
+import maxon
+import mxutils
+
+__author__ = "Ferdinand Hoppe"
+__copyright__ = "Copyright (C) 2024 Maxon Computer GmbH"
+__version__ = "2025.0.0+"
+
+doc: c4d.documents.BaseDocument # The active document
+
+def main() -> None:
+    """Called when Cinema 4D runs this script.
+    """
+    # The most common use case for GetGraph is to create a new material and graph from scratch.
+    # The call below will result in a new material being created in the active document with the
+    # name "matA". Since we are not passing an explicit node space, the currently active material
+    # node space will be used (which usually is the Redshift node space for most users).
+    graphA: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(name="ActiveNodeSpace")
+    print(f"{graphA = }")
+
+    # This will create a material named "matB" that has a graph in the Redshift material node space,
+    # no matter what the currently active material node space is.
+    graphB: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="RedshiftSpace", nodeSpaceId=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+    print(f"{graphB = }")
+
+    # But we can also use the function to create or get a graph from an existing material. The call
+    # below will either create a new Redshift graph for the first material in the document #material
+    # or return its existing Redshift graph. The CheckType call exists so that the script halts when 
+    # there is no materials in a document. But since we just crated #matA and #matB, we will here 
+    # just retrieve the graph from "matB" (because new materials inserted in front at not at the end). 
+    # I.e., #graphB and #graphC are the same.
+    material: c4d.BaseMaterial = mxutils.CheckType(doc.GetFirstMaterial())
+    graphC: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        material, nodeSpaceId=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+    print(f"{graphC = }")
+    print(f"{graphB == graphC = }")
+
+    # We could also create a Standard Renderer graph, or a third party render engine graph such
+    # as Arnold or VRay for example.
+    graphStandard: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="StandardSpace", nodeSpaceId=maxon.NodeSpaceIdentifiers.StandardMaterial)
+    
+    try:
+        vrayGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+            name="VRaySpace", nodeSpaceId="com.chaos.class.vray_node_renderer_nodespace")
+    except Exception as e:
+        print (e)
+
+    # We can also pass a document or an object for the first argument #element of GetGraph. If we
+    # pass a document, it will yield the scene nodes graph of that document, and if we pass an object,
+    # it will yield its capsule graph (if it has one).
+    sceneGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(doc)
+    print(f"{sceneGraph = }") 
+
+    # Finally, we can determine the contents of a newly created graph. We can either get an empty
+    # graph or the so-called default graph with a few default nodes as it would be created in
+    # Cinema 4D when the user creates a new graph for that space. #createEmpty=True is the default
+    # of a #GetGraph call.
+    emptyGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="ActiveSpaceEmptyGraph", createEmpty=True)
+    defaultGraph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="ActiveSpaceDefaultGraph", createEmpty=False)
+    
+    # Finally, there is also GraphDescription.GetMaterialGraphs which simplifies iterating over all
+    # material graphs of a given node space in a document. This can simplify carrying out batch
+    # operations on material graphs for a specific render engine, while keeping other render engines
+    # untouched. Other than GetGraph, this function will not create new graphs when none exist.
+
+     # Print all Redshift renderer material graphs in a document. This will be at least one graph,
+     # because created explicitly one in this script.
+    graph: maxon.NodesGraphModelRef
+    for graph in maxon.GraphDescription.GetMaterialGraphs(doc, maxon.NodeSpaceIdentifiers.RedshiftMaterial):
+        print(f"Redshift graph: {graph}")
+
+    # Same for the Standard renderer material graphs. This will also be at least one graph, because
+    # created explicitly one in this script.
+    for graph in maxon.GraphDescription.GetMaterialGraphs(doc, maxon.NodeSpaceIdentifiers.StandardMaterial):
+        print(f"Standard graph: {graph}")
+
+if __name__ == "__main__":
+    main()

scripts/05_modules/node/graph_descriptions/getting_graphs.py

@@ -0,0 +1,53 @@
+"""Demonstrates the core concepts of graph descriptions by creating a simple material.
+
+This script will create a red metallic material with an index of refraction of 1.1415 in the Redshift
+node space. To run the script, paste it into the Script Manager of Cinema 4D and execute it.
+
+Note:
+    This is the brief version of the hello_world script. See hello_world_narrative.py for a narrative
+    documentation of this script.
+"""
+__author__ = "Ferdinand Hoppe"
+__copyright__ = "Copyright (C) 2024 Maxon Computer GmbH"
+__version__ = "2025.0.0+"
+
+import c4d
+import maxon
+
+doc: c4d.documents.BaseDocument # The active document
+
+def main() -> None:
+    """Called when Cinema 4D runs this script.
+    """
+    # Get a new  material named "Hello World" which has a graph in the Redshift node space.
+    graph: maxon.NodesGraphModelRef = maxon.GraphDescription.GetGraph(
+        name="Hello World", nodeSpaceId=maxon.NodeSpaceIdentifiers.RedshiftMaterial)
+
+    # Apply a graph description to the graph.
+    maxon.GraphDescription.ApplyDescription(
+        graph, 
+        # The description which is applied to the graph. We are going to write a simple description
+        # of a Standard Material node connected to an Output node. Note that graph descriptions flip
+        # the reading direction of graphs from the usual left-to-right to right-to-left. They
+        # start out with the terminal end node of the graph and then describe the nodes leading to
+        # that node. Each scope (a pair of curly braces) in the description describes a node.
+        {
+            # We describe the terminal Output node of the graph.
+            "$type": "Output",
+
+            # We describe the value of the Surface port of the Output node which is connected to the
+            # outColor port of a Standard Material node.
+            "Surface": {
+                "$type": "Standard Material",
+
+                # We set a  few ports of the Standard Material node to literals, i.e., constant 
+                # values that are not driven by other nodes.
+                "Base/Color": (1, 0, 0),
+                "Metalness": 1.0,
+                "Reflection/IOR": 1.1415
+            } 
+        }
+    )
+
+if __name__ == "__main__":
+    main()