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.
Python console can be enabled by selecting Python console item from the Window menu:
This will open the Python console window.
Opens a .py file containing a Python script and loads it into the console.
Allows you to save the script in the console to a .py file to use it later, or with a different scene.
Closes the console window.
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.
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:
Allows changing scene and viewport settings.
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.
Handles working with fbx files.
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:
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:
Editors are for modifying this data:
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.
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:
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.
To learn more about using Python, see the API Reference.
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:
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:
Here is the re-export script used in the video:
Cascadeur also includes a number of ready-made commands for performing various tasks. Scripts for these commands can be found in the same folder.