P4D101 - Getting started with Python in Cinema 4D

The Python integration into Cinema 4D is quite thorough. There are several places where you can use Python to script and Python is integrated as a first class citizen with the same level of access like Cinema 4D’s internal scripting language COFFEE as well as the C++ API.

There are different places in which you can use Python:

• as Python Script
• as Python Generator
• as Python Tag
• as Python Xpresso Node
• as Python Plugin

As you can see, there are plenty of options to use Python in Cinema 4D. For a start let us focus on using a Python script - ignoring the other possibilities for now.

Python Script

Python scripts are probably the most immediate way to perform automated tasks. To create a script open the Script Manager (Python) from the Python menu. Also open the Console (Python) from the same menu. The console will show you error messages and output from print\ statements in your Python script.

When you have not done something in Cinema 4D before the Script Manager should already contain this code:

    import c4d

    from c4d import gui
    #Welcome to the world of Python

    def main():
        gui.MessageDialog('Hello World!')

    if __name__=='__main__':
        main()

The executed part

Now let us examine this a bit closer. For a start let us ignore the first few statements and look at the parts that actually do something:

    if __name__=='__main__':
        main()

This is the part that get’s executed when Cinema 4D runs the Python script. When a Python program is loaded as script, Python sets the variable __name__ to the value of "__main__". This way a Python script knows it has been called as script rather than having been imported.

This brings us to the first statements - the import:

Imports

    import c4d

    from c4d import gui

The import statement loads existing Python code from another file - a module. The Python binding to Cinema 4D is defined by the c4d module. By importing the c4d module you gain access to Cinema 4D’s functions through the API (Application Programming Interface). Within the c4d module there are several specialized packages that handle different parts of the API. One of those packages is c4d.gui that deals with the graphical user interface functions and classes.

    from c4d import gui

This statements imports the gui package from the c4d module. This is an optional step that makes the gui functions available without the need to prefix them with the c4d module name (the namespace). Without the above statement you would have to explicitly prefix the gui.MessageDialog() function with c4d.

    import c4d

    c4d.gui.MessageDialog("Hello World!");

Condition and Code Block

Back to the actual code:

    if __name__== '__main__':
        main()

The conditional if statement checks the __name__ variable for the value of '__main__'. If this is true - so the program was loaded as script - the code block in the if statement is executed. Here, the previously defined function main() is called.

In Python a code block (=scope) like within a if statement or a function is defined by indenting the code rather than having curly brackets { } like eg. in COFFEE. You need to pay attention to have the identical number of whitespace characters when indenting. Different levels indicate different code blocks. Generally I would advise you to use spaces and no tab characters. Indenting by four spaces is a widely used format.

Print

Instead of defining a function first and then calling it when the script is executed you can also write your code here:

    if __name__ == "__main__" :
        print "Hello World!"

This would output the text “Hello World!” into the Python console rather than popping up a dialog window like MessageDialog() does. The advantage of print is that it does not interrupt the execution of the script like the dialog window that requires the user to press the OK button. So print is a great way of outputting debugging data to the console that can show you what is happening in your script. This makes it easier to find errors when something goes wrong. The disadvantage of print is that is only shows in the console which a normal user generally does not have open when using scripts. So avoid print for displaying data that is important to the user.

Functions

In the example code there is definition of the function main() that is being called from the script rather than immediate code:

    def main():
        gui.MessageDialog('Hello World!')

This def statement defines a function named main(). The code following the definition is indented to contain the code block for the function. In this case a popup window with the text “Hello World!” is shown. This function only contains this one statement and does not have parameters or return values. We will have a look on how to use those in a later article.

In the example the function main() is called below using the statement main().

Summary

This was a very brief introduction into Python scripting in Cinema 4D by looking at the default script that is generated when opening the Script Manager.

What we have learned is:

• how Python scripts are executed in Cinema 4D (it defines __name__ as "__main__" conforming to general Python scripts)
• how Python can access Cinema 4D’s API through the c4d module and how to use import to use the c4d module and its packages
• how to use the print statement to output text to the Python console
• how to define a basic function using the def statement and how to call it

In future articles we actually will have a look at how to do something meaningful in a Python script like working with the current scene and how to use variables to store values and how to save your scripts so you can reuse them.

For further information have a look at the Python 2.6.4 documentation and Maxon’s documentation on their Python integration.