Programmer Guide

Develop in Rumba with Python

Rumba Python Modules

The Rumba Python API is divided in different modules:

  • rumba is the Python binding of the Rumba C++ API.

  • rumbapy is the a Python module providing different user interface services.

  • Imath is a Python binding of the ILM’s Imath library, providing mathematic objects.

  • fbx provides FBX file format services.

  • rumba_alembic provides Alembic file format services.

  • mtorba is a module accessible from Maya.

Run a Python script using the command line

One way to run a Python script with Rumba is to pass it on the rumba command line.

  • Make sure the rumba application is in your PATH variable.

  • Open your prefered command shell (gitbash gives good results), and run Rumba using the command line like:

rumba my_project.rumba --script my_script.py --no-gui

This command will open the rumba project and then execute the python script. You can specify multiple scripts.

The command outputs will appear in your shell window (into gitbash, not in cmd.exe).

The –no-gui option let you run Rumba with no graphic user interface. Using this option, you can for example open a document, inspect it, modify it, save it or export geometry caches.

Run a Python command using the command line

You can also execute simple python commands specified on the command line :

rumba my_project.rumba --cmd "print('Hello Rumba')" --no-gui

You can use multiple –cmd (or -c) arguments, they all share the same Python environment.

Using the Rumba’s Script window

../_images/script_editor.jpg

The Script Editor

The other solution is to use the Rumba’s Script window.

  • Open Rumba

  • Open the script windows (Windows -> Script).

  • Type some python code

  • Execute it with CTRL+Enter.

The purpose of this editor is simply to run some commands but not to edit a text file. You will probably use your prefered text editor to do that anyway. You can for example source a script file like this:

execfile("my_script.py")

The script editor content is saved with your Rumba preferences.

Execute a Python script at Rumba Start

The first thing you will probably do is running some code at the Rumba start.

To do that, you will have first to set the environment variable RUMBA_USER_PLUGINS with the root path of your Rumba scripts to run.

All the .py files in this folder will be sourced. This is the perfect moment to register your plug-ins or do whatever you want at the Rumba start.

Document management

Load a document

To open a document :

import rumba
rumba.load_document("document.rumba")

Save the document

To save the current document :

import rumba
document = rumba.active_document()
document.write("document.rumba")

Reset a document

To get a fresh new document :

import rumba
rumba.new_document()

Quit Rumba

To quit Rumba :

import rumbapy
rumbapy.quit()

Scene assembly

Create a node

Create, let’s say a SceneGraphNode node (a simple xform node), named ‘group’ in the document root:

import rumba
node = rumba.Node("SceneGraphNode", "group", rumba.active_document())

For details about nodes and plugs, see the rumba.Node class documentation.

Reference a file

Use the reference function to reference a rig file or an alembic cache.

import rumba
doc = rumba.active_document()
rumba.reference(doc, "$(RUMBA_ROOT)/data/creative_seeds/seed2.rumbanode", "")
rumba.reference(doc, "set.abc", "")

Note that you can use environment variables in the file paths.

Update a reference

Let’s say you want to update a rig filename. You can use the Node.replace_reference function, either if the reference is loaded, or not. Here we will replace “Seed” by a “XKLoor” robot.

import rumba

doc = rumba.active_document()

# Get the root node of the reference
seed = doc.child("seed2")

# Change its reference filename
seed.replace_reference("$(RUMBA_ROOT)/data/creative_seeds/xkLoor.rumbanode")

Inspect the document

Let’s iterator over the nodes in the document root :

import rumba
doc = rumba.active_document()
for node in doc.children():
  print(node.name(), node.type_name())

This will print the name and the type of all the root document children nodes.

Set the animation range

Let’s modify the animation limits and the current animation range. We simply set the documents plugs:

import rumba

start = 100
end = 200

doc = rumba.active_document()
doc.start_frame.set_value(start)
doc.end_frame.set_value(end)
doc.range_start_frame.set_value(start)
doc.range_end_frame.set_value(end)

Export the animation

Exporting Asset nodes

The Usd or Alembic exporters exports the scene graph generated by the Asset.display and modified by the optional deformation layers.

Each Asset node has an export_path attribute holding an optional path string like /characters/john. If set, that path will be used by the Usd and Alembic exporters as the path of the asset’s scene graph root node in the exported file.

If the export_path attribute is not set, the Asset.display scene graph is exported has it is.

Export an alembic file

To export the current animation in an Alembic file :

import rumba_alembic, rumbapy
nodes = [] # export all the assets

with rumbapy.Progress("Exporting animation...") as progress:
  rumba_alembic.export_nodes("my_animation.abc", nodes, progress=progress.update)

For more details, see the rumba_alembic.export_nodes() documentation.

Export a .rumbaanim file

The .rumbaanim file format can be used to share animation in Rumba or import the controllers animation back into Maya.

To export the current animation in a .rumbaanim file :

import rumbapy

with rumbapy.Progress("Exporting animation...") as progress:
  rumbapy.export_rumba_animation("my_animation.rumbaanim", progress=progress.update)

For more details, see the rumbapy.export_rumba_animation() documentation.

Import a .rumba or a .rumbaanim file back into Maya

The controllers animation can be imported back on Maya’s referenced rigs using .rumbaanim or .rumba files.

Importing from a .rumba file launches a rumba process to export a temporary .rumbaanim file and then imports it.

To import them back from Maya :

from mtorba.rumbaanim_importer import import_anim

import_anim("my_animation.rumba", False)

For more details, see the mtorba.rumbaanim_importer.import_anim() documentation.

Export a .rumbaanim file from Maya

The Maya controllers animation can be exported back to Rumba using .rumbaanim files.

To export them from Maya :

from mtorba.rumbaanim_exporter import export_anim

export_anim("my_animation.rumbaanim")

For more details, see the mtorba.rumbaanim_exporter.export_anim() documentation.

Export the controllers animation to an FBX file

Let’s export the animation of the rig controllers to an FBX file. No geometry will be written, only the animation of the controllers.

This animation can be then imported in another DCC like Maya or a game engine using an existing rig.

import fbx, rumbapy
nodes = [] # export all the assets
frames = [] # export all the frames
ascii = False # we want a binary FBX file
prefix = True # we want the asset names prefixed by the root node name, like Maya would do

with rumbapy.Progress("Exporting animation...") as progress:
  fbx.export_nodes("my_animation.fbx", nodes, frames, ascii, prefix, progress.update)

For more details, see the fbx.export_nodes() documentation.

Create a playblast

To create a playblast :

def playblast(filename):
    import rumbapy
    from widgets.main_window import MainWindow # non-documented api

    camera = MainWindow.instance().viewports_manager.main_viewport.camera

    overrides = {
            "renderer":{
                "height": 100,
                "width": 100,
                "onion_skin":{
                    "enable": 0
                }
            },
            "audio":{
                "enable": False},
    }

    rumbapy.playblast.playblast_camera(camera, filename, from_frame=None, to_frame=None, overrides=None, single_image=False, player=False)

playblast("playblast.mp4")

Warning

This sample is using a non-documented API. A proper API will be soon available.

For details about playblasts, see the rumbapy.playblast documentation.