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.

Commands

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.

Creating Commands

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:

def command_name()
return “<name>”

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:

return “<menu_name>.<command_name>”

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.

Reloading Commands

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.

Standard Commands

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
 

Was this article useful to you?

3
0