Understanding Clarisse Files#

Clarisse files are based on an easy to read ASCII object description format. Each element created in Clarisse is serialized in a file and the sum of this serialization becomes a project or a build file.

There are a very little concepts to understand how Clarisse file structure is formed: entries, comments, and directives.

Please, note the following documentation is for informational purpose only. It does not replace the SDK documentation.

Entries#

In Clarisse, an entry is a name separated by a space and followed by one or multiple values or a group.

Here is an example of entries:

parent "build://project/canyon/renderCam"
aim_distance 33.38
scale 1 1 1

Comments#

A comment should always start with a double slash //, for example:

// this is a comment

Directives#

Project directives are powerful tools for assembling scenes without even the need of opening Clarisse. This way, you can assemble shots from any other application and send them directly to CNode for rendering.

Directives are keywords and function calls placed inside project files. They are executed/evaluated during project loading.

There are 3 kinds of directives:

• pre-processor directives that are executed just before project loading starts (like pre-processor directives in C/C++).
• command directives that are executed just after project loading. They acts like post-process operations in your project when loaded in Clarisse.
• referencing directives that are kept in the project.

You can find a full working example inside directive directory in Clarisse contents.

Path Resolution#

Some directives, such as #include preprocess directive or import_abc command directive, require a file path as argument. When loading a project, Clarisse resolves file paths in the following order:

1. relatively to the path of the project being loaded
2. relatively to the search paths defined in Clarisse or CNode (specified using -search_path command line argument)
3. relatively to the execution directory of Clarisse or CNode

Preprocessors#

As its name suggests, Preprocessor directives preprocess the project file just before Clarisse starts building the project (creating objects, setting attributes...). More and more preprocessor directives will be available in the future.

#include#

This directive is used to copy the content of a specified file and paste it in the exact location where the directive stands.

It basically acts the same way as the C/C++ #include preprocessor directive.

#include "filename"

Unlike in C/C++, this directive only accepts string like file names and not the #include <filename> syntax.

If the path of the specified file is not resolved, the loading of the project stops and Clarisse returns an error. This can happen when the input file is not found.

Remember, preprocessor directives specifying missing files are not ignored and project loading fails.

Usage#

Simplest #include usage example:

Let's imagine we have a project file named simple_include.project which contains:

#include "my_included_project.project"

Loading this file will give the exact same result as loading directly my_included_project.project file.

Another example would be to split your project into elements:

#include "my_image.inc"
#include "my_renderer.inc"
#include "my_shaders.inc"
...
#include "my_geometries.inc"

During project loading, Clarisse assembles all the project's elements into a single one. The file extension .inc is not mandatory: any extensions (even no extension at all) are valid for file inclusion.

Commands#

Command directives are executed just after project loading and can be seen as postprocess operations that are applied to your project.

More and more command directives will be available in the future. Command directives use a function call syntax as following:

directive_name(arg1, arg2, ... ,argN)

Context Sensitivity#

Directives are context sensitive. This means that the context in which they are called may have an impact on the directive result as the holding context is passed to the directive.

For example:

#Isotropix_Clarisse_Project_Version 0.91
directive(arguments)

Execute the dummy directive directive in the root context of the project project://.

However, if we had this:

#Isotropix_Clarisse_Project_Version 0.91
Context "my_context" {
    directive(arguments)
}

Execute the dummy directive directive inside the context my_context

Execution Order#

Command directives are executed following their call order in the project file.

For example, if we have:

directive1(arguments)
directive2(arguments)
directive3(arguments)

Clarisse executes directive1 then directive2 and finally directive3.

Argument Types#

Command directives may optionally make use of arguments. Like in C/C++, directive arguments have types.

Their syntax uses the same syntax as the values of the properties written in project files. The any type means that any types can be used as an argument.

import_abc#

This directive import an Alembic archive inside the context from which the directive is called. It acts the same way using File > Import > Scene.

import_abc(string filename)

Where filename is the filename of the Alembic file to import.

The following example will import the Alembic file my_assets.abc inside the context my_scene.

#Isotropix_Clarisse_Project_Version 0.91
Context "my_scene" {
    import_abc("my_assets.abc")
}

set_value#

This directive sets the value of an object's attribute.

set_value(string attr_value_path, any new_value)

Where:

• attr_value_path is the relative path to the attribute which value will be modified.
• new_value is the new value that will be assigned to the specified attribute.

Depending on the attribute type specified in the Technical tab of the Reference section in this guide, you must type your value argument according to the following rules:

The following example will set the parent attribute of locator1 to locator2.

#Isotropix_Clarisse_Project_Version 0.91
Context "my_scene" {
   Locator {
       name "locator1"
   }
   Locator {
       name "locator2"
   }
   set_value("locator1.parent", "locator2")
}

Referencing and Overrides#

Unlike #include directive, references are kept in the project file. In other words, when saving a project referencing a file, the link is kept in the project.

Reference "trex" {
 options {
   filename "trex.abc"
 }
}

Moreover, local modifications to items in referenced projects are stored as incremental overrides such as:

Reference "trex" {
 options {
   filename "trex.abc"
 }
 overrides {
   object "Trex_jawShape" {
     enable_subdivision_surface yes
   }
 }
}

Here, the only modification made to the reference is that the user activated Enable Subdivision Surface on Trex_jawShape geometry.

Clarisse can also reference directly Alembic assets. It works the exact same way as referencing projects.

Clipboard: copying and pasting#

When you copy one or multiple items in Clarisse, Clarisse basically serializes its current selection to the clipboard.

When you paste in Clarisse, Clarisse looks in the clipboard and build items from the serialization if found.

This is how Clarisse manages copying and pasting between different Clarisse processes.

If you wish to see the serialization of your clipboard coming from Clarisse, copy your selection and paste it in any text editor.

For example:

#Isotropix_Clarisse_Clipboard_Serialization 0.91
CameraPerspective {
   name "renderCam"
   #version 0.9
   copy_from "build://project/canyon/renderCam"
   translate 0.0 0.0 0.0
   rotate 0.0 0.0 0.0
   scale 1 1 1
   parent ""
   constraints ".mot_player"
   aim_distance 33.3820041068195
   field_of_view 50.9822839085102
   embedded_objects {
       ConstraintMotPlayer {
           name "mot_player"
           #version 0.9
           copy_from "project://canyon/renderCam.mot_player"
           active yes
           filename "$PDIR/motion/mn_camera.mot"
       }
   }
}

When Clarisse looks in the clipboard for an available serialization, it first check for #Isotropix_Clarisse_Clipboard_Serialization. This line is mandatory: when it's not there, the paste operation silently fails.