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.
Frequently-used scripts can be set up as commands. Commands are available through the Commands menu (at any time; you don’t need to open the Python console and load script files to use them.
A command is a .py file that follows several rules.
First: the file should be placed in the following folder:
<Cascadeur main folder>\resources\scripts\python\commands
As the software starts, it will try to load any .py file from this folder and include it in the Commands menu. However, for it to be loaded successfully, it also has to adhere to other rules as well.
Second: a command should include a name.
This means the text of the command script has to include the following procedure:
This function defines the name that will be used to show the command in the menu:
The <name> value is a simple text string.
If you need to put your command to a submenu, this can be done by separating the name of the submenu and the command name with a period:
In this case, the command will be put to a <menu_name> submenu:
Third: the script should include the run(scene) function.
An example of a run(scene) function, taken from the delete_objects.py script included in the standard Cascadeur package.
This function is called when the command is run. All actions that the script performs should be put in this function (of course, other functions can still be called from it).
With these three requirements a script should be recognized as a command, and work without issues.
Cascadeur loads command scripts on startup. You can continue to make changes to the scripts as the software is running, but these changes won’t be automatically reflected in the program.
If you need them to be reflected, you’ll have to manually update the scripts.To do this, select Reload scripts from the Commands menu:
This function will reload every command in the commands folder to the current version.
Cascadeur also includes a number of ready-made commands for performing various tasks.
The scripts for these commands can be found in the following folder:
<Cascadeur main folder>\resources\scripts\python\commands