2D-3D Integration

Maximize your creative production power.

Start learning animation for free today with Harmony trial version.
Take the opportunity to experiment.

Harmony Premium Harmony Premium
Harmony Premium Harmony Premium
Download your free trial now

Harmony Stage provides you with impressive 2D-3D integration possibilities. This feature allows you to combine the two animation genres within the same production resulting in some remarkable scene composition and a unique style.

Refer to the Chapter 2D-3D Integration in the Harmony User Guide for more in-depth explanations and step-by-step instructions.

2D-3D Integration Basics

Toon Boom Plug-in for Autodesk®Maya®

Autodesk®Maya® can produce 3D model exports which are compatible with Toon Boom Harmony.

You will first need to install the necessary plug-in to be able to export your 3D models to *.osb files which is the format recognized by Toon Boom Harmony.

  • To obtain the appropriate Toon Boom 3D plug-in for Autodesk®Maya® and its installation instructions, please contact support at support@toonboom.com with all of the following information
    • The version of Autodesk®Maya® you are working with.
    • The operating system you are working in, Windows or Mac OS X.
    • The complete build number of Toon Boom Harmony you are using. Please send the full build number, i.e. 9.2.0.xxxx. You can access this number in the Help > About menu.

Installing the Toon Boom 3D plug-in for Autodesk®Maya®

When you receive the plug-in, follow the installation instructions in the Readme_install file included with the package.

The contents of the plug-in package should be as follows:

The next time you will export a 3D model from Autodesk®Maya®, the TBExport option will be available from the Files of Type drop-down menu.

If you are have any difficulties installing the Toon Boom 3D plug-in for Autodesk®Maya®, please contact support@toonboom.com.

Exporting a 3D Object for Harmony Using Maya

Once you set up Toon Boom Harmony and your system for the use of 3D, the next step would be to generate the 3D models you plan to import and use in your scene. You will need to use Autodesk®Maya® for this.

Make sure you have installed and loaded the necessary plug-in from Toon Boom prior to taking the following steps.

To export a 3D object for Harmony:

  1. In Autodesk®Maya®, create your 3D object.
    You should also complete the texturing of your 3D object, as well as set up a few lights in your scene. When you render your scene later through Harmony, it will use this original Maya® scene to render with the shaders, textures, and lighting of the scene.

    When you animate the object in Harmony, it will use this scene file and push the animation from Harmony into this scene. For this reason you may want to parent your lights to your object so that the lighting that you've set up moves with the object when it's animated. If not, you may end up with a situation where the object is rotated out of the lighting, and you can see a very dark 3D object. In Maya®, you can parent one layer to another by middle-mouse clicking and dragging that layer.
  2. Save your Maya binary file *.mb as you will use it later on.
  3. Use the export command to export your model. File > Export All.
  4. The Export All dialog box opens.
  5. In the Files of type drop-down menu, select TB3DExport.
  6. When you complete the export, a *.osb file will be created.

Instructions may differ depending on the version of Autodesk®Maya® which you have. It is therefore important that you refer to the their documentation for correct instructions on how to create and export a 3D model.

Importing a 3D object from Autodesk Maya to Harmony

Once you have exported a model in *.osb file format using Autodesk®Maya®, you can import it into Harmony Stage and integrate it to your 2D animation scene.

To import 3D model(s) from Autodesk®Maya® into Harmony Stage:

  1. In Harmony Stage, select File > Import > 3D Models.
  2. The Import 3D Models dialog box opens.
  3. Use the Browse button and locate your *.osb file(s) on your computer.
  4. Click on Open to validate your choice and close the browsing window.
  5. In the Import 3D Models dialog box, choose your import options and click on OK to validate your choices and import the selected file(s).

The 3D Model(s) will be imported in your scene.

Note that, if at this point, the Preview mode is set to Render View  then the 3D model will not be visible in the Camera view. If this is the case, click on the Open GL View  button, you should now be able to see your 3D model(s).

Refer to the 2D-3D Integration chapter in the Harmony User Guide to learn more about the import options and 3D rendering in Harmony Stage.

Using Peg Modules to Control the Position of 3D Objects

You can use Peg modules to control the position of 3D objects, and connect them peg modules together as you would with 2D layers to create rigs.
Refer to the Chapter Building a Character > Rigging in the Harmony User Guide to find out more about this topic.

Manipulating the 3D Object

Once you have imported the 3D model into your scene, you can easily manipulate it to setup your scene. You can even add keyframes, just like any other elements and animate it on a trajectory.

This topic is divided as follow:

  • Enabling the 3D Option
  • Using Transformation Tools to Manipulate the 3D Models

Refer to the following chapters of the Harmony User Guide to learn more:

  • Setting Up the Scene
  • Working in a True 3D Space
  • Creating Animation Paths

Enabling the 3D Option

To rotate the 3D model in three axes instead of two, you must enable the 3D option in the layer properties. By default, the new layers in Harmony Stage display only the 2D options, allowing you to only move them as flat layers.

To enable the 3D option:

  1. In the Timeline view, select the 3D model layer you want to move in the 3D space.
  2. Click on the selected layer once, to display its properties in the Layer Properties view, or double-click on it to open its properties in a dialog box.
  3. In the Layer Properties dialog box, click on the Transform tab.
  4. Click on the Enable 3D option checkbox to display the 3D parameters for that particular layer.
  5. Click on the Close button.

New parameters appear in the Layer Properties window.
Refer to the chapter Working in a True 3D Space > Enabling the 3D Option > 3D Parameters in the Harmony User Guide to learn more about these 3D parameters.

Using Transformation Tools to Manipulate the 3D Models

Once the 3D option is enabled, your Transformation tools automatically become 3D Transformation tools, this means that you can now manipulate them on the Z-axis as well. The Translate , Rotate  and Scale  tools are found in the Advanced Animation toolbars and the Transform  tool can be found in the Tools toolbar. You can use these tools to set up or animate your 3D model. Note that if you want to set up the position of your 3D model, you must disable the Animate  mode. Do not forget to re-enable it when if you want to animate it.

It is recommended to enable the bounding box selection style in the preferences panel. The default selection style highlights your element, while at the same time hiding the skin and lighting of your 3D element. The bounding box selection style will create a 3D box around your selected element without interfering with its display.

To enable the Bounding Box Selection Style preference:

  1. Open the Preferences panel:
    • Windows/Linux: Select Edit > Preferences or use the default keyboard shortcut [Ctrl]+[U] (Windows/Linux).
    • Mac OS X: Select Stage > Preferences or use the default keyboard shortcut [z]+[U] (Mac OS X).
  2. Choose the Camera tab.
  3. In the Tools section, enable the Bounding Box Selection Style preference.

This section explains how the following tools behave in 3D mode:

  • Translate Tool
  • Rotate Tool
  • Scale Tool
  • Transform Tool

  Translate Tool
Once you enable the 3D option, the 3D Translate tool becomes available. Direction arrows will appear around the pivot points to indicate the different axes.

If you click on a direction arrows you can move your layer on only one axis. If you click anywhere else, the layer can move freely on two axes at once. Once the arrow is selected, it will turn pink.

If you move the layers in the Perspective view, it may be difficult to control the motion, since you may not have the optimum point of view on your stage to understand the setup. In this case it is best to use the direction arrows to move the layers.

  Rotate Tool
Once you enable the 3D option, the 3D Rotate tool becomes available. A rotation sphere appear will around the pivot points to indicate the different axes.

You can click on the direction ellipses to rotate your layer on one axis only. If you click anywhere else, the layer rotates freely on two axes at once. Once the ellipse is selected, it will turn pink.

If you move the layers in the Perspective view, it may be difficult to control the motion since you may not have the optimum point of view on your stage to understand the setup. In this case it is best to use the direction ellipses.

  Scale Tool
Once you enable the 3D option, the 3D Scale tool is available.

You will see one of two things:

  • A Scaling Rectangle, this appears if your drawing is flat.
  • A Scaling Cube, this appears if your object has some rotated layers around the pivot points, indicating the different axes. If you click and drag on this Scaling Cube, it will scale proportionally on all axes.

Click on one of the three control points to scale the shape on one axis. Hold down the [Shift] key to scale the object proportionally. Once the control point is selected, it will turn pink.

If you move the layers in the Perspective view, it may be difficult to control the motion since you may not have the optimum point of view on your stage to understand the setup.

  Transform Tool
Once you enable the 3D option, the 3D Transform tool become available. This tool is a combination of the 3D Translate, 3D Rotate and 3D Scale tools.

  • Translating an Element
    To translate an element, grab the Direction Arrows in the same way that you would with the Translate tool.
  • Rotating an Element
    To rotate an element, grab the Rotation Ellipses in the same way that you would with the Rotate tool.
  • Scaling an Element
    To scale an element, grab the Scaling Control Points in the same way that you would with the Scale  tool. If you click and drag on this Scaling Cube, it will scale proportionally on all axes.
    You can also set up all these position parameters using the Layer Properties dialog box.

Refer to the chapter Working in a True 3D Space > Enabling the 3D Option > 3D Parameters 
in the Harmony User Guide to learn more about these 3D parameters.

Refer to the following topics in the Creating Animation Paths chapter of the Harmony User Guideto learn more about managing, setting and animating parameters and function curves:

  • Function Curves
  • Layer Parameters
  • Creating a Function
  • Function View
  • Creating Function Curves
  • Function Drop-down Menu
  • Function Types

Rendering and Compositing 3D Models

To be able to render the 3D objects you imported in Harmony Stage through Autodesk®Maya® soft render, you will need to prepare your system by establishing some precise environment variables and setup your network view in Harmony.

This section is divided as follows:

  • Preparing the Project Directory
  • Setting Up the Environment Variable On Windows
  • Setting Up the Environment Variable and Script on Mac OS X
  • Setting Up the Network View

This section is very technical, if you need help or experience problems while setting up the 3D rendering, please contact Toon Boom Harmony support at support@toonboom.com

Preparing the Project Directory

To set up rendering:

  1. Copy your original Maya binary file  *.mb into your Harmony project directory at the same location as the *.osb file you have imported. This *.osb file should be in the elements folder, inside a subfolder named like the element. For example: if the element is called PirateShip then the subfolder should be named PirateShip.
    You saved the Maya *.mb file in the Exporting a 3D Object for Harmony Using Maya section of this document.
  2. Rename the *.mb file so it has the same name as the *.osbfile. For example: if the *.osb is called PirateShip-1.osb , the name the *.mb as PirateShip-1.mb.
  3. Copy any textures used in the Maya® project into this same folder.

Setting Up the Environment Variable On Windows

The next step is to set up the Environment Variable to assign the port for rendering on Windows.

To set up the environment variable on Windows:

The System Properties dialog box opens.

You can browse to the installation folder of Maya® and copy the complete path to the bin folder from the explorer browsing window to make sure you have the exact path.

If you receive an error readout in the command line when you try to render, please contact support at support@toonboom.com and provide the error readout content.

Setting Up the Environment Variable and Script on Mac OS X

If you are working on Mac OS X, you need to set up a TOONBOOM_MAILBOX environment variable like Windows and a script that will call Maya®.

Setting Up the Environment Variable
Follow these steps to set up the environment variable on Mac OS X.

To set up the environment variable on Mac OS X:

Creating and Setting Up the Script
Follow these steps to create the script to call Maya® and set to it up.

To create the script and set it up:

Setting Up the Network View

Now that your environment variables have been properly set up, you need to take the final step and prepare your network to call the Autodesk®Maya® rendering utility. Once it is done, you will be able to render the 3D objects in your Toon Boom Harmony project and preview them in the Camera view in Render View  mode. This will allow you to composite your scene and effects efficiently.

There are two types of script module that work with the Harmony-Maya connection:

This module uses the script renderMayaBatch();
This script starts up a Maya Batch session, renders the 3D elements on that frame, then closes the session. It will open and close the session for every frame to be rendered.

This script starts up a Maya Batch session that stays open so that when you render 3D objects through multiple frames, it does not close the session between each of them.

To prepare the project network:

You are now all set to render your animation project.
Refer to the chapter Exporting Your Movie in the Harmony User Guide to learn about the different export options and parameters available in Toon Boom Harmony.

  1. In Windows, Go to Start > Right click on Computer and select Properties from the pop-up menu.
  2. From the Computer Properties dialog box, select Advanced System Settings.
  3. In the System Properties dialog box, click on the Environment Variables button.
    The Environment Variable dialog box opens.
  4. The first variable to set up is the Maya® path. Browse down in the System Variables section until you find the variable called Path and select it.
  5. Click on the Edit button. The Edit System Variable dialog box opens.
  6. Add a semi-colon [;] at the end of the last path in the Variable value field.
  7. Copy the path to the bin folder of Maya following the semi-colon.
    For example: For Autodesk®Maya® 2011 on Windows, that path would read:
    C:\Program Files\Autodesk\Maya2011\bin
  8. Click on OK to validate this environment variable and go back to the Environment Variables dialog box.
  9. The second variable to set up is a new system variable.
  10. Click on the New button. The New System Variable dialog box opens.
  11. Set up the new variable:
    • In the Variable name field, type in TOONBOOM_MAILBOX .
    • In the Variable value field, type in any available port. For this example, we will try port 7778. (If the port you chose is already taken, you will receive an error readout in the command line when you try to render.)
  12. Setting Up the Environment Variable
  13. Creating and Setting Up the Script
    1. Using Terminal, open the folder .MacOSX. This is a hidden folder, so you need to open it using the line cd; open .MacOSX
    2. If the folder does not exist, you need to create it:
      mkdir .MacOSX
    3. Navigate to the .MacOSX folder and create the environment.plist file.
      You can use the following lines:
      cd .MacOSX/
      touch environment.plist
      sudo vim environment.plist
    4. Type in your password to be able to edit the file
    5. Once you're in the text editor, type "i" to go to insert mode
    6. Copy or type the following text into the environment.plist file:
      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
      <plist version="1.0">
      <dict>
           <key>TOONBOOM_MAILBOX</key>
           <string>7778</string>
           <key>PATH</key>
           <string>/usr/local/bin:/bin</string>
      </dict>
      </plist>
    7. When you have finished copying the text into the plist file, type Esc :wqto save and quit the vi text editor.
      If you receive an error readout in the command line when you try to render, please contact support at support@toonboom.com and provide the error readout content.
    1. From the Terminal, we want to create a file that we can save the script in.
    2. You may create this file in either /usr/local/bin or ~/bin.  If you save it in usr/local/bin, then all users will be able to render on that machine. If you create the file in ~/bin, then only the current user will be able to render from that machine.
    3. First, change directory to the directory where you want to create the script file:
      cd /usr/local/bin
    4. If the directory bin doesn't exist yet, then create it:
      mkdir /usr/local/bin
    5. We will now create the script file called maya:
      sudo vim maya
    6. type in your password to grant administrator access
    7. Now from inside the text editor, select "i" to go to Insert Mode, and copy and paste the following text:
      #!/bin/bash
      exec /Applications/Autodesk/maya2012/Maya.app/Contents/MacOS/Maya "$@"
    8. Save and exit by typing in:
      Esc :wq
    9. Now we need to edit the file to make sure that all users can access it. Type in:
      chmod ugo+x maya
      • Render Maya Batch
      • >Render Maya Batch Server
    1. Launch Toon Boom Harmony. It is recommended to run it from command line, this way, you will have a printout of the process as it renders. Once it is launched, you might also want to display the Message Log view.
    2. In the Network view, locate your 3D object module.
    3. In the Module Library, select either the RenderMayaBatch or RenderMayaBatchServer module and drag it to the Network view.
    4. In the Network view, hold the [Alt] key down while dragging the Maya render module right under the 3D object module to connect it.
    5. Repeat Step 3 and Step 4 for each 3D object module in your scene.
    6. In the Camera view, click on the Render View  button.
    7. All the elements of your scene will appear in this complete preview of the rendered scene.
    8. If it does not render as expected, run Toon Boom Harmony from the command line and see if you received an error readout when clicking on the Render View button. Email this information to support@toonboom.com.
    9. If you want to add effects filters modules to your 3D object, make sure to connect them right under the Maya® render module.