Python Scripting in Cascadeur

There might be times when built-in Cascadeur functionality, versatile as it is, just won’t be enough. For cases like these, there is an option to use Python scripting.
Python scripts allow you to:

• Use built-in scripts to extend Cascadeur functionality.
• Automate frequently-used operations.
• Access objects’ inner structure without using Node Editor.

Enabling Python Console

Python console can be enabled by selecting Python console item from the Window menu:

This will open the Python console window.

Python Console Overview

Load
Opens a .py file containing a Python script and loads it into the console.

Save
Allows you to save the script in the console to a .py file to use it later, or with a different scene.

Close
Closes the console window.

Execute
Runs the script in the console.

It should be noted, however, that the console only offers very limited functionality for working with Python code. It is intended primarily for running scripts, not for writing them.
If you are planning to write complex scripts for Cascadeur, we recommend to use an external IDE such as Atom, Visual Studio, PyCharm.

Writing Scripts

Scripts are written in the main area of the console. Cascadeur uses Python 3.8.

Modules and Libraries

Python scripting uses the csc module for accessing Cascadeur API. It includes several sub-modules:

The app module contains high-level logic for working with the application as a whole.

Application method from this module gives you access to an instance of the application itself.
The Application method includes several important methods:

-Action_manager for accessing commands from the Commands menu.
-Dialog_manager is used for creating dialog windows for selecting files, asking the user to agree or disagree with something etc.
-Scene_manager allows opening, closing and changing Cascadeur scenes.

Scene _anager, in turn, also contains a number of lower-level methods:

View_scene
Allows changing scene and viewport settings.

Domain_scene
Stores all the main information the user works with in the scene: object structure, animation, selections, animation tracks and their selections.

Domain_scene is usually accessed via the view_scene method, but some other method too provide links to it.

Changes made in the domain scene are done through the modify interface (see below).

Every change is recorded in the command history and can be undone (using the Undo function) or restored (Redo).

Data source manager
Used for saving, loading and import/export scenes.

FBX_import
Handles working with fbx files.

The application method also includes means for accessing tools such as Mirror Tools, Tween Machine etc. App settings are also available through it.

Viewers and Editors

To interact with the scene itself, a number of management functions are used. These functions are known as viewers and editors.

Viewers are used  for reading the data present in the scene:

Model viewer
The main instrument for reading scene data. It provides access to scene objects based on their object IDs. Additionally, it includes two lower-lever viewers:

Data viewer is used for reading data values.
Behavior viewer reads parameters from Behaviors attached to objects.

Viewers are called directly from the scene:

sc.model_viewer().data_viewer()

Editors are for modifying this data:

Model editor
The main editing interface. Like model viewer, it works with scene objects on the basis of their IDs. It also includes four specialized editors:

Data editor modifies data values.
Behavior editor is used for adding, removing and setting up behaviors.
Layer editor is used for working with Animation Tracks and folders.

Update editor
Works with the nodes that make up scene objects. See Node Editor to learn more about this topic.

Editors are called from the model method:

de = model.data_editor()

Editors are accessed via the modify method:

scene.modify(command_name(), mod)

where mod is the name of the function that will receive the editors.

Working With Objects

Once you’ve imported the modules you need, you can start working with the objects in the scene. This can be done in two ways:

If you are using model_editor, all operations with the objects require their IDs:

model_editor.set_object_name(id: csc.model.<object_id>, name: <object_name>)

This method finds an object with the <object_id> ID and changes its name to the value defined by <object_name>.

If you are using update_editor, objects can be interpreted as Python objects that have their own inner methods.

More complex operations require modifying attributes: the object’s inner parameters. These parameters define everything about the object. An object’s type, its name, its coordinates, rotations and scale, its visibility, its place in the hierarchy - these are all attributes.

Attributes are stored within behaviors attached to the object. So to access an attribute, you first need to get the corresponding behavior.

bv = scene.model_viewer().behaviour_viewer()
object_behavior = bv.get_behaviour_by_name(<object_id>, <behavior_name>)

Once you have the behavior, you start working with its attributes:

attribute = scene.get_viewer().get_behavior_data(<behavior>, <attribute>)
where <behavior> is a link to a behavior and <attribute> is a string that defines the name of the attribute to get from this behavior.

Attributes can be modified in the following way:

model.behaviour_editor().set_behaviour_data(<behavior_id>, <behavior_name>, <attribute_value)

And this is how scripts are written in Cascadeur.

Python API Reference

To learn more about using Python, see the API Reference.

Custom Commands

Cascadeur uses a dedicated folder for storing user commands.
The folder can be found by the following address:

When the software is run, it initializes the script files found in this folder, and appends corresponding items to the Commands menu:

Every item in this menu is a command with a corresponding .py file.

For a script file to be recognized as a command, it should follow a certain structure:

1. It should include the command_name() method that returns the name of the command:

2. The script itself should be stored inside the run() method, which will be executed when the command is called:

Reloading Commands

If you make alteration to the script after the software is run, the script won't be automatically updated to reflect these alterations.
You'll have to update it manually by using the Reload scripts command:

The following video shows an example of adding and executing custom commands:

Scripts.mp4 from Андрей Егоров on Vimeo.

Here is the re-export script used in the video:

Sample Scripts

Cascadeur also includes a number of ready-made commands for performing various tasks. Scripts for these commands can be found in the same folder.

These sample script files are located in the dedicated folder by the address:

Script files in the folder.

If you’d like to learn how Python scripting works in Cascadeur, these files can be used as examples.

See Also

API Reference