Clarisse 5.0 SP5 SDK  5.0.5.5.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Embedding Clarisse in a Python Host

Table of Contents

In this tutorial we show you how to create and run Clarisse inside any Python enabled host.

This is extremely useful when integrating Clarisse in your pipeline. For example you can:

Setup

License Requirements

Creating a Clarisse application embedded in a Python host requires a CNode license. If no CNode license is available then the application will exit.

Environment Variables

You need to add the path to Clarisse Python API to the environment variable PYTHONPATH. This is required so that you can import the Clarisse Python module ix_helper.py from your Python code.

In the following, replace pythonX with:

Windows
set PYTHONPATH=path\to\Clarisse\pythonX;%PYTHONPATH%
Linux and macOS
export PYTHONPATH=path/to/Clarisse/pythonX:$PATH

If using Maya, you need to add or edit the PYTHONPATH variable declared in the file maya.env, located in the user profile directory.

Importing Clarisse Python API

Once all environment variables are properly set, you can import Clarisse Python API from your Python code. To import Clarisse API, there's a dedicated Python module ix_helper.py that you need to import. This file is located inside the python folder found in Clarisse binary folder.

We strongly advise you to import it using the following syntax:

1 from ix_helper import *

Importing the module this way will setup everything as if you were running your script directly from Clarisse's Script Editor.

Creating the Application from Python

When running a Python script in Clarisse, the application object is already created. However, when you import Clarisse API in a Python host, you must create an application instance before being able to call Clarisse APIs.

The module ix_helper provides the helper function create_application(modules) to do just that.

The mandatory argument modules specifies a path, or path list, to Clarisse built-in modules, and possibly external ones.

Example:

1 from ix_helper import *
2 create_application('path/to/clarisse/module`)
3 # From this point you can call Clarisse APIs from "ix" and "ix.api"

A Working Example

In the following example we will:

  1. Create a Clarisse application.
  2. Load a project.
  3. Render an image.
  4. Save the rendered image to a file.
1 # Import Clarisse Python API to have access to all of "ix" and "ix.api"
2 from ix_helper import *
3 
4 # Create the Clarisse application instance
5 create_application('C:/Program Files/Isotropix/Clarisse 5.0/Clarisse/module')
6 
7 # Load a project
8 ix.load_project('D:/work/my_project.project')
9 
10 # Render an image at the current frame
11 render = ix.render_image('project://scene/image')
12 
13 # Save the resulting image as an 8 bit PNG to the specified path on disk
14 ix.save_png8(render, 'D:/work/render/image')

Known Limitations

Troubleshooting

In this section we describe additional setup steps that were required in Clarisse 4.0 or older. These steps shouldn't be necessary anymore in 5.0 but we keep this section to help you troubleshot potential problems.

If Python fails to load Clarisse libraries or fails to import Clarisse Python API, you might need to add or edit the following environment variables:

For example, if PATH is incorrect you'll get an error similar to this:

>>> from ix_helper import *
Traceback (most recent call last):
...
ImportError: DLL load failed: The specified module could not be found.

For PATH, you can edit the environment variable directly, or you can edit it in your Python code directly like follows:

1 import os
2 os.environ["PATH"] += os.pathsep + 'C:/Program Files/Isotropix/Clarisse 5.0/Clarisse'

Similarly, for PYTHONPATH, you can edit the environment variable, or you can edit it in your Python code directly like follows:

1 import sys
2 sys.path.insert(1, 'C:/Program Files/Isotropix/Clarisse 5.0/Clarisse/python3')