Python SDK example for Cinema 4D 2024.4.0

Author: maxon-madam

scripts/04_3d_concepts/modeling/modeling_commands/smc_extrude_s26.py

@@ -11,33 +11,37 @@
     * c4d.utils.SendModelingCommand()
 
 Overview:
-    There are in principle two ways to execute modelling commands: In the original document a node
-    is contained or in a dummy document. This latter case is carried out by creating a dummy 
-    document just for the command, cloning the relevant nodes into that document, and then executing
-    the command there. In most cases, executing a modelling command in the original document which 
-    could be a loaded document, and therefore subject to threading restrictions, will cause no 
-    issues, but there are some notable exceptions:
+    There are in principle two ways to execute modeling commands: In the original document a node
+    is contained in or in a dummy document. The latter case is carried out by creating a dummy 
+    document just for the command, cloning the relevant node(s) into that document, and then 
+    executing the command there. In most cases, executing a modeling command in the original 
+    document - which could be a loaded document and therefore subject to threading restrictions - 
+    will cause no issues, but there are some notable exceptions:
     
-      * SMC calls which are not done from a non-main thread for a node in a loaded document.
+      * SMC calls which are not done from a non-main thread context for a node in a loaded document.
+        This could for example be an SMC call in an object plugins GetVirtualObjects method that is
+        meant to modify an input object of the plugin. Think of an extrude object plugin that has 
+        for example the option to bevel its input spline.
       * Tools or tasks for which the complexity of a document directly impacts runtime of the tool
-        but not the result of the tool; imagine huge amounts of irrelevant data the tool might has 
+        but not the result of the tool; imagine a huge amount of irrelevant data the tool might has 
         to traverse.
       * Some tools require setups which make a dummy document desirable, e.g., the 'Join' tool.
     
     But using a dummy document has also drawbacks:
       
        * It is computationally much more demanding since all relevant data has first to be copied 
-         over and then back again.
+         over to the dummy document and often then also back again to an 'original' document.
        * Inserting the SMC result back into its original document can be labour-intensive when the
-         result is meant to replace the original object and cannot be inserted as new object. For 
+         result is meant to replace the original object and cannot be inserted as a new object. For 
          example all BaseLink parameters in that document which link to that node must then be found
          and updated too.
-       * Determining what is relevant for a tool can be hard. In some cases it might be not enough
+       * Determining what is relevant for a tool can be hard. In some cases it might not be enough
          to copy over a single object, and instead non-obvious dependencies which influence the 
          outcome of the tool are required too. The 'Current State to Object' tool is such example, 
          as the state of an object can depend on many things as for example fields, effectors, and 
          tags. In these cases it is best to clone the whole document; documents are nodes and can 
-         therefore be cloned themselves. But it will further increase the footprint of the command.
+         therefore be cloned themselves. But it will further increase the time and memory complexity
+         problem of the approach.
     
     Showcased in this example is primarily the more complicated case of executing the command in a 
     temporary document. But in general it is more desirable to execute SMC in the document the node
@@ -75,18 +79,18 @@ def main(doc: c4d.documents.BaseDocument, op: typing.Optional[c4d.BaseObject]) -
         raise MemoryError("Could not create new document.")
     temp.InsertObject(clone)
 
-    # A modelling command invokes one of the modelling tools of Cinema 4D. The function takes
+    # A modeling command invokes one of the modeling tools of Cinema 4D. The function takes
     # therefore container for the settings of that tool, in this case for the Extrude tool.
     bc = c4d.BaseContainer()
     bc[c4d.MDATA_EXTRUDE_PRESERVEGROUPS] = True # Preserve element groups in extrusions.
     bc[c4d.MDATA_EXTRUDE_OFFSET] = 50.0 # The extrusion depths.
     # There are many more options for that tool as exposed in toolextrude.h
 
-    # A modelling command takes a list of objects as one of its inputs. In this case it is just a 
+    # A modeling command takes a list of objects as one of its inputs. In this case it is just a 
     # list containing the node #clone.
     objects = [clone]
 
-    # A modelling command has also a mode of operation. The extrude tool for example behaves 
+    # A modeling command has also a mode of operation. The extrude tool for example behaves 
     # differently, depending on in which editor mode (point, edge, polygon, object) the document 
     # is in. E.g., being in edge mode will extrude the active edge selection. The example here ties 
     # the SMC mode to the mode of active document. There are also more SMC modes than shown here.
@@ -100,7 +104,7 @@ def main(doc: c4d.documents.BaseDocument, op: typing.Optional[c4d.BaseObject]) -
     else:
         raise RuntimeError(f"Document is not in any of the modes supported by the extrude tool.")
 
-    # Finally, a modelling command also takes a set of flags. With them the command can for example
+    # Finally, a modeling command also takes a set of flags. With them the command can for example
     # be automatically wrapped in an undo. Since this example operates on a temporary 'throw-away'
     # document, the flags are being set here to the none-flag.
     flags = c4d.MODELINGCOMMANDFLAGS_NONE
@@ -111,7 +115,7 @@ def main(doc: c4d.documents.BaseDocument, op: typing.Optional[c4d.BaseObject]) -
     res = c4d.utils.SendModelingCommand(command=c4d.ID_MODELING_EXTRUDE_TOOL, list=objects, 
                                         mode=mode, bc=bc, doc=temp, flags=flags)
     if not res:
-        raise RuntimeError(f"Modelling command failed for {op}.")
+        raise RuntimeError(f"modeling command failed for {op}.")
 
     # The same call when not going the temporary document route, and instead carrying out the 
     # command directly on the node in the active document. The the file documentation for details.

scripts/04_3d_concepts/readme.md

@@ -21,4 +21,6 @@ The Cinema 4D API provides classes to describe complex 3D scenes and tools to ed
   * **scene_management**: *Scene management such as layers, markers, undo, etc...*
 
   * **take_system**: *The Take System makes it possible to handle variations of a scene in one BaseDocument.*
+
+* **simulation**: *Contains code examples for the simulation tools of Cinema 4D, such as its particle system.*