Tips to export your environment using mtorba

When animating, having the environment in the background is often useful. Rumba v1.0 handles alembic files, so you can export your set from your favorite 3D modeling software and import it directly into Rumba via the Referencing system (File -> Reference Node).

However, since alembic files are not meant to transfer your shading information from one software to another, your imported set will have the default gray shader. This won’t be a problem anymore when Rumba introduces its USD support.

In the meantime, you can still export sets with basic shading and textures using the mtorba plugin for Maya. For that, you will need to have Autodesk® Maya® and Rumba installed.

First, to prepare your set for export, make sure the geometries composing your set are in the same group and that it is the only group present in your scene.

Then, make sure all the geometries have either a lambert or a blinn material associated with them. Note that you can have multiple materials assigned to one model, as long as they are associated with different face sets. You can also have a File node controlling the colors, but avoid ramps, as it is not a node that is transferable (see the list of supported nodes here).

For your images, the relative paths are resolved and written as absolute paths, meaning that if you change computer and your images are in a different path, they will not be loaded.

So now that you have your basic shading prepared (with or without textures), all you need to do is click on the Export to Rumba button and select where you want to save your file.

Now, you can open Rumba, create a new animation or load an existing one, click on File -> Reference Node and load your exported rumbanode file.

Happy animation!

How to set up and export a rig from Maya to Rumba

Introduction

Welcome to this tutorial on how to set up your Maya rig to export and use it in Rumba. We will use the spiderman rig made by Jirawat Srisarntiwong and Yanin Srisarntiwong (available here) as our sample, download it to follow along.

You will also need to install Autodesk® Maya® with the mGear plugin (that you can find here). The mtorba plugin should self-install with Rumba (follow instructions here). Before starting this tutorial, make sure you have a Rumba shelf in your Maya.

There are a few things to check before you start with the creation of the nodes needed by the mtorba plugin. 

Before anything else, verify that all the parts of the rig (the geo, the rig, the controllers) are all in the same group (if you use the spiderman rig, it should be the case already). This group will be used for the export. In our case, the group is named root and that naming will be a problem later on. To avoid naming conflict, check our naming convention and avoid having nodes named the same way in the rig, even though Maya allows it if they are in different groups. We renamed the group SpidermanRig.

We are now ready to tackle the set up of our export.

Assigning the manipulators

First of all, we have to create links between the manipulators and the existing rig’s controllers.

Select the world_ctl node then, in the Rumba shelf, click on Default Rumba Manipulators. Note that you should have a controller selected for this to work. This step is not mandatory, you can create your own manipulators (cf the Feet Setup section), but you will have more work to do when Rumba incorporates it’s automatic picker creation for example.

This will create a manipulators group containing a bunch of transform nodes. These nodes are all named according to the naming convention defined here. They all have extra attributes that will be interpreted during the export. First, our main concern will be the Rumba Controller Name attribute, which indicates the controller associated with each manipulator. Then, we will cover the arms, legs and hands manipulators, as they are different.

So, for each manipulator in the manipulators’ group, we will select the controller and it’s associated manipulator (the order of your selection has no impact) and click on the association button in the Rumba shelf.

Let’s start with the positioning controllers. Associate them as follows :

rootworld_ctl
worldglobal_C0_ctl
walklocal_C0_ctl
bodybody_C0_ctl
pelviship_C0_ctl

Rumba v1.0.0 : The world manipulator cannot be associated using the described method. For now : fill the Rumba Controller Name attribute of world with the controler name (global_C0_ctl).

Then, let’s move on to the spine controllers. Most of the needed manipulators were automatically created, but here, we will need to tweak that a little bit. Since the spine is a blend of IK and FK, we have to choose if the IK or the FK would be considered the “main” controllers and which ones would be the “sub” controllers. This would be your choice, depending on the habits of your animators. Whatever you choose, the main will be associated with spine0, spine1, spine2, etc., and the others will be spine0_0, spine0_1, spine1_0, spine1_1, spine2_0, etc. For the missing manipulators, either rename those that are unused or duplicate and rename existing ones.

For this particular rig, I chose the IK to be the main controllers, and the FK to be the subs. Here is one possible association :

spine0spine_C0_ik0_ctl
spine2spine_C0_ik1_ctl
spine0_0spine_C0_fk0_ctl
spine0_1spine_C0_fk1_ctl
spine1_0spine_C0_fk2_ctl
spine1_1spine_C0_fk3_ctl
spine2_0spine_C0_fk4_ctl

Next up is the neck, which is also a blend of IK and FK, but the setup is a bit different from the spine setup. Here, the FK is the main control mode, the IK seems to be the sub one. Let’s associate as follows :

neckneck_C0_fk0_ctl
neck0neck_C0_fk1_ctl
neck1neck_C0_fk2_ctl
neck_0neck_C0_ik_ctl

Following that logic, the head controllers are associated as follows :

headneck_C0_head_ctl
jawneck_C0_head_ctl
jaw_0headJaw_C1_ctl
jawupheadBend_C0_ctl
jawup_0headBend_C1_ctl
liddown_0_l (_r)eyeProfile_L3_ctl (eyeProfile_R3_ctl)
lidup_0_l (_r)eyeProfile_L1_ctl (eyeProfile_R1_ctl)
lidup_1_l (_r)eyeProfile_L2_ctl (eyeProfile_R2_ctl)
eye_l (_r)eyeBase_L0_ctl (eyeBase_R0_ctl)
eyecornerin_l (_r)eyeProfile_L0_ctl (eyeProfile_R0_ctl)

Arms setup

The ArmManipulator has its own kind of setup, distinct from the ManipulatorPython. When using the Default Rumba Manipulator creation button, two arm manipulators were created (arm_l and arm_r). They both have four children : hand, arm, elbow and forearm. To create the manipulators for an arm, you won’t have to associate each part of the arm to these children, but you will have to fill in a number of information in the Extra Attributes section of the arm_l and arm_r manipulators.

In order to fill in the ArmManipulator, you need to know how to find the following nodes of the rig :

  • The shoulder, elbow and arm controllers in FK
  • The IK controller
  • Either an IK shoulder controller if there is one, or the skinning shoulder joint
  • The IK shoulder and elbow joints (the start of the joint chain if there is one)
  • The controller and attribute that manages the switch IK/FK
  • The method used to control the orientation of the elbow in IK
    • A pole vector
    • A roll control attribute
    • A roll controller

In our sample rig, you can toggle the visibility of the joints using the Jnt Vis attribute on the SpidermanRig group node (the one we renamed at the start of this tutorial). Once you see the joints, you can toggle the arm to IK mode, move the hand and see the names of the IK joints.

For the IK shoulder controller part, you can use the shoulder orbit controller.

Now that we have all the components needed for the ArmManipulator, let’s start by filling in the names of the FK controllers for the left arm :

Rumba Shoulder Controllerarm_L0_fk0_ctl
Rumba Elbow Controllerarm_L0_fk1_ctl
Rumba Wrist Controllerarm_L0_fk2_ctl

Next, is the IK shoulder and hand controller and the IK shoulder and elbow joints :

Rumba Ik Shoulder Controllershoulder_L0_orbit_ctl
Rumba Ik Targetarm_L0_ik_ctl
Rumba Ik Shoulder Resultarm_L0_0_jnt
Rumba Ik Elbow Resultarm_L0_5_jnt

Since we are looking at the joints, it is a good time to check the orientation of the shoulder and elbow joint. We need the main axis of the joints, which should be the axis that points from the shoulder to the elbow, and the plane normal axis of the elbow, which should be an axis pointing up from that joint (documentation).

Rumba Ik Frontx
Rumba Ik Plane Normalz

When filling the right ArmManipulator, be mindful of the orientation switch. On the right side, the normal plane axis is the one pointing down, not up, and the main axis is probably the opposite of the one defined for the left side (in our case, the Ik Front is -x and the Plane Normal do not change, it is still the z axis).

The next step is the method to orient the elbow. In this exemple, we have both a poll vector and a roll attribute set up. Here are the two possible settings :

Pole VectorRoll Attribute
Rumba Ik Elbow ModePositionAngle
Rumba Ik Elbow Controllerarm_L0_upv_ctlarmUI_L0_ctl.arm_roll
Rumba Ik Elbow Angle MulIgnore1.000

Last, we have to define how to switch between IK and FK, so Rumba can let you manipulate the arm however you want without having to switch. You have to know the limit values for the switch attribute (usually, either 0 to 1 or 0 to 10).

Rumba Ik Switch ControllerarmUI_L0_ctl
Rumba Ik Switch Plugarm_blend
Rumba Ik Switch On1.0
Rumba Ik Switch Off0.0

Once you have your arm manipulator ready for both arms, you may find that there are some controllers that were not used in our setup : the tweak controllers. Those are considered of a lower level than the main arm controllers. For this rig, they are even hidden by default. You can toggle their visibility with the Tweak Vis attribute of the ArmUI_L0_ctl for the left arm.

For these controllers, we will associate them with manipulators directly, using the same nomenclature we used to differentiate the IK and FK spine, meaning, upperarm_0_l (name_number_side).

upperarm_0_larm_L0_tweak0_ctl
upperarm_1_larm_L0_tweak1_ctl
upperarm_2_larm_L0_tweak2_ctl
upperarm_3_larm_L0_tweak3_ctl
elbow_0_larm_L0_mid_ctl
forearm_0_larm_L0_tweak5_ctl
forearm_1_larm_L0_tweak6_ctl
forearm_2_larm_L0_tweak7_ctl
forearm_3_larm_L0_tweak8_ctl

Last of all, we have to associate the shoulder/clavicle controller :

shoulder_lshoulder_L0_ctl

Mirror this to the right side and we are done for the arms.

Legs setup

The leg_l and leg_r manipulators are actually of the type ArmManipulator, meaning, you need to fill in the same information we used for the arms (where the shoulder becomes the hip, the elbow becomes the knee, the wrist becomes the ankle and the hand becomes the foot).

There are two main differences. The Rumba Ik Shoulder Controller is named leg_L0_root_ctl instead of shoulder_L0_orbit_ctl and, if you are using the Angle mode for the elbow orientation, you should be using a Rumba Ik Elbow Angle Mul of 0.035 on both side (you sometimes need to test different values for this multiplier).

For everything else, just replace arm by leg, and your leg setup will be complete.

There are also the tweak controllers to setup :

upperleg_0_lleg_L0_tweak0_ctl
upperleg_1_lleg_L0_tweak1_ctl
upperleg_2_lleg_L0_tweak2_ctl
upperleg_3_lleg_L0_tweak3_ctl
knee_0_lleg_L0_mid_ctl
lowerleg_0_lleg_L0_tweak5_ctl
lowerleg_1_lleg_L0_tweak6_ctl
lowerleg_2_lleg_L0_tweak7_ctl
lowerleg_3_lleg_L0_tweak8_ctl

Last of all, we have to associate the side hip controllers:

hip_lleg_L0_root_ctl

Remember to mirror the set up on the right side.

Hands setup

The last type of manipulator that you can use is the HandManipulators. It allows you to have direct control over all the fingers at once (you can either rotate one phalanx of one finger, all the phalanxes of one finger, one phalanx of all the fingers or all the phalanxes of all the fingers).

You will need to determine three thing to fill in the HandManipulators :

  • The naming pattern of the fingers
  • The name of each finger
  • The name of each phalanx (or number)
  • The fingers’ closing axis (local)

To help you find the naming pattern of the finger, note the name of the first phalanx of the index finger, the thumb and the middle finger, and the last phalanx of the index finger

For this Spiderman, they are : 

  • finger_L0_fk0_ctl
  • thumb_L0_fk0_ctl
  • finger_L1_fk0_ctl
  • finger_L0_fk2_ctl

First, we isolate the parts that don’t change : _fk and _ctl. Then, remark that the names of the fingers are written first, and the phalanxes are numbered from 0 to 2. So the naming pattern can be summarized as {fingerName}_fk{phalanxNumber}_ctl. Replace the {fingerName} by %f and the {phalanxNumber} by %p and you have the correct naming pattern for the fingers : %f_fk%p_ctl

Don’t forget to verify that this pattern stays valid for all fingers.

Looking for the naming pattern allowed us to also find out the names of the individual fingers (finger_L0 to finger_L3 and thumb_L0), and the names given to each phalanx (0 to 2).

For our left hand, you can enter the following information :

Rumba Controller Pattern%f_fk%p_ctl
Rumba Finger Token 0thumb_L0
Rumba Finger Token 1finger_L0
Rumba Finger Token 2finger_L1
Rumba Finger Token 3finger_L2
Rumba Finger Token 4finger_L3
Rumba Phalange Token 00
Rumba Phalange Token 11
Rumba Phalange Token 22
Rumba Axis Closez

If your character has less than 5 fingers, empty the unused fields, they will be ignored. Same goes for the phalanxes.

There are a few controllers left to bind, the metacarpal bones and the cup of the hand. Note that there isn’t a metacarpal controller for the thumb, so you can either skip the metacarpal0_l manipulator or start from it and skip the metacarpal4_l. Since, the thumb is associated with the number 0 in the hand, I decided to skip the metacarpal0_l so there will be no confusion during the painting phase.

metacarpal1_lmetaMid_L0_ctl
metacarpal2_lmetaMid_L1_ctl
metacarpal3_lmetaMid_L2_ctl
metacarpal4_lmetaMid_L3_ctl
handcup_lmeta_L0_ctl

As for the arms and legs, mirror this set up on the right side.

Feet setup

For the feet, we come back to the more classic bindings. We are once again faced with deciding which controllers are deemed to be the main ones and which ones are offsets or finer controls. We can ignore the FK and IK foot main controllers since they are already binded using the leg_l and leg_r ArmManipulators.

First, if we switch between IK and FK, there are some controllers that don’t change, and in IK mode only, there are all the roll and peel controllers. There are no FK only controllers. One possibility is to use the foot and toes manipulators for the controllers that are always present, and to create specific manipulators for the IK only controllers. Another would be either to create specific manipulators for every foot controller or to use the foot_0, heel_0 and toes_0 for the IK controllers.

So, the main controllers will be :

foot_lfoot_L0_fk0_ctl
toes_lfoot_L0_fk1_ctl
toes0_lfoot_L0_fk2_ctl

To create manipulators that are not using a specific nomenclature, you can just select a controller, click on the Create a Manipulator icon and select the actions you want to allow.

Here is a list of selected actions for each of the IK controllers.

Type of manipulator
foot_L0_roll_ctlNo translate
foot_L0_heel_ctlNo translate
foot_L0_tip_ctlNo translate
foot_L0_bk0_ctlNo translate
foot_L0_bk1_ctlNo translate
foot_L0_bk2_ctlNo translate
foot_L0_bk3_ctlNo translate

Do this on the right side, and with that, all the manipulators are associated with their corresponding controllers. The next step is to define which manipulators will be directly associated with a grip on the geometry of our character.

Painting the manipulators

Now that our controllers are associated with manipulators, we can create a map of grips on our model. A grip is a group of the model’s faces that will correspond to a manipulator (and, by extension, a controller). You will be able to control the rig with click and drag motions of those grips, without the need to select a controller.

Since the geometry of our model is a low poly version, we have to make choices on what will be grips on the geometry, and what will be a grip controller (a controller for which the curve acts as a grip). The reflexions we had on which controller set is to be considered to have the broader controls is gonna be useful here. Those controllers will have more surface of grip than their finer counterparts. Depending on the topology of your model, you might not be able to assign faces to all the controllers (without making the result unusable). So some of the finer controllers will probably be left as they are (with the grip property on their curves), while the others will have their corresponding color painted on the mesh.

To start painting on the mesh, select it (you might have to do it in the outliner if, like in our example, it is not selectable) and then click on the Paint Manipulator On Selection button. A popup window will appear with the list of paintable manipulators. Some of those manipulators will be ignored either because they are not the final manipulators (like the arm_l or arm_r that are placeholders, unlike their children) or because they are finer controllers that would clutter the mesh.

When you have finished with the painting of a manipulator, just click again on the Paint Manipulator On Selection button, and select the next manipulator you want to work on.

Here is an example of how to paint the grips on the spiderman mesh. Note that you only need to paint the left part of the mesh, then, you can hit the Mirror Manipulators button to mirror the paint to the right side. First, the trunk :

Then, on to the head :

Then the arm, where we paint the children of arm_l, but not arm_l. We also do not paint all the tweaks (when there is not enough space). For the hand, we indicated the thumb and the pinky parts, remember to paint all fingers, following the logic indicated :

Last of all, the leg:

Once you have painted all the manipulators on the left side of the character, remember to click on the Mirror Manipulators button so you don’t have to repeat the process.

Finishing touches – Optional

You can export your rig now, it is ready to be used in Rumba. In this last part of the tutorial, we will do purely cosmetic work, to clear up the model in Rumba, hiding all the painted controllers’ grips for the animators (without breaking or destroying anything from the rig, to allow debug).

There are several ways you could go about hiding those controllers. One method would be to break their visibility connexions and hide them all manually. Another would be to add some nodes to control the visibility of the controllers, keeping the already present controls of the visibility present.

We will take the left arm as an example of such nodes. For this arm, we want to hide the IK and FK controllers, the hand controllers and the tweaks that were painted, but leave the possibility to show the other tweaks (using the armUI_L0_ctl). We might want to leave the pole vector control for the IK controls (optional).

First, let’s look at the controllers and how their visibility is set. First, the hand’s visibility attribute is not connected to anything, so it will directly be connected to our switch attribute. Let’s create a show_grip_controllers attribute on the world_ctl transform (choose the controller that seems the most logical for you). Set this attribute type to boolean. Using the node editor, connect this new attribute directly to the visibility of each of the hand controls. If you are comfortable with python or mel, don’t hesitate to script these parts as they are extremely repetitive. The rest of the controllers have their visibility controlled one way or another, so they will necessitate a few nodes in between our attribute and their visibility attribute.

In FK, if you select a controller, you will see that it’s visibility attribute is hidden. In these cases, I tend to switch to the node editor view to find how the hidden attributes are controlled. So, for our FK arm, the visibility is linked to a reverse node, that inverts the current FK/IK Blend attribute’s value. So, here, we want to insert a test after the reverse node. We want our controller’s visibility to be on only if the output of the reverse node and the output of our control attribute are true. Since we want to use the Maya nodes that are supported by the export script, we don’t have access to the Math Nodes, so we don’t have boolean operators that would let us create a AND operator. So, we need to use the fact that a boolean is actually an integer with a 0 value when it is false, and 1 when it is true. Testing that both our values are true is the same as verifying that the sum of the two hidden integers is equal to 2.

In the node editor, add the three FK controllers (remove the shapes and keep only the transforms). Click on the Input connexion button to bring up the reverse node they are connected to. Then, add the world_ctl to have access to the show_grip_controllers attribute. Using tab, create an addDoubleLinear node and a condition node. Rename them showFK_L0_Grip_add and showFK_L0_Grip_condition. Connect the output of the reverse node to the input1 of the showFK_L0_Grip_add and the show_grip_controllers attribute to the input2. Connect the output of showFK_L0_Grip_add to the First Term of the showFK_L0_Grip_condition node. In the Attribute Editor of the showFK_L0_Grip_condition, change the Second Term value to 2.000. Since the Color if False and Color if True have inverted values, you can either switch the values (1.0 if True and 0.0 if False), or change the operation attribute to Not Equal. Last, connect the OutputR value of showFK_L0_Grip_condition to the visibility attributes of the FK controllers’ transforms (replacing the previous connexion).

For the IK controllers, it is nearly the same manipulation, to the exception that they are directly controlled by the FK/IK Blend attribute, so we have to create another set of addDoubleLinear and condition nodes, connected the same way, but the input1 input of the addDoubleLinear node is the FK/IK Blend attribute, not the reverse node output.

The last set of controllers we want to hide are the tweaking controllers. Their visibility is switched on and off using the Tweak Vis attribute of the armUI_L0_ctl. To set up our nodes, we need to show them, so let’s set the Tweak Vis to on. Here, be careful not to click on the Output Connections button in the Node Editor when armUI_L0_ctl is selected, it will bring up way more nodes than we want. Instead, select and add the tweak nodes that were painted on the model to the Node Editor. Also add the armUI_L0_ctl and the world_ctl nodes to it. Create the same set of addDoubleLinear and condition nodes we created for the other controllers, connect and rename them with the same logic (changing the connection to the input1 input so it is the Tweak Vis).

You can go on and either do the same steps for all the parts of the rig you want to hide or create a script that will do that for you 🙂

Now, you can export your rig to Rumba and make sure everything works the way it should (especially, verify the manipulators are correctly painted, and that the arms, legs and hands work as intended).

Enjoy!