It’s been a long time… how have you been?

This is going to be another Python/Cinema 4D related post.

While python is great for quickly scripting workflow optimizing tools, prototype stuff or write generators and tags, is it suited for big, complex plugin development?

It is!

You get ‘nearly’ full access to the C++ API of Cinema 4D, don’t have to compile or worry much about platform dependencies, can easily find a ton of neat recipes and libraries out there…

So it’s not only possible to code full-fledged python plugins but it even has its advantages over classical C++ development.

Imagine you wrote a nifty script, decided to make it a simple plugin, and now want to take it a step further – add more features, a complex GUI with some dialogs etc…

If you are still working with the script editor by now, things will most likely start to get out of hand as you introduce more modules and classes, deal with more code and more functionality.

This is the point where you might want to look out for a little help.

We are going to set up an IDE (Integrated Development Environment), talk a bit about modules/packages and finally I will try to give some general hints and tips.

Coding Environment/IDE:

Prepare Cinema 4D:

You may skip this part, but I highly recommend it:

• Make a copy of your Cinema 4D installation – name it “Cinema 4D R12 Dev” for example.
• Get rid of all Cinema 4D plugins you don’t need for your development
• Place an empty text file named “c4d_debug.txt” into the root folder of your Cinema 4D copy.

This will slow Cinema 4D down a bit, but enables you to monitor memory leaks.

We will add some useful things on Cinema 4D-side later – for now let’s continue with the Eclipse setup…

Eclipse:

If you never used one, think of an IDE as your workshop, it’s a collection of tools as well as the place where you do and organize your coding work.

Eclipse is one of the most popular – its Java based, open source, free to use and most importantly has excellent support for python.

So let’s start by downloading and installing Eclipse Classic from http://www.eclipse.org/downloads/
If you don’t have the Java Runtime Environment installed jet, you need to do this first.

PyDev:

As said before, Eclipse has excellent python support – but not out of the box, so we are going to install PyDev.

PyDev will help you coding by adding syntax highlighting, code completion and much more.
Should you encounter any trouble with the following steps, please refer to the PyDev installation manual.

• After installation, startup Eclipse, click “Help”, and chose “Install New Software…”.
• Next click the “Add…” button, type in “PyDev” as name and “http://pydev.org/updates” as location – then confirm.
• Now enter “PyDev” in the “Work with:” field, you should see an entry “PyDev for Eclipse” - check it and click “Next”.

After confirming again and accepting the terms, it will download and install.

• Click “Windows” and open the “Preferences” dialog.
• Select PyDev and the child “Interpreter – Python”
• Click “New…”, input “Python Cinema 4D” as name and browse to your Cinema 4D installation.
• In “/resource/modules/python/res/Python.win64.framework/” select the python.exe.
• Confirm your selection and the paths PyDev wants to add to your syspath.

So much for the PyDev installation itself, now we have to associate the Cinema 4D Python plugin extension *.pyp with PyDev to enable syntax highlighting and code completion for those files as well:

• Open ‘Window’ within the file-menu and click ‘Preferences’
• Select ‘General’ -> ‘Content Types’ from the list on the left.
• In the ‘Content types:’ view on the right, unfold ‘Text’ and click ‘Python File’
• Hit the ‘Add…’ button of the ‘File associations:’ list on the lower right, type “*.pyp” into the popup and confirm.

Its helpful to add a file containing all symbols of the Cinema 4D Python API’s “c4d” package to the ‘site-packages folder to spice up the auto-completion – grab it here.

Place the file within “/resource/modules/python/res/Python.win64.framework/Lib/site-packages“

Note:

You will have to update this file if you want to keep up to date with future versions of Cinema4D, it can be easily printed to the console by executing:

for itm in dir(c4d):
    s = getattr(c4d, itm)
    print "%s = %s" % (itm, s)

Project setup

We take your IDE for a spin and create the first project:

• Click “File” – “New” and chose “PyDev Project”
• Input a Name for your Project and uncheck the “Use default” box below.
• Browse to your Cinema 4D installations plugin folder, create a new directory with your plugins name and select it.
• Select “2.6″ from the “Grammar Version”- dropdown and leave the Interpreter set to default.
• Last but not least uncheck the “Create default ‘src’ folder…” checkbox and hit “Finish”.

To setup the needed folder structure, header- resource- and string files for your plugin, please read the Cinema 4D Python documentation “Plugin structure” –  especially “Directory structure” – and take a look at the Python plugin examples within the documentation – or the experimental plugin from this post:

Just remember this part is vital, so do not rush through it – at least read the section mentioned above and take a good look at the SDK examples.

Only if you have built C++ plugins before and are already familiar with the structure, you may…

Hint:

You can also add your existing project files by just placing them within the plugin-directory we just created, or dragging them into the project-folder within Eclipse.

When organizing the file structure within your project, you are working with your file system – changes you do here are reflected on your harddisk.
This also works the other way round, move something on the file system and Eclipse will update those changes to your project – while not always instantly.

You can press F5 within Eclipse to update a folder and its subfolders or the contents of a file.

Don’t worry, if the project-view is out of sync with the file system – Eclipse will tell you.

A coders Cinema 4D:

We are all set with the IDE part – let’s tune the Cinema 4D installation a bit more to improve the workflow and finalize your coding environment.

If you didn’t add/import your existing code to the project we just created, write a simple hello world and fire up Cinema.

It’s a good idea to setup a developer friendly layout, I like adding the console window to the tabs on the right, next to the object manager – or even better to a side monitor.
Should you be writing a CommandData Plugin, consider opening the Command Manager and dragging its icon into the layout, so you can quickly re-open it.

You will be launching and closing Cinema 4D a lot during development – it’s helpful to have a strategy to quickly start and close it.
Place a link to Cinema 4D on your taskbar/dock, close it using ALT+F4/Command+Q or create a little python script containing “exit()” and add it to the layout/create a shortcut.

Finally, open your Plugin as well as everything you need to test its functionality and save the layout as startup layout.

If you have a test document that you need to check your plugin, press CTRL+E, click the “Open Preferences Folder…” button and place it as “default.c4d” within that folder so it will load on startup.

You long got the idea – try to prepare everything so you don’t have to spend time doing recurring tasks on every unit-test you are going to make during development.

Some additional tools:

It’s often helpful to keep an eye on memory consumption and or active threads so I always have the task manager/activity monitor in reach when coding.

And while not really necessary, it’s convenient to have a good, fast text editor with Python syntax highlighting so you are able to read a file or snippet without having to launch the IDE first.
I can recommend Notepad++ and TextMate or Emacs for this job.

Working with eclipse:

Eclipse in combination with PyDev is a mighty! tool – Aside from the obvious killer features – syntax highlighting and code completion, there is a ton of others.

Often you will discover some that will make you feel bad for not having used them right from the start, so I’ll try to point out the most useful, while I encourage you to read up on Eclipse and PyDev.

The Find/Replace Dialog

Press CTRL+F for all your search and replace needs – just listing it to make you aware of the direction-, selection- and regex support.
If you haven’t used regular expressions jet, you should directly head over to Wikipedia - you won’t regret it.

Even more powerful is the…

Search Dialog

CTRL+H opens the global or project wide search – here you can also replace over all files.

Just keep in mind that the “PyDev Search” tab does only look within *.py files while the “File Search” tab by default searches over a *.* pattern.

Compare feature and history

Just select two files, right click and chose “Compare with” -> “Each other”.

You can also compare a file with an earlier state of itself by choosing “Local history”.

This is another huge plus of using an Eclipse – don’t worry anymore about changing huge sections of code or commenting it – just go ahead and delete it – you can always return to an earlier state using the “History”- tab.

But use this with care, as it’s possible to lose the history by moving or re-creating a project and it’s not infinite.

Tabbed views

You can drag a tab to one side of the code view until a small arrow appears – the tab will then snap to that side, splitting your view so you can work with multiple source files at the same time.

This is very useful when working with the header-, resource- or string files of your project as you can code on the left and copy ‘n paste ID’s from the right for example.

Coding python for Cinema 4D:

We have setup the coding environment – how about doing some programming now?

This will be a loose collection of tips that are all more or less Cinema 4D related, but mostly  good practice in general.

Modules and namespace:

First – this is OOP (Object Oriented Programming) and your project’s structure should reflect that.

In general, classes and modules are a good thing, it’s a far more common fault to have less abstraction than too much.

Packages/Modules are also the key to keep your code organized, manageable – AND reusable.

So if you are going to write something that you might want to use again later, consider spending the extra time to make it a bit more user/coder-friendly and build a class or module.

When working with python and modules you have to keep a close eye on naming and namespace, especially in context with the Cinema 4D SDK.

Be creative and use unique module names – this will keep things easier when you are using other modules – and you will – at least the ones from the Cinema 4D API.
Also be careful when importing from modules – it’s rarely a good idea to just import everything (from foo import *) – instead carefully select the members you really need and give everyone its own import line rather than stacking them with commas in one.

It’s often better to just import the module into your namespace and reference the members via module.foo – you don’t pollute your namespace and it’s more readable.

In any case you should avoid the API’s module AND member names like the plaque.

For example if you extend the GeDialog Class and have a method “def close(self):” – but make the slight mistake to call it as “Close()”, you might end up with a similar behavior but wonder for minutes while your dialog just closes without saving it’s settings first (or whatever “close()“ should have done).

I know for some this is basic stuff – many have their own patterns for this and that’s ok!

Whatever you do – be consistent and aware of your namespace.

Symbols:

As you need to keep track of the enums within the c4d_symbols.h, it is best to define every integer by yourself and not auto-enumerate them.

Then mirror those symbols to a *.py file called “ids.py” and be careful to update both should you change them or introduce new ones.

Instead of hardcoding ID’s, you should always use the symbol within the c4d-package.
Should you ever need to identify a symbol by it’s integer value (for example if you want to check for a certain flag that is returned) – this little script will help you out:

import c4d;
from c4d import gui; 

def main():
    wanted = gui.RenameDialog("ID to search for...")
    outp = ""

    for itm in dir(c4d):
        s = getattr(c4d, itm)
        if s == int(wanted):
            outp += "%s = %s\n" % (itm, s)

    gui.MessageDialog("Sorry - none found..." if outp == "" else outp)

if __name__=='__main__':
    main()

API calls / performance:

Don’t get me wrong – the Python API is blazing fast – so fast you often can’t tell the difference to C++ – but still, API calls take time.
When working with thousands of objects, this quickly adds up no matter how fast each individual call is.

Try to limit those calls in sections of your code, where you really need performance – look for ways to keep states within your own plugin logic rather than querying them form Cinema 4D whenever possible.

If you are looking for bottlenecks, be sure to check out cProfile – it’s great.

Prototyping:

Using an IDE doesn’t forbid you to use Cinema 4D’s script editor and console to quickly whip up and test something – you can even write and directly execute a simple test script within eclipse if you are working on parts of your plugin that don’t need the Cinema SDK (some kind of parser for example) and take advantage of the PyDev debugger.

Debugging:

The lack of a real debugger can be compensated by using the PyDev remote debugger, pythons inspect module and the logging package.

Remember that there is a limit to the amount of characters the Cinema 4D console can output for a single print command.

Also take a look at sys.exc_info()

Garbage Collection:

When introducing circular references you should use weak references to give the garbage collector a hand.

Compilation:

How about shipping your plugin as precompiled byte code?

This will make Cinema 4D start up faster – as the compilation of your plugin can be skipped, obfuse your source and still be platform interoperable.

Just copy your plugin, open the console/terminal and execute “python.exe -mcompileall C:\PathToMyPlugin” and delete all *.py files afterwards.

Note that this might not work in some cases, so be sure to test your plugins functionality again.

Platform dependency:

While Python is platform-independent, there are still some things to keep in mind.

Don’t use backslashes in paths but slashes – they are understood by windows AND mac OS.

You can also use platform.system() to determine on what OS your plugin runs on and import modules after a conditional check – for example:

if platform.system().lower() == "windows":

    import winsound
    winsound.PlaySound(os.path.join(os.path.dirname(__file__), "../res/snd", "DingSound.wav"),
winsound.SND_FILENAME)

GUI – Threading:

It’s the old story, if the GUI thread has to wait for your plugin, you lock up Cinema 4D – unacceptable for the user.

Doing time intensive stuff within your own threads is the simple solution to this, but keep in mind that you can’t have them call the GUI thread – instead use messages and the GeDialog’s SetTimer().

Resource reference:

Classes that use the “plugins” module need a reference to the plugins resource pointer.

This can be handled by importing those classes within the plugins *.pyp file and setting the class variable “__res__” or using a singleton (see below).

Singletons and invading Borgs:

This is something for the advanced developer – and kind of a hot topic too.

The use of globally accessible objects or ‘globals’ is often considered bad practice but also unavoidable in some cases (logger) and python even somewhat encourages it.

So if you know what you are doing and think about using a singleton, you might want to take a look at the “borg”-(anti)pattern – a monostate proxy with a twist.

class Borg:

__we_are_one = {}

    def __init__(self):       
    self.__dict__ = self.__we_are_one

Still alive

This was a lot of compressed stuff to digest, I know, but please do me the favor and don’t let any of this scare you off, it’s easier and more fun than you would expect.

I am sorry some topics where not covered in the depth they deserve -  it wasn’t easy to keep this a readable post rather than a book…

I hope this still was helpful to someone, if you have any questions, thoughts or would like me to write a more detailed post on a certain topic – let me know.

Sebastian Rath´s PY4D is a new, alternative way to script with or to code plugins for Cinema4D – without COFFE or C++ – but in Python.

The current beta (v0.9.0001) already makes a fine impression and proves itself easy to get started with.

This video shows a little script that was adapted in a twinkling and controls the particles of a TP-Storm to behave after the three flocking boids rules.
Don has rendered a much prettyer version of the dummy above.

You can download the C4D-scene here.

Update: The file has been updated to work with the R12 version of Cinema 4D.