Python Scripting

From VFXPedia

Jump to: navigation, search

This page provides an overview of using Python with Fusion. Much of the LUA scripting documentation applies to Python as well - just the syntax is different. Here's some information to get you started and a look at some caveats.


Getting Started

  • Fusion allows you to add .py files alongside .eyeonscript files in the Scripts: directory's subfolders (comp, tool, ...)
  • The scripting console can be switched between LUA and available python versions. Since Fusion 6.2, you can install Python 2.7 or 3.1 as Fusion supports either one. The console will have buttons for "Py2" or "Py3" respectively. Fusion 6.1 still comes with its own version of Python and its console button is labeled "Pyth".

Image:F62 PythonConsole.png

  • Install Python by downloading the 2.7.x or 3.2.x installers here:
  • To control Fusion from an external Python interpreter, use the PeyeonScript bindings. They are available for Python 2.6, 2.7, 3.1 and 3.2 (both 32 and 64bit) and can be downloaded alongside Fusion from eyeon's website.

Video Tutorials

Blazej Floch has recorded a four-part series of video tutorials on how to use Python with Fusion. It covers setup, modules, peyeonscript and the famous rigid body simulation comp.. Watch part 1 (intro), part 2 (accessing tools), part 3 (rigid bodies) and part 4 (python modules) on Youtube.

Stefan Ihringer's scripting 101 video, while explaining the basics of LUA scripting, can easily be adapted to Python. It covers creating and connecting tools, setting their input values and some file name handling. Watch it on YouTube.

Stefan Ihringer's scripting 102 covers a rewrite of the Bake Animation tool script in Python. Topics include: OOP, inputs, attributes and keyframes. Watch it on YouTube. The finished script can be found in the Useful Scripts section.

Coding Reference

Differences to LUA


  • InTool scripts & expressions can't be written in Python.
  • Scriptlibs are unavailable as well. However, you can create your own Python modules, as described in part 4 of Blazej's video tutorial.


  • The Python console doesn't have a neat shortcut to dump the contents of a variable. You'll have to use a print statement or the Pretty Print module instead. Also, the console doesn't allow multi-line input (yet).
  • While the console history is shared between LUA and Python, variables defined in one language are not automatically available in the other language.
  • Help() doesn't work the same as in LUA mode. You can get help by printing the return value of the GetHelp() method that is available on every object. This example uses the fusion variable, it could also be any composition or input object. Note that LUA syntax is used throughout the help text. You need to substitute the colon with a dot for function calls.
print(fusion.GetHelp("Composition"))    ## equivalend to LUA's Help("Composition") 
  • In the LUA console, all the comp's tools are automatically available as global variables (if they don't conflict with existing variables). This isn't the case in the Python console, where the tool handles are part of the corresponding composition object:
  • For the same reason, LUA allows you to call methods and access members of the current composition object directly. This is not possible in Python:
-- works in LUA
# throws exception in Python...
# ...since it needs the comp object

Function Calls

  • To exit a Python script prematurely, raise and catch an exception. Calls to sys.exit() can be used in Fusion 6.31 or later. (In earlier versions, this will quit Fusion instead.)
# In LUA you would print an error, then call exit().
# In Python, raise an exception with an error string attached and enclose everything in a try: block
    if tool is None:
        raise Exception("This is a tool script, you must select a tool in the flow to run this script.")
    # rest of script goes here...
except Exception as e:
   print e
  • Functions that expect tables will expect dictionaries in Python.
  • LUA allows you to omit table indices and quotation marks, which often results in tidier code:
attrs = [TOOLS_Name = "mytool", "something else"]

For Python's dictionaries, you need to add numeric keys (1-based instead of zero-based!) for each item in the table that isn't already a key-value-pair. Every non-numeric key needs to be a quoted string:

attrs = {"TOOLS_Name": "mytool", 1: "something else"}

For more examples see the tips for AskUser().

  • To assign 2D position coordinates to inputs, you need to assign dictionaries as well. For example:
Transform1.Center = {1: 0.5, 2: 0.5}
  • GetPos(), which returns the coordinates of a tool in the flow, doesn't work in Python. Instead, use GetPosTable() which returns x and y as a dictionary object.
Personal tools